Problem
Our skills currently chain via prose. `brainstorming` ends with "now run /ship". `do-issue` says "hand off to /wrap-up when the PR merges". This works but is fragile: prose is easy to drift, hard to introspect, and impossible for the harness to act on. A skill cannot declare upfront "my output feeds skill X with these args" — so we cannot build dashboards of skill flows, validate chains exist, or have the harness auto-route handoffs.
We want frontmatter-level declarative composition.
Reference: prior art
oh-my-claudecode (https://github.com/yeachan-heo/oh-my-claudecode) skills declare composition in frontmatter:
```yaml
pipeline: [deep-interview, omc-plan, autopilot]
next-skill:
next-skill-args: { ... }
handoff: .omc/specs/{slug}.md
```
Their runtime appends a "Skill Pipeline" section to the skill's loaded content so handoff happens automatically. We should evaluate whether this maps to our marketplace-plugin model.
Research task (do this before writing code)
This is the part we don't know — and the implementer should investigate before deciding the design:
- What does Claude Code natively support in skill frontmatter today? We currently use `name`, `description`, `triggers`. Are there other documented or undocumented fields the harness reads? See https://docs.claude.com/en/docs/claude-code/skills and the plugin docs.
- Can we extend frontmatter with custom fields the harness ignores but our hooks/commands can read? If yes, that unlocks declarative chaining without harness changes.
- Is there a hook lifecycle event (e.g. SkillStart, SkillEnd, post-Stop) that could read these fields and inject the next skill into context?
- Compare with how Cursor rules / our own `alwaysApply` field work — we already extend frontmatter; what's the precedent.
What to build (after research)
An expanded frontmatter schema for our skills. Candidate fields (final list TBD by research):
- `pipeline:` — declared chain this skill participates in
- `next-skill:` — automatic handoff target
- `next-skill-args:` — structured payload to pass forward
- `handoff:` — file path where state is written for the next skill to pick up
- `requires:` — prerequisite skills/tools/MCP servers
- `model-hint:` — preferred model tier (sonnet/opus/haiku) when delegated to subagent
- `cost-tier:` — cheap/medium/expensive (for cost-aware orchestration)
- `stability:` — stable/experimental (for opt-in gating)
Pick the subset that's actually useful and implementable. Don't build all of them.
Concrete value
These chains in our repo would benefit immediately:
- `brainstorming → writing-plans → executing-plans → ship`
- `do-issue → wrap-up → cleanup-worktree`
- `debug → systematic-debugging → verify-fix`
- `upgrade-deps → multi-review → ship`
Open questions
- Backwards compatibility: skills without the new fields must keep working unchanged.
- Validation: do we lint frontmatter at install time (`/ai-coding-config doctor`?) or runtime?
- Discovery: should `/load-rules` or a new command surface the chain graph?
- Does this need a hook to actually drive handoff, or is it just metadata for humans/LLMs to read?
Success criteria
- At least 3 of our existing skill chains use the new frontmatter end-to-end.
- An LLM reading a skill knows what to do next without us writing it in prose.
- No existing skill breaks.
- The schema is documented in `.claude/CLAUDE.md` alongside our existing frontmatter conventions.
Problem
Our skills currently chain via prose. `brainstorming` ends with "now run /ship". `do-issue` says "hand off to /wrap-up when the PR merges". This works but is fragile: prose is easy to drift, hard to introspect, and impossible for the harness to act on. A skill cannot declare upfront "my output feeds skill X with these args" — so we cannot build dashboards of skill flows, validate chains exist, or have the harness auto-route handoffs.
We want frontmatter-level declarative composition.
Reference: prior art
oh-my-claudecode (https://github.com/yeachan-heo/oh-my-claudecode) skills declare composition in frontmatter:
```yaml
pipeline: [deep-interview, omc-plan, autopilot]
next-skill:
next-skill-args: { ... }
handoff: .omc/specs/{slug}.md
```
Their runtime appends a "Skill Pipeline" section to the skill's loaded content so handoff happens automatically. We should evaluate whether this maps to our marketplace-plugin model.
Research task (do this before writing code)
This is the part we don't know — and the implementer should investigate before deciding the design:
What to build (after research)
An expanded frontmatter schema for our skills. Candidate fields (final list TBD by research):
Pick the subset that's actually useful and implementable. Don't build all of them.
Concrete value
These chains in our repo would benefit immediately:
Open questions
Success criteria