From 1f10d63e5e05f055c8b25371138bb03ffb7acf1c Mon Sep 17 00:00:00 2001 From: Nick Sullivan Date: Mon, 4 May 2026 18:05:20 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=E2=9C=A8=20Add=20declarative=20composition?= =?UTF-8?q?=20frontmatter=20to=20skills?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduces four optional frontmatter fields for skill composition: - next-skill: happy-path handoff target (skill or command name) - requires: prerequisites as skill:/tool:/mcp: entries - model-hint: preferred model tier when delegated as a subagent - stability: stable|experimental maturity marker Annotates three existing chains: - brainstorming → brainstorm-synthesis (model-hint: sonnet) - brainstorm-synthesis → ship (model-hint: opus, requires: brainstorming) - systematic-debugging → verify-fix (model-hint: opus) Documents the schema in .claude/CLAUDE.md and plugins/core/skills/CLAUDE.md. No existing skills break — fields are optional and harness-ignored. Fixes #52 Co-Authored-By: Claude Opus 4.7 --- .claude/CLAUDE.md | 43 +++++++++++++++++++ plugins/core/skills/CLAUDE.md | 35 +++++++++++++++ .../core/skills/brainstorm-synthesis/SKILL.md | 6 ++- plugins/core/skills/brainstorming/SKILL.md | 4 +- .../core/skills/systematic-debugging/SKILL.md | 4 +- 5 files changed, 89 insertions(+), 3 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 1fd352d..79101a2 100644 --- a/.claude/CLAUDE.md +++ b/.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` | list | Prerequisites in `skill:name`, `tool:name`, or `mcp:name` format | +| `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 diff --git a/plugins/core/skills/CLAUDE.md b/plugins/core/skills/CLAUDE.md index 31ed5d6..ed26238 100644 --- a/plugins/core/skills/CLAUDE.md +++ b/plugins/core/skills/CLAUDE.md @@ -78,6 +78,41 @@ 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 list of `skill:name`, `tool:name`, or `mcp:name` +entries. + +```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 `|`) diff --git a/plugins/core/skills/brainstorm-synthesis/SKILL.md b/plugins/core/skills/brainstorm-synthesis/SKILL.md index 5023ce0..1e4fdfc 100644 --- a/plugins/core/skills/brainstorm-synthesis/SKILL.md +++ b/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" diff --git a/plugins/core/skills/brainstorming/SKILL.md b/plugins/core/skills/brainstorming/SKILL.md index 008c471..1de188d 100644 --- a/plugins/core/skills/brainstorming/SKILL.md +++ b/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" diff --git a/plugins/core/skills/systematic-debugging/SKILL.md b/plugins/core/skills/systematic-debugging/SKILL.md index e916ea9..e1d6278 100644 --- a/plugins/core/skills/systematic-debugging/SKILL.md +++ b/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" From 056c3d7664044e17e686cde4907265d90026b72b Mon Sep 17 00:00:00 2001 From: Nick Sullivan Date: Mon, 4 May 2026 18:10:11 -0500 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20Fix=20bot-review=20issues=20?= =?UTF-8?q?in=20skill=20frontmatter=20PR?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add stability: experimental to mcp-debug to demonstrate the field - Clarify requires is a YAML sequence (not a comma-separated string) - Add note that commands don't have SKILL.md so can't declare requires Co-Authored-By: Claude Opus 4.7 --- .claude/CLAUDE.md | 2 +- plugins/core/skills/CLAUDE.md | 5 +++-- plugins/core/skills/mcp-debug/SKILL.md | 3 ++- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 79101a2..28f6f1f 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -85,7 +85,7 @@ 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` | list | Prerequisites in `skill:name`, `tool:name`, or `mcp:name` format | +| `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 | diff --git a/plugins/core/skills/CLAUDE.md b/plugins/core/skills/CLAUDE.md index ed26238..0d28f5e 100644 --- a/plugins/core/skills/CLAUDE.md +++ b/plugins/core/skills/CLAUDE.md @@ -90,8 +90,9 @@ name (same as the slash command without `/`). next-skill: ship ``` -**`requires`**: Prerequisites, as a list of `skill:name`, `tool:name`, or `mcp:name` -entries. +**`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: diff --git a/plugins/core/skills/mcp-debug/SKILL.md b/plugins/core/skills/mcp-debug/SKILL.md index 5bbd7f9..42abe48 100644 --- a/plugins/core/skills/mcp-debug/SKILL.md +++ b/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"