Feature Define

feature-define

Creates the two artifacts every project feature MUST have:

1. ai-context/features/<slug>.md — the authoritative domain knowledge.

2. .claude/skills/<slug>/SKILL.md — the antenna that activates on

triggers and forces a read of the markdown.

>

Both are scaffolded from skills/_templates/feature/ in the global

agent-config repo. The antenna is a pure pointer — it never duplicates

markdown content.

Triggers: /feature-define, define feature, nueva feature, documentar feature, documentar funcionalidad, new feature scaffolding

---

Process

Step 0 — Guardrails

1. Refuse to run inside the agent-config repo itself. Detect via file_exists("install.sh") AND dir_exists("skills/_shared") OR basename(cwd) == "agent-config". If true, emit:

"feature-define only runs inside consumer projects. The agent-config

repo holds the templates, not project features."

Stop.

2. Require a consumer project root: dir_exists(".claude") AND file_exists("CLAUDE.md"). If either is missing, emit:

"Run /project-setup first — this project is not configured for Claude

Code yet."

Stop.

3. Locate templates at ~/.claude/skills/_templates/feature/. Required files:

• _template.md — the 6-section domain knowledge template.
• SKILL.md.template — the antenna skill template.

If either is missing, emit:

"Templates not found at ~/.claude/skills/_templates/feature/. Re-run

install.sh in your agent-config repo to deploy them."

Stop.

---

Step 1 — Gather feature information

Ask the user, one question at a time. STOP and wait between questions.

1. Feature name (human-readable, e.g. "Checkout Flow"). Derive feature_slug = lowercase + hyphens (e.g. checkout-flow). Validate:

• Slug matches ^[a-z][a-z0-9-]*$. Reject otherwise.
• ai-context/features/<slug>.md does NOT already exist. If it does,

ask: "A feature file already exists for <slug>. Open it, overwrite, or pick a new slug?" Default: open.

• .claude/skills/<slug>/ does NOT already exist. Same handling.

2. One-line purpose: what user problem does this feature solve?

3. Sub-flows or subpages (optional, multi-line): list each with a one-line description. Used to populate the Domain Overview bullets.

4. Triggers: keywords or phrases that, when the user mentions them, should activate the antenna skill. Suggest defaults derived from the feature name; let the user confirm or extend. Comma-separated.

5. External integrations (optional, multi-line): systems/APIs this feature talks to. Used to pre-populate the Integration Points table header — the user fills the details later.

Do NOT ask for business rules, decisions, or gotchas at scaffolding time. Those are filled in as the feature is built and learned.

---

Step 2 — Generate the markdown

1. Read ~/.claude/skills/_templates/feature/_template.md. 2. Replace the title <Feature Name> with the user's feature name. 3. Set Last updated by: to the git user name (read from git config user.name; fallback to "human"). 4. Set Last run: to today's date (YYYY-MM-DD). 5. Pre-populate the Domain Overview placeholder with:

• The one-line purpose from Step 1.
• A bullet list of sub-flows from Step 1 (if provided).

6. If integrations were provided in Step 1, leave the Integration Points table header in place and add one empty row per integration with the system name pre-filled. 7. Keep all [auto-updated] markers intact — they are required by the contract (see feature-domain-expert Pattern 4). 8. Write to ai-context/features/<slug>.md. Create the directory if absent.

---

Step 3 — Generate the antenna skill

1. Read ~/.claude/skills/_templates/feature/SKILL.md.template. 2. Replace placeholders:

• {{feature_slug}} → the slug from Step 1.
• {{feature_name}} → the human-readable name.
• {{triggers}} → comma-separated triggers from Step 1.

3. Write to .claude/skills/<slug>/SKILL.md. Create the directory if absent.

---

Step 4 — Register the antenna in the project CLAUDE.md

1. Read the project's CLAUDE.md. 2. Locate the ## Force-read inline section. If a sub-section "Feature skills (project-local)" does NOT exist below it, create it with this header:

   ### Feature skills (project-local)

   Each feature with non-trivial domain logic has an antenna skill that
   forces a read of `ai-context/features/<slug>.md` when its triggers fire.

   | Feature | Antenna | Domain knowledge |
   |---------|---------|------------------|

3. Append a row for the new feature:

   | <Feature Name> | `.claude/skills/<slug>/SKILL.md` | `ai-context/features/<slug>.md` |

4. If the Force-read inline section does not exist at all in the project CLAUDE.md, do NOT auto-create it — emit a warning instead:

"Project CLAUDE.md has no '## Force-read inline' section. Add the

Feature skills block manually (template available in

docs/templates/project-claude-template.md)."

---

Step 5 — Summarize and next steps

Emit:

Created:
  - ai-context/features/<slug>.md  (domain knowledge — fill in business
    rules, integrations, gotchas as you learn them)
  - .claude/skills/<slug>/SKILL.md (antenna — auto-activates on triggers:
    <triggers>)

Registered in: CLAUDE.md → Force-read inline → Feature skills (project-local)

Next steps:
  1. Open ai-context/features/<slug>.md and add at least one Business Rule
     (BR-1). Empty feature files are noise.
  2. Restart Claude Code to pick up the new antenna skill in
     available-skills.
  3. When the feature ships its first change, use /sdd-propose <change> —
     the markdown will be preloaded automatically via slug matching.

---

Rules

• MUST NOT run inside the agent-config repo. Templates live there; features

do not.

• MUST refuse if the project is not Claude-configured (no .claude/ or

CLAUDE.md).

• MUST use the canonical 6-section template — never invent new sections.

The contract is owned by feature-domain-expert.

• MUST preserve [auto-updated] markers in the generated markdown so

codebase-teach can later coexist without overwriting human content.

• The antenna skill MUST remain a pure pointer. If the user asks to embed

domain content in the skill, refuse and direct them to edit the markdown instead.

• MUST NOT pre-populate Business Rules, Decision Log, or Known Gotchas.

Those grow as the feature is built — pre-filling creates fake history.

• MUST register the antenna in the project CLAUDE.md when a Force-read

inline section exists; emit a warning otherwise (no silent skip).