helm skill
Advisor-orchestrated in-session build loop. The session model (the strongest model you have, or a new SOTA model you want to evaluate) acts as planner + advisor + reviewer; implementation is delegated to cheaper subagent models. Derives a verifiable completion condition up front and interviews the user if one can't be derived. Supports saved model-routing profiles (/helm <profile-name>, /helm profile save ...), a model-intel refresh (/helm refresh) that audits locally available models against Artificial Analysis data, and a ledger report (/helm evaluate) that measures cost savings and per-model performance. Use when the user says /helm, 'helm this', 'advisor loop', 'run the advisor loop', 'you plan, delegate the build', 'helm profile', 'helm refresh', 'helm evaluate', or wants the top model orchestrating while lesser models implement. NOT a scheduled loop: it runs inside the current session until the goal check passes.
- GitHub stars
- 6
- Files
- 5
- Last commit
- Sep 2, 2026
- License
- MIT
- Allowed tools
- —
What does the helm skill do?
helm is an agent skill. Advisor-orchestrated in-session build loop. The session model (the strongest model you have, or a new SOTA model you want to evaluate) acts as planner + advisor + reviewer; implementation is delegated to cheaper subagent models. Derives a verifiable completion condition up front and interviews the user if one can't be derived. Supports saved model-routing profiles (/helm <profile-name>, /helm profile save ...), a model-intel refresh (/helm refresh) that audits locally available models against Artificial Analysis data, and a ledger report (/helm evaluate) that measures cost savings and per-model performance. Use when the user says /helm, 'helm this', 'advisor loop', 'run the advisor loop', 'you plan, delegate the build', 'helm profile', 'helm refresh', 'helm evaluate', or wants the top model orchestrating while lesser models implement. NOT a scheduled loop: it runs inside the current session until the goal check passes.
How to install the helm skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the helm skill in Claude Code
~/.claude/skills/helm/SKILL.md
$ npx degit Jacknelson6/helm ~/.claude/skills/helmInstall the helm skill in Claude Code (project)
.claude/skills/helm/SKILL.md
$ npx degit Jacknelson6/helm .claude/skills/helmInstall the helm skill in Codex
~/.agents/skills/helm/SKILL.md
$ npx degit Jacknelson6/helm ~/.agents/skills/helmInstall the helm skill in Gemini CLI
~/.gemini/skills/helm/SKILL.md
$ npx degit Jacknelson6/helm ~/.gemini/skills/helmInstall the helm skill in Claude.ai
npx degit Jacknelson6/helm helm && zip -r helm.zip helm # claude.ai → Customize → Skills → + → Create skill → Upload a skill → helm.zip
SKILL.md
View on GitHubHelm — advisor-orchestrated build loop
You (the session model) are the advisor: you plan, set the goal, dispatch work, review every result, and decide when it's done. You do NOT write the implementation yourself. Implementation is done by delegated subagents on a cheaper model tier. The loop lives entirely in this session: no scheduled wakeups, no cron, no background daemons. It ends when the completion check passes or a real blocker needs the user.
Division of labor. Helm is provider-agnostic: tiers are roles, and each maps to whatever your provider or harness offers (Anthropic, OpenAI, xAI, Zhipu/GLM, Google, local models, or a mix):
| Role | Tier | Notes |
|---|---|---|
| Advisor / orchestrator / reviewer | session model, or a strong-tier subagent on routine runs (see references/routing.md) | plans, chunks, reviews diffs, resolves ambiguity; the session model always owns the completion condition and the exit check |
| Implementer (default) | mid tier | scoped build chunks with clear acceptance criteria |
| Implementer (hard chunks) | strong tier | cross-cutting refactors, tricky state/async, anything the mid tier failed once |
| Bulk mechanical | small tier | renames, codemods, no judgment |
Tier examples: Anthropic haiku / sonnet / opus; OpenAI mini-or-nano / standard / frontier-or-reasoning; xAI Grok mini / standard / frontier; GLM air / standard / frontier; Google Flash-Lite / Flash / Pro. Use whatever identifiers your harness accepts for its subagent model parameter. If your harness cannot run subagents on a different model, run implementers as fresh scoped workers on the same model: you lose the cost split but keep the discipline (chunking, independent review, verifiable exit), which is most of the value.
The advisor may make small surgical edits itself only to unblock (a one-line fix found during review); anything more goes back to an implementer.
Token economics (make the savings real)
Helm's overhead is real: each subagent carries its own system prompt and re-reads files the advisor also touched, so a helm run burns roughly 1.3-1.5x the raw tokens of a solo run. The savings come entirely from rate arbitrage, so protect it:
- Every dispatch names a cheap tier explicitly, including scouts. Harness defaults inherit the SESSION model, so a read-only explore agent dispatched without a model override silently bills at advisor rates. Measured leak on a real run: ~120k advisor-tier tokens on one codebase-mapping scout that should have cost mid-tier money. Exploration, planning research, and mechanical work all go out with the model parameter set; the only thing that runs on the session model is the advisor's own reasoning.
- Review diffs, not files. The advisor reviews with
git diffplus targeted greps/snippet reads. Never re-read whole files an implementer already processed; if broad reading is needed, that's a scout dispatch on the cheap tier. - Don't helm single-chunk tasks. Below ~2 chunks the advisor's planning and review overhead dominates and a solo session is cheaper. Rule of thumb: helm pays when the implementer tier is at least 2x cheaper per token than the session model AND the task splits into 2+ delegable chunks.
- Route the advisor seat itself. The session model is the priciest token in the loop; on routine pattern-following runs a strong-tier subagent runs the whole advisor loop and the session model only sets the completion condition and verifies the exit. The four routes, the triage rubric, and the break-even math all live in references/routing.md (the single source for those numbers; do not restate them here).
- Stay on plan-billed subagents, and confirm before leaving the plan.
Every dispatch, including the delegated advisor, defaults to the harness's
built-in subagent mechanism (Claude Code: the Agent tool), so it bills
inside the existing subscription; helm never needs out-of-band API calls.
The presence of an API key in the environment (OPENROUTER_API_KEY,
OPENAI_API_KEY, ANTHROPIC_API_KEY, ...) is availability, NOT consent: keys
often exist for the product under development, not for helm's own spend.
Route dispatches through a metered API only when the user explicitly chose
it, either in this run's confirmation or on a profile's
billing:line. If both a subscription lane and a usable key could serve a chosen model and the user hasn't said which, ask once (one short question), then record the answer in the state file and, if a profile is active, offer to save it to the profile so the question never repeats. - Undispatchable models need a lane: ask for the OpenRouter key. When a
chosen model (a profile seat, a Custom pick, or an inline mention) is not
in the harness inventory (references/model-intel.md section 1), the
subscription lane cannot serve it and the only way to run it is a metered
gateway; helm's gateway is OpenRouter. Resolve
OPENROUTER_API_KEYfrom the environment, else from<skill-dir>/.env.local. If neither has it, stop BEFORE any dispatch and ask one question: name the seats the harness can't run, say an OpenRouter key is required to use them, and offer two options: (a) addOPENROUTER_API_KEY=...to<skill-dir>/.env.local(gitignored; see README setup) or export it, then reply "ready"; (b) swap those seats to the nearest dispatchable models for this run (name them). Never ask for the key in chat, never echo it, never write it to a tracked file, state file, or log. Once the key resolves and the user has chosen (a), that choice IS the explicit consent: recordbilling=api:openrouteron theModels:line, offer to save it to the active profile, and run those seats as scoped workers through OpenRouter's chat-completions endpoint (same self-contained dispatch prompt, token counts from the response's usage field into the ledger). Seats the harness can dispatch stay on the subscription lane; the key only pays for the ones it can't. - Record tokens so the claim is auditable. Each log line carries the
harness-reported subagent token count, one line per agent, updated in
place on follow-ups (never a second "cumulative" line, which double-counts
the run). At exit, write the single machine-parseable
Totals:line (see references/dispatch-and-review.md for both formats). A run that can't show its split can't prove it saved anything. - Declare the run's economics. A run with a cheap implementer tier is a
savingsrun: the split is the point, and advisor share should stay at or below roughly 30% of total tokens. A run where the user picks a strong-tier implementer (e.g. the escalation model builds everything) is aqualityrun: it costs MORE than solo and buys independent review, chunk discipline, and a verifiable exit instead. Both are legitimate; record which one this is (economics=in the Totals line) so the run is judged against its own purpose, and never present a quality run as having saved tokens. Tier check before tagging: if the implementer's blended price is not at least ~2x cheaper than the advisor's, the run cannot honestly besavings; tag itquality. Measured (Aug 2026): an Opus-5-implementer run tagged savings returned only a ~10% saving, half the fleet median.
Current recommended stack, from the cached Artificial Analysis snapshot in
references/model-intel.md (refreshed 2026-09-02;
when the snapshot is over ~30 days old, note that in the plan confirmation
and offer /helm refresh, but never block a run on it):
| Tier | Single-provider (e.g. Claude Code) | Cross-provider harness |
|---|---|---|
| Orchestrator / advisor | session model (Claude Fable 5.1 or Opus 5) | Claude Fable 5.1 or Opus 5 |
| Builder (mid) | Claude Sonnet 5 | GLM-5.3-Flash (new; GPT-5.6 Terra if you want a proven builder) |
| Escalation (strong) | Claude Opus 5 | Grok 4.6 or Claude Opus 5 |
| Mechanical (small) | Claude Haiku 4.5 | DeepSeek V4 Flash or GLM-5.3-Flash |
Cross-provider stacks only work in harnesses that can route subagents to multiple providers; in a single-provider harness, use that provider's column. Either way, recommend only models the current harness can actually dispatch: when in doubt, run the harness inventory in references/model-intel.md before proposing tiers.
Step -1 — self-update (quiet, never block, once per session)
Run this at most ONCE per session: on the first helm invocation of the conversation only. If any earlier turn of this session already ran the self-update pull (any mode or subcommand counts), skip this step entirely.
If the directory containing this SKILL.md is a git clone (a .git exists
there), run, with a short timeout and no prompts:
git -C <skill-dir> pull --ff-only --quiet
If it fast-forwarded, re-read SKILL.md (and any references you use this run)
before proceeding so you follow the newest version. On any failure (offline,
diverged, not a repo), continue silently with the current version; never ask
the user about it and never spend more than one attempt. Vendored installs with
.git removed are pinned on purpose and skip this step.
Invocation modes and subcommands
Treat the first word (or two) after /helm as an optional mode. Remove the
mode words before interpreting the remainder as the task request. Words such
as automatic, autofix, or a task whose first word merely begins with
auto are ordinary request text, not mode aliases.
/helm auto <task>: accept the route and model tiers helm derives from the request. Skip the route/model confirmation question; announce the selected plan in one line and proceed immediately. This bypass applies only to route/model confirmation, never to a genuinely ambiguous completion condition or a later real blocker./helm custom <task>: skip the Auto-vs-Custom confirmation and ask directly for only the route or tiers not already supplied inline./helm <profile-name> <task>: if the first word matches a saved profile inprofiles.local.md(see references/profiles.md), run with that profile's tiers and billing lane: announce them in one line, skip the tier confirmation, and still choose the route per references/routing.md (profiles pin models, never routes)./helm profile <save|list|show|delete> ...: manage saved profiles; follow references/profiles.md. Not a build run./helm refresh: re-audit the models this harness can dispatch, refresh the Artificial Analysis snapshot, and review saved profiles and the loop architecture against it; follow the Refresh section of references/model-intel.md. Not a build run./helm evaluate: read this repo's.helm/run ledgers and report measured cost savings, per-model performance, and suggested tier or profile changes; follow references/evaluate.md. Not a build run./helm help: print a compact command reference and stop. One table covering every mode and subcommand above (command + one-line what-it-does- an example invocation), then the user's saved profile names from
profiles.local.md(or "no profiles saved yet" plus the save syntax), then one closing line: the current model-intel snapshot date and where the full docs live (README.md and references/). No network, no dispatches, no state file. Not a build run.
- an example invocation), then the user's saved profile names from
/helm <task>with no mode: use the confirmation flow below.
auto, custom, profile, refresh, evaluate, and help are reserved
and can never be profile names. An unknown first word is not an error: treat
it as task text.
On invocation: route first, then confirm
Before anything else, ROUTE the run: read references/routing.md and pick the cheapest of its four loop shapes (solo / dispatch / helm-lite / helm) that holds quality for this task, following its triage discipline (route from the request text alone). The session model is the most expensive thing in the loop, so the first decision is how much of it this task actually needs. Route 0 (solo) skips the loop machinery, but never silently: tell the user in one line that you are handling it solo and why, then do the work; if it grows past a single bounded edit, stop and re-enter routing with what you learned.
For routes 1-3 without an explicit invocation mode or active profile, ask the user ONE question (use AskUserQuestion if available), folding the route and all model tiers into a single confirmation:
Helm plan: . advising, building, on escalation, for mechanical work. OK?
- Auto (recommended): run as proposed; the advisor may still move a specific chunk up or down a tier, noting why in the log.
- Custom: you pick the route and/or the three tiers yourself (any models your harness can run, including mixing providers).
If the user picks Custom, follow up asking for the route and three tiers (top / escalation, mid / default implementer, low / mechanical), offering the models available in this harness as options plus free-text for anything else. If the invocation already named models inline (e.g. "/helm ... implement with haiku"), treat that as Custom with those choices prefilled and confirm in the same question rather than re-asking from scratch.
Record the outcome on the Models: and Route: lines of the state file and
honor it for the whole run.
Step 0 — completion condition (never skip)
Turn the request into a goal with a verifiable end condition before any work. Read references/success-criteria.md first: it has worked examples by task type (feature, bug fix, refactor, UI, performance), the invalid conditions to reject, and a gold-standard state file. Hold your own condition to that bar. A valid condition is one you can check without the user, in descending preference:
- Command exit — the project's verify/test gate passes, a named test passes, a script prints X.
- Observable behavior — a route returns the right payload, a rendered page shows the element/state, a DB row exists with the right shape.
- Enumerable checklist — a finite list of concrete items each individually verifiable by 1 or 2 (e.g. "all 6 pages use the token", greppable).
Not valid: "looks good", "feels done", "improved", open-ended polish. If after one honest attempt you cannot state a condition of type 1-3, stop and interview the user (with AskUserQuestion if available, otherwise plain questions). Keep it skimmable: short options with your recommended default first. Typical probes:
- "Which of these would prove it's done: X passes / Y renders / Z rows exist?"
- "Is done = merged, or done = working on this branch?"
- "What's explicitly out of scope?"
Then write the state file .helm/<slug>.md at the repo root (slug = short kebab
task name):
# Helm: <task>
Status: in progress
Goal: <one sentence>
Completion check: <exact command(s) or observable + how to observe it>
Out of scope: <list>
Models: advisor=<session model or delegated strong tier> implementer=<model> escalation=<model> [profile=<name>] [billing=<subscription|api:<provider>>]
Route: <1|2|3> <dispatch|helm-lite|helm>: <one-clause why>
## Chunks
- [ ] 1. <chunk> — acceptance: <check>
- [ ] 2. ...
## Log
- <iteration entries appended here>
Status: is machine-read; keep it to exactly one of in progress,
complete, blocked. Anything you'd like to say about the status (what's
pending, what shipped, what the user owes the run) goes on a separate
Status-note: line, never inside Status: itself.
The state file is the loop's memory; it must survive context compaction. Re-read it at the top of every iteration instead of trusting conversation history.
Step 1 — plan (advisor, full effort)
Steps 1 and 2 are the advisor's job wherever the advisor lives: on the helm-lite route they run inside the delegated advisor agent (dispatched with the template in references/routing.md) and the session model rejoins at Step 3 to verify the exit. On the full helm route, you are the advisor; proceed.
Plan at the level you'd want from a staff engineer: read the relevant code yourself (targeted reads only) or via a read-only explore agent dispatched WITH an explicit cheap-tier model override (an explore agent without one inherits the session model and bills the whole sweep at advisor rates), decide the approach, then split into delegable chunks. A good chunk: one implementer can finish it without cross-chunk context, touches a bounded file set, and has its own acceptance check. 2-6 chunks is typical; if it's one chunk, helm is overkill, just delegate once. Size ceiling: if a chunk's expected diff spans more than ~3 files or mixes concerns (lib + cron + UI in one chunk), split it before dispatching. Measured across the Jul 2026 ledgers: the median accepted chunk lands near 150k subagent tokens, and the two ~410k outliers ran 2.5-3x that, one of them carrying its run's only rejection. Aug 2026 update: every accepted chunk above ~250k logged watchdog stalls needing manual resumes (5 stalls across 3 chunks in one week); treat ~250k expected subagent tokens as a hard split trigger, not a soft ceiling.
Scout discipline (in the measured ledgers, scouts are the biggest spend after implementation):
- Audit/hardening sweeps: don't fan out 3-4 parallel full-sweep dimension scouts (correctness, perf, convention, security) over the same surface. Run one small-tier pre-pass to shortlist files, then ONE mid-tier deep audit over the shortlist. Measured: parallel dimension scouts hit 44% of one run (605k) and a sibling sweep spent another 577k, including one dimension that returned zero findings for 141k.
- Regression diagnosis: one small scout confirms WHICH surface regressed before any archaeology scouts (git history, DB comparisons) go out. A measured run spent a full scout sweeping the wrong surface.
- Retire zero-yield dimensions: an audit dimension that has returned zero accepted findings across runs gets folded into another scout's checklist or dropped.
- Inventory scouts go small-tier: file lists, call-site enumeration, env-var sweeps, and other structured-inventory sweeps need format-following, not judgment; dispatch them on the mechanical tier. Measured (Aug 2026): a haiku inventory scout cost ~76k where sibling sonnet scouts ran 100-180k for comparable coverage.
The project's own rules bind every chunk: CLAUDE.md / AGENTS.md conventions, the design system, lint and test gates. Quote the relevant rules into each dispatch prompt rather than assuming the subagent will find them.
Step 2 — the loop
Before your first dispatch, read references/dispatch-and-review.md: the dispatch prompt template, the per-chunk review checklist, and the log-line format. For each unchecked chunk (parallelize only chunks with zero file overlap):
- Dispatch an implementer on the chosen implementer model via your harness's subagent mechanism (Claude Code: the Agent tool; elsewhere: whatever spawns a scoped worker with a selectable model). The prompt must be self-contained: goal one-liner, the chunk, exact file paths, relevant conventions (quoted inline, not "see CLAUDE.md"), the acceptance check, and "run the project's verify gate before returning; return a summary of changed files + gate output."
- Review as advisor. Read the actual diff (
git diff), not just the agent's summary. Check correctness, convention fit, scope creep, and the acceptance check. You are the senior reviewer; be strict. - Iterate with the SAME agent (SendMessage or your harness's equivalent, so it keeps its context) with specific fixes. Escalation ladder on repeated failure of the same chunk: default tier fails once → retry with sharper instructions; fails twice → redispatch fresh on the strong tier; the strong tier fails on the same root cause → 3-strikes rule, stop and ask the user (this is a real blocker).
- Gate. After accepting a chunk, run the project's verify gate yourself. Red gate = the loop's problem: dispatch a fix, never park it.
- Record. Check the box and append one log line to the state file (chunk, implementer model, attempts, verdict). This log doubles as the scorecard when you're evaluating how well a model tier performs.
Step 3 — exit
Run the completion check from the state file, literally and fully. Only two exits:
- Pass → mark the state file
Status: complete, write theTotals:ledger line, commit if the user has authorized commits (stage only this task's files), and give a short recap: what was built, where it landed, per-model attempt stats from the log, and sensible next steps. - Blocked → 3 strikes on one root cause, missing credentials, a destructive decision, or genuinely ambiguous scope discovered mid-loop. Write the blocker to the state file and ask the user the narrowest possible question. The 3-strikes rule applies at the completion-check level too: if 3 distinct strategies fail the SAME check leg (not the same chunk), that leg is the blocker; bring the user the evidence from all 3 rounds rather than dispatching a 4th variation.
Never exit because the loop "has done a lot" or the session is long. Partial completion without a blocker is not an exit state; keep dispatching.
Anti-patterns
- Advisor writing the feature itself "because it's faster" (defeats the point; small unblock edits only).
- Defaulting every run to the session-advised route out of habit, or reading files "to decide the route" (route from the request; a wrong route self-corrects, a session-advised routine run never gets cheaper).
- Dispatching without a per-chunk acceptance check (unreviewable results).
- Trusting the implementer's self-report instead of reading the diff.
- Vague completion condition accepted to avoid interviewing the user.
- Converting this into a scheduled/background loop; helm is strictly in-session.
Files in this skill
5helm skill questions
How do I install the helm skill in Claude Code?
Run npx degit Jacknelson6/helm ~/.claude/skills/helm. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the helm skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.