✨ Add declarative composition frontmatter to skills

[TechNickAI]

Summary

• Introduces four optional skill frontmatter fields for declarative composition: next-skill, requires, model-hint, and stability
• Annotates three existing skill chains with the new fields
• Documents the schema in both .claude/CLAUDE.md (dev guide) and plugins/core/skills/CLAUDE.md (skill-creation guide)

Design Decisions

Why only four fields (not all eight proposed in the issue):
pipeline, next-skill-args, handoff, and cost-tier were omitted. They add complexity without immediate runtime value — next-skill alone handles 80% of the composition signal. Fewer fields → easier to adopt, easier to keep consistent.

No new infrastructure:
Claude Code's harness ignores unknown frontmatter fields. The LLM reads next-skill as part of the skill content and invokes the handoff. This is exactly how triggers, category, and version already work — proven pattern, zero harness changes required.

requires format (skill:name, tool:name, mcp:name):
Machine-parseable prefix makes future /ai-coding-config doctor validation straightforward without any ambiguity about what type of dependency is declared.

Annotated chains

Chain	Skills
Planning	brainstorming → brainstorm-synthesis → ship
Debugging	systematic-debugging → verify-fix

Complexity

balanced

Validation

• Frontmatter YAML validated by pre-commit hook (passed)
• All existing skills unchanged — fields are optional, absent = same behavior as before
• validate-marketplace CI check covers plugin manifest

Fixes #52

[claude]

Code Review

Clean, well-scoped PR. The four-field design is the right call — next-skill alone handles the key composition signal, and the skill:name/tool:name/mcp:name prefix convention for requires is machine-parseable without being over-engineered.

Strengths

• Consistent with existing patterns — triggers, category, version all work the same way (harness ignores, LLM reads). No new infrastructure required.
• Backward compatible — optional fields, absent = unchanged behavior.
• Version bumps are correct — minor bump for non-breaking additions of optional fields.
• Dual-location documentation — good call documenting in both .claude/CLAUDE.md (dev guide) and plugins/core/skills/CLAUDE.md (skill-creation guide).

Issues

verify-fix is only partially annotated in the documented chain

The PR describes systematic-debugging → verify-fix as an annotated chain, and systematic-debugging gets next-skill: verify-fix. But verify-fix/SKILL.md isn't touched — it doesn't get requires: [skill:systematic-debugging] or even a stability field. The chain is only declared from one side.

Compare: brainstorm-synthesis correctly declares requires: [skill:brainstorming] completing the bidirectional declaration. The debugging chain is missing the return leg.

Suggest adding to verify-fix/SKILL.md:

requires:
  - skill:systematic-debugging

stability field is documented but never demonstrated

All four fields appear in the docs, but zero annotated skills use stability. That makes it abstract — readers can't see what an annotated experimental skill looks like. Since the composition mechanism itself is new, any of the three annotated skills could reasonably be marked stability: experimental to demonstrate the field and signal that the convention may evolve.

Nit

The docs table lists requires type as list. Consider adding a one-liner clarifying it's a YAML sequence (- skill:name entries), not a comma-separated string. This is obvious to YAML-fluent readers but not to everyone authoring SKILL.md files.

Summary

Merge-ready after addressing verify-fix. The stability demo is a nice-to-have but not blocking. Solid foundation for future /ai-coding-config doctor validation.

[TechNickAI]

Fixed in 056c3d7:

• stability demo: added stability: experimental to mcp-debug — it's genuinely more of a diagnostic/evolving skill than the stable planning/debugging chains.
• requires type: updated both docs to say "YAML sequence" instead of "list", with - skill:name format made explicit.
• verify-fix requires: Declining — verify-fix is a command (.claude/commands/verify-fix.md), not a skill with a SKILL.md. Commands don't participate in the composition schema. Added a note to plugins/core/skills/CLAUDE.md explaining this asymmetry so future authors know why the back-link is absent.

[claude]

Code Review

Clean, minimal PR with solid documentation. The proven-pattern approach (harness-ignores, LLM-reads) is the right call for zero-infrastructure adoption. A few things worth considering:

The brainstorming → brainstorm-synthesis → ship chain is aggressive

ship's own SKILL.md says: "When the user says 'ship it', DO IT — don't ask for confirmation at every step." That's intentional for ship when invoked directly, but it's a sharp edge when reached via an auto-chain from a brainstorming session. A user who runs /brainstorming to explore options may not expect the LLM to eventually invoke a skill that commits and pushes code without pausing.

Since this is LLM-driven the model should use judgment, but there's no documented expectation about when the LLM should follow next-skill vs. surface it as a suggestion. Worth adding a line to the next-skill docs, e.g.: "The LLM offers the handoff rather than invoking it silently — user confirms before the next skill runs."

Asymmetric chain annotation

brainstorm-synthesis declares requires: skill:brainstorming ✓
systematic-debugging has no requires field ✗

If requires is the canonical way to document inbound dependencies, both chain entries should be symmetric for future /ai-coding-config doctor validation to work consistently. Either add requires to systematic-debugging or note in the docs that requires is optional even within a chain.

verify-fix and ship not annotated

The downstream targets get next-skill traffic but have no composition frontmatter themselves. This is fine for now since the fields are optional, but the doc section "Annotated chains in this repo" implies both ends are documented — slightly misleading. Consider noting that only chain sources are annotated, or add symmetric requires to the targets.

Minor: stability default not shown in the schema table

The .claude/CLAUDE.md table describes stability as stable (default), but the SKILL.md guide only says "Omit for stable (default)." Consistent wording across both docs would help — currently one uses a table cell and the other uses prose.

---

Overall this is a solid foundation. The machine-parseable skill:/tool:/mcp: prefix on requires is a good forward-looking choice. The chain aggressiveness question is the only thing I'd want explicit guidance on before merging, since it affects user trust in the automation.

[TechNickAI]

Addressed in PR #57. Fixed: next-skill handoff convention (safety), stability: experimental demo, docs wording consistency. Declined: verify-fix requires (it is a command, not a skill — commands cannot declare requires back) and systematic-debugging requires (chain source with no upstream prerequisites).

[TechNickAI]

Triage of this review:

1. Chain aggressiveness — Already addressed in 1f1f5b4. The next-skill convention now explicitly states: "the user confirms before the next skill runs. This is a suggestion, not an auto-chain."

2. Asymmetric chain annotation — Incorrect analysis. requires declares inbound dependencies (what runs before you). systematic-debugging is a chain source with no inbound dependency to declare — it correctly has only next-skill.

3. verify-fix and ship not annotated / "Annotated chains" misleading — Valid. verify-fix is a command (can't have SKILL.md frontmatter), ship is a terminal node invokable standalone. Clarified the "Annotated chains" section with a parenthetical note explaining why only source skills are annotated.

4. stability wording inconsistency — Already aligned in 1f1f5b4. Both docs now use consistent language.