Skip to content

🐛 Address review feedback from PR #55 #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TechNickAI wants to merge 2 commits into
base: main
Choose a base branch
from
Open

🐛 Address review feedback from PR #55 #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1f1f5b4
🐛 Address review feedback from PR #55 - Clarify next-skill convention…
May 5, 2026
c32caae
📝 Clarify annotated chains: only source skills are annotated
May 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 18 additions & 13 deletions .claude/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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)
Expand Down
10 changes: 6 additions & 4 deletions plugins/core/skills/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
3 changes: 2 additions & 1 deletion plugins/core/skills/brainstorm-synthesis/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down