diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 28f6f1f..b7c9a6c 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -79,15 +79,15 @@ Include: keywords users say, questions they ask, symptoms they describe, tool na ## 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. +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 | +| 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. @@ -96,9 +96,10 @@ All fields are optional. Skills without them work unchanged. ```yaml --- name: brainstorm-synthesis -version: 1.1.0 +version: 1.1.1 category: planning model-hint: opus +stability: experimental next-skill: ship requires: - skill:brainstorming @@ -109,13 +110,17 @@ triggers: **`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. +offers the handoff when its task is complete — the user confirms before the next skill +runs. This is a suggestion, not an auto-chain; the LLM should never silently invoke the +next skill without user awareness. **`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. +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:** +**Annotated chains in this repo** (source skills only — downstream commands like +`verify-fix` can't declare `requires` back, and terminal skills like `ship` are +invokable standalone): - `brainstorming → brainstorm-synthesis → ship` (planning) - `systematic-debugging → verify-fix` (debugging) diff --git a/plugins/core/skills/CLAUDE.md b/plugins/core/skills/CLAUDE.md index 0d28f5e..481a5c8 100644 --- a/plugins/core/skills/CLAUDE.md +++ b/plugins/core/skills/CLAUDE.md @@ -83,8 +83,9 @@ Core principle: If you can't explain WHY it's broken, you're not ready to fix it 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 `/`). +**`next-skill`**: The skill or command to offer as a handoff after this one completes. +Use the bare name (same as the slash command without `/`). The LLM surfaces this as a +suggestion — the user confirms before the next skill runs. Never auto-invoke silently. ```yaml next-skill: ship @@ -107,8 +108,9 @@ Options: `sonnet`, `opus`, `haiku`. model-hint: opus ``` -**`stability`**: Maturity marker. Omit for `stable` (default). Mark `experimental` when -behavior may change or the skill is under active development. +**`stability`**: Maturity marker — `stable` (default) or `experimental`. Omit for stable +skills. Mark `experimental` when behavior may change or the skill is under active +development. ```yaml stability: experimental diff --git a/plugins/core/skills/brainstorm-synthesis/SKILL.md b/plugins/core/skills/brainstorm-synthesis/SKILL.md index 1e4fdfc..c39b28f 100644 --- a/plugins/core/skills/brainstorm-synthesis/SKILL.md +++ b/plugins/core/skills/brainstorm-synthesis/SKILL.md @@ -2,9 +2,10 @@ 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.1.0 +version: 1.1.1 category: planning model-hint: opus +stability: experimental next-skill: ship requires: - skill:brainstorming