use skills

Syntax

use skills: <skill-a>, <skill-b>

What it does

Lists the skills the agent is allowed to call while it plans and acts — so the loop coordinates proven, reusable skills instead of one giant prompt. This is skill-driven development: you build and battle-test each skill on its own, then wire the loop to orchestrate them. The names must already resolve (in ~/.claude/skills); if they don't exist yet, prove the skill by hand first, then add it here.

Why it matters: a monolithic prompt is hard to debug and impossible to reuse. Naming skills keeps each capability small, independently tested, and shared across loops — the loop's job shrinks to deciding when to call each one. There are two roles a skill can play, and they're distinct. As an execution skill listed under use skills:, it's a tool the agent may invoke during a cycle. As a verifier, it decides the verdict via done when the skill "<name>" approves (or scores 8 or more, or approves by 3 judges). Pairing the two — an execution skill that does the work and a review skill that judges it — is the common shape.

If the skills don't exist locally, let a recommender install them: use skills recommended by ctx resolves the bundle at run time (with recommend skills with ctx at the config tier). With no ctx attached those lines are inert and the loop runs unchanged.

Example

loop "harden the upload endpoint":
  goal: no high-severity findings in the upload path
  use skills: security-review, code-review
  done when the skill "security-review" approves
  each cycle: plan, then act, then observe
  when it fails: reflect, then plan again

Example — skills chosen by ctx

recommend skills with ctx              # config tier: ctx is the skill source

loop "harden the stripe webhook handler":
  goal: webhook retries are idempotent and signature-checked, with tests
  use skills recommended by ctx for "stripe webhook idempotency"
  top up skills from ctx when a step needs more
  done when "pnpm test api/webhooks" passes

Common mistakes

• Naming a skill that doesn't exist. use skills: assumes the names resolve in ~/.claude/skills. Inventing a skill around capabilities you haven't built means the loop calls nothing. Prove the skill manually first, or let ctx install it.
• Confusing the execution role with the verifier role. Listing a skill under use skills: only permits the agent to call it — it does not make it the finish line. To let a skill decide "done", it must appear in a done when the skill "…" approves predicate.
• Trusting a green test alone when "done" also means "built right". An execution skill can make a test pass the wrong way. Add a trajectory eval — done when the skill "…" approves on the trajectory with a the bar: line — to judge how the work was done, not just the result.
• Assuming ctx lines do something without ctx. use skills recommended by ctx is inert unless the ctx MCP server is attached; it won't error, but it also won't install anything. For a self-contained file, list the resolved skills under use skills:.

Related