Declare a model for each agent skill stage

[V3RON]

Why

No skill in .claude/skills/ names a model, and work-issue delegates every stage to a general-purpose subagent without choosing one. So each stage runs on whatever model the session uses. An Opus session spends Opus on implementing and on device tests, which are mostly mechanical. A Sonnet session reviews and triages on Sonnet, where catching problems matters most. On #96 the implement phase started on Opus and had to be stopped by hand and restarted on Sonnet.

Expected outcome

Each stage runs on its declared model however it starts: delegated by work-issue, run as a slash command, or loaded by another agent.

A skill's model: frontmatter on its own is not enough (evidence in the comments). Claude Code applies it only when a person types the slash command. When a skill is loaded through the Skill tool, which is how work-issue and subagents load them, the run stays on the caller's model. A skill with model: plus context: fork runs in its own subagent on the declared model, whichever way it is started.

Skill	Frontmatter
design-feature, triage-issue, review-pr, review-memory	model: opus, context: fork
implement-issue, e2e-device	model: sonnet, context: fork
file-issue, cut-release	model: sonnet, no fork
work-issue, architecture, writing-changelog, writing-user-docs	none

file-issue interviews a person, and cut-release waits for an explicit yes. Both need the conversation, so they stay inline: their model applies when typed as a slash command, and they run on the caller's model when loaded through the Skill tool. work-issue runs on the model the person starts it with. The three writing and rule skills load inside other stages, so they must not change that stage's model.

work-issue delegates each stage by invoking its skill with the Skill tool and passing the issue, the branch and the task as arguments. It stops starting a general-purpose agent that then loads the skill. A forked skill starts without the conversation, so the arguments must carry everything the stage needs.

The Skills table in AGENTS.md gains a Model column and a Forked column, which are the one list to edit when the mapping changes.

Constraints and non-goals

• Use the aliases (opus, sonnet), not dated model IDs, so the mapping follows new releases without edits.
• work-issue never passes a model override. A model given when starting a subagent wins over the skill's model, which would undo this change.
• If an organisation's availableModels excludes a declared model, Claude Code silently falls back to the session model. That is acceptable and needs no handling.
• Non-goal: OpenCode. It ignores this frontmatter, and its stages keep running on the session model.
• Non-goal: changing what any skill does, beyond work-issue's delegation mechanics.

How we know it is done

1. Every skill's frontmatter matches the table above.
2. AGENTS.md's Skills table has Model and Forked columns matching the frontmatter.
3. A check that runs in CI fails when a skill's model: or context: disagrees with AGENTS.md, or when a skill in .claude/skills/ is missing from the table.
4. work-issue invokes each stage's skill with the Skill tool and arguments, and still receives that skill's report block.
5. The PR shows headless runs (claude -p … --output-format json, whose modelUsage lists the models used) proving these routes:
   • From a Sonnet session, loading review-pr through the Skill tool runs it on Opus.
   • From an Opus session, loading implement-issue through the Skill tool runs it on Sonnet.
   • A forked skill receives the arguments it was invoked with.

Alternatives considered

• model: alone in each skill: ignored whenever the skill is loaded through the Skill tool, so it never applies to work-issue's stages.
• One .claude/agents/<stage>.md per stage with its model: works for delegated runs, but a typed /review-pr also needs an inline model:, so each stage's model would live in two places.
• work-issue naming the model in each delegation: a skill run on its own would get no model.

[V3RON]

Tested before implementing. model: in a skill's frontmatter on its own switches the model only when a person types the slash command. A skill loaded through the Skill tool stays on the caller's model. context: fork fixes that, and so does a per-stage agent definition. I've updated the body to use context: fork.

How it was tested: a worktree of main with this issue's frontmatter plus two probe skills, on Claude Code 2.1.281. I ran headless claude -p --model <session> --output-format json for each probe and read the models used from modelUsage and the transcripts. The transcripts confirm each skill loaded from the worktree's edited copy.

#	Session	Route	Declared	Ran on
1	Sonnet	general-purpose subagent → Skill tool review-pr	opus	Sonnet
2	Opus	general-purpose subagent → Skill tool implement-issue	sonnet	Opus
3	Sonnet	general-purpose subagent → Skill tool architecture	none	Sonnet
4	Sonnet	subagent with Agent model: haiku → Skill tool review-pr	opus	Haiku
5	Sonnet	Skill tool review-pr in the main loop	opus	Sonnet
6	Sonnet	typed /model-probe	opus	Opus
7	Sonnet	Skill tool model-probe in the main loop	opus	Sonnet
8	Sonnet	general-purpose subagent → Skill tool model-probe	opus	Sonnet
9	Sonnet	Skill tool, skill with model: opus + context: fork	opus	Opus
10	Sonnet	Agent tool, .claude/agents/agent-probe.md with model: opus	opus	Opus

When a skill loads through the Skill tool, the transcript records the declared model (command_permissions.model: claude-opus-5-5), but the next reply still runs on the session model. Row 4 shows that a model given when starting a subagent takes effect. That's why the body says work-issue must never pass one.

---

Generated by Claude Code

[V3RON]

Addendum: this issue also sets reasoning effort per stage, through an effort: frontmatter field. It behaves exactly like model:.

Evidence. Each run was a headless Sonnet session at --effort high. A PreToolUse hook logged the effort field that Claude Code passes to hooks for the current turn. Every probe declared effort: low.

Route	Effort used
No skill (control)	high
Inline skill, loaded through the Skill tool	high (ignored)
Inline skill, typed as a slash command	low
Skill with context: fork, loaded through the Skill tool	low
.claude/agents/*.md with effort: low, through the Agent tool	low
General-purpose subagent loading a skill with no effort:	high (inherited)

Valid values are low, medium, high, xhigh and max. The Claude Code docs don't cover per-skill or per-agent effort yet. I found it by checking the installed Claude Code 2.1.281, so it could change.

Amended table

Skill	Frontmatter
design-feature, triage-issue, review-pr, review-memory	model: opus, effort: high, context: fork
implement-issue	model: sonnet, effort: medium, context: fork
e2e-device	model: sonnet, effort: low, context: fork
file-issue	model: sonnet, effort: medium, no fork
cut-release	model: sonnet, effort: low, no fork
work-issue, architecture, writing-changelog, writing-user-docs	none

Because file-issue and cut-release are not forked, their effort applies only when typed as a slash command, the same as their model.

Amended criteria

• Criterion 2: AGENTS.md's Skills table also gets an Effort column.
• Criterion 3: the CI check also compares effort:.
• Criterion 5 adds one proof: from a session at --effort high, e2e-device loaded through the Skill tool runs at low. A PreToolUse hook that logs effort shows it.

---

Generated by Claude Code

[V3RON]

#110 sets model:, effort: and context: fork on each skill as in the amended table. work-issue now delegates through the Skill tool with arguments. A new pnpm check:skills step in CI keeps the AGENTS.md Model, Effort and Forked columns in sync with the frontmatter.

Verified with headless runs on 2.1.281. From a Sonnet session, review-pr ran on Opus. From an Opus session, implement-issue ran on Sonnet. From a session at high effort, e2e-device ran at low, as the PreToolUse hook log shows. Each fork echoed a nonce from its arguments. The PR has had no agent review.

---

Generated by Claude Code