✨ Add declarative composition frontmatter to skills

.claude/CLAUDE.md

@@ -77,6 +77,49 @@ triggers:
 
 Include: keywords users say, questions they ask, symptoms they describe, tool names.
 
+## Skill Composition Frontmatter
+
+Optional fields for declarative composition. The Claude Code harness ignores them;
+the LLM reads them as part of the skill content and acts accordingly.
+
+| Field | Type | Purpose |
+|---|---|---|
+| `next-skill` | string | Happy-path handoff — the skill or command to invoke after this one completes |
+| `requires` | YAML sequence | Prerequisites; each entry is `skill:name`, `tool:name`, or `mcp:name` |
+| `model-hint` | string | Preferred model tier when delegated as a subagent: `sonnet`, `opus`, or `haiku` |
+| `stability` | string | `stable` (default) or `experimental` — signals maturity for opt-in gating |
+
+All fields are optional. Skills without them work unchanged.
+
+**Example — planning chain:**
+
+```yaml
+---
+name: brainstorm-synthesis
+version: 1.1.0
+category: planning
+model-hint: opus
+next-skill: ship
+requires:
+  - skill:brainstorming
+triggers:
+  - "synthesize approaches"
+---
+```
+
+**`next-skill` convention:** Use the bare skill/command name (same as the slash command
+without the `/`). Commands and skills are both valid targets. The LLM reads this and
+invokes the next skill when its task is complete — no new infrastructure required.
+
+**`requires` convention:** Use `skill:name` for skill dependencies, `tool:name` for
+Claude Code tools (Read, Bash, etc.), `mcp:name` for MCP servers. Informational for
+now; `/ai-coding-config doctor` can validate these in the future.
+
+**Annotated chains in this repo:**
+
+- `brainstorming → brainstorm-synthesis → ship` (planning)
+- `systematic-debugging → verify-fix` (debugging)
+
 ## Command Update Protocol
 
 When a user runs `/ai-coding-config update`, after pulling the latest changes from this

plugins/core/skills/CLAUDE.md

@@ -78,6 +78,42 @@ Core principle: If you can't explain WHY it's broken, you're not ready to fix it
 [Rest of skill content...]
 ```
 
+## Composition Fields (Optional)
+
+These fields let skills declare their place in a workflow. The Claude Code harness
+ignores them; the LLM reads and acts on them as part of the skill content.
+
+**`next-skill`**: The skill or command to invoke after this one completes. Use the bare
+name (same as the slash command without `/`).
+
+```yaml
+next-skill: ship
+```
+
+**`requires`**: Prerequisites, as a YAML sequence of `skill:name`, `tool:name`, or
+`mcp:name` entries. Note: `next-skill` can target both skills and commands; commands
+(`.claude/commands/*.md`) don't have SKILL.md files and can't declare `requires` back.
+
+```yaml
+requires:
+  - skill:brainstorming
+  - tool:Bash
+```
+
+**`model-hint`**: Preferred model tier when this skill runs as a delegated subagent.
+Options: `sonnet`, `opus`, `haiku`.
+
+```yaml
+model-hint: opus
+```
+
+**`stability`**: Maturity marker. Omit for `stable` (default). Mark `experimental` when
+behavior may change or the skill is under active development.
+
+```yaml
+stability: experimental
+```
+
 ## Critical Constraints
 
 - **Single line descriptions** - Claude Code doesn't parse block scalars (`>` or `|`)

plugins/core/skills/brainstorm-synthesis/SKILL.md

@@ -2,8 +2,12 @@
 name: brainstorm-synthesis
 # prettier-ignore
 description: "Use when facing hard architectural decisions, multiple valid approaches exist, need diverse perspectives before committing, or want M-of-N synthesis on complex problems"
-version: 1.0.0
+version: 1.1.0
 category: planning
+model-hint: opus
+next-skill: ship
+requires:
+  - skill:brainstorming
 triggers:
   - "brainstorm synthesis"
   - "f-thread"

plugins/core/skills/brainstorming/SKILL.md

@@ -2,8 +2,10 @@
 name: brainstorming
 # prettier-ignore
 description: "Use when rough ideas need design before code, requirements are fuzzy, multiple approaches exist, or you need to explore options before implementation"
-version: 0.4.0
+version: 0.5.0
 category: planning
+model-hint: sonnet
+next-skill: brainstorm-synthesis
 triggers:
   - "brainstorm"
   - "design session"

plugins/core/skills/mcp-debug/SKILL.md

@@ -2,8 +2,9 @@
 name: mcp-debug
 # prettier-ignore
 description: "Use when testing MCP servers, debugging MCP tool responses, exploring MCP capabilities, or diagnosing why an MCP tool returns unexpected data"
-version: 1.0.0
+version: 1.1.0
 category: debugging
+stability: experimental
 triggers:
   - "mcp"
   - "test mcp"

plugins/core/skills/systematic-debugging/SKILL.md

@@ -2,8 +2,10 @@
 name: systematic-debugging
 # prettier-ignore
 description: "Use when debugging bugs, test failures, unexpected behavior, or needing to find root cause before fixing"
-version: 1.2.0
+version: 1.3.0
 category: debugging
+model-hint: opus
+next-skill: verify-fix
 triggers:
   - "debug"
   - "investigate"