From 1f1f5b4b31b05ae2853aabc9b631c2a2faacf1b8 Mon Sep 17 00:00:00 2001 From: Hex Sullivan Date: Tue, 5 May 2026 11:06:50 +0000 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=90=9B=20Address=20review=20feedback?= =?UTF-8?q?=20from=20PR=20#55=20-=20Clarify=20next-skill=20convention:=20L?= =?UTF-8?q?LM=20offers=20handoff,=20user=20confirms=20(safety)=20-=20Add?= =?UTF-8?q?=20stability:=20experimental=20to=20brainstorm-synthesis=20(dem?= =?UTF-8?q?onstrates=20the=20field)=20-=20Align=20stability=20wording=20be?= =?UTF-8?q?tween=20dev=20guide=20and=20skill-creation=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/CLAUDE.md | 27 ++++++++++--------- plugins/core/skills/CLAUDE.md | 10 ++++--- .../core/skills/brainstorm-synthesis/SKILL.md | 3 ++- 3 files changed, 23 insertions(+), 17 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 28f6f1f..88e4456 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,11 +110,13 @@ 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:** 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 From c32caae1d3d668e2f303918501544992afd18ed3 Mon Sep 17 00:00:00 2001 From: Hex Sullivan Date: Tue, 5 May 2026 11:11:45 +0000 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=9D=20Clarify=20annotated=20chains?= =?UTF-8?q?:=20only=20source=20skills=20are=20annotated?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Downstream commands (verify-fix) can't declare requires back since they lack SKILL.md frontmatter, and terminal skills (ship) are invokable standalone without inbound dependency declarations. Co-Authored-By: Claude Opus 4.6 --- .claude/CLAUDE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 88e4456..b7c9a6c 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -118,7 +118,9 @@ next skill without user awareness. 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)