bh-rat/steer/building-skills

building-skills

Build an Agent Skill the deliberate way: design the trigger and the components with the user, scaffold with steer new, write the body, and prove the result with steer validate and a real run. The user gets an installed, spec-valid skill, not a plausible-looking draft.

This skill bundles its own steer runtime at scripts/steer.py for its flow and learning; authoring the new skill additionally needs the installed steer CLI, checked below.

Before you start

1. Check steer. Run steer --version. If it is missing, ask the

user to install it (uv tool install steer-ai or pip install steer-ai), then continue; do not hand-roll a lookalike scaffold as a fallback.

1. Set two paths. SKILL is this skill's own directory (this file's

parent); WS is the new skill's directory, decided during design; it does not need to exist yet.

1. Apply past lessons. Run `python3 "$SKILL/scripts/steer.py" learn

show` and follow what it says; those lessons came from real previous builds.

1. Improving rather than building? For a review or tune-up of an

existing skill, skip the flow and follow references/improving-a-skill.md.

Process

This build runs behind an enforced flow: steps verify themselves against reality, and you cannot skip ahead. The flow lives next to this file and operates on the new skill's directory:

python3 "$SKILL/scripts/steer.py" flow status --workspace "$WS" python3 "$SKILL/scripts/steer.py" flow next --workspace "$WS" python3 "$SKILL/scripts/steer.py" flow done <step-id> --workspace "$WS"

The steps, and what completes them:

1. design (mandate): triage the source material, make the four

decisions below, and compose the exact steer new command. Show the user the command, the name, and the install scope; mark the step done when they agree.

1. scaffold (verified): run the agreed command. Completes when

SKILL.md exists in the workspace.

1. write (verified): fill the scaffold with real content. Completes

when no TODO marker is left anywhere in the workspace (the generated scripts/steer.py is exempt; you never edit it).

1. validate (verified): completes only while steer validate .

passes in the workspace. Fix warnings and info findings too, or tell the user which one stays and why.

1. exercise (mandate): install the skill, run it once on a real

task, and fix what the run exposes. Mark done after the run, then wrap up as the directive says.

Do NOT claim the build is done while the flow status shows incomplete steps.

The four design decisions

Ground every decision in real material: the document or API the user pointed at, this conversation's history, or their answers, never generic knowledge of what such a skill "usually" looks like. When the source is a document, an API, or the current conversation, read references/source-material.md first; it says what to extract and what to leave behind.

1. Who triggers it? Model-invoked means the description is the

entire trigger: what the skill does plus when to use it, in the words the user would actually say. Human-invoked (--user-invoked) trades auto-triggering for firing exactly when asked. Pick deliberately.

1. What does it need at runtime? Credentials, state between runs, an

environment snapshot, steps that must not be skipped, a managed background process, lessons from its own runs: each is one steer component, wired in by steer new together with a bundled runtime (scripts/steer.py), so whoever runs the skill needs Python, not steer. Read references/choosing-components.md and take only what changes behavior.

1. What loads when? Material every run needs goes in the body;

branch-only detail goes under references/ (--refs) behind a one-line pointer. The budgets (under 500 lines, about 5k tokens) exist because the whole body enters context on every trigger.

1. How much freedom? Deterministic work becomes a script

(--scripts, one JSON envelope on stdout); judgment stays prose; a required order becomes flow steps (--steps) with verify conditions instead of ALL-CAPS pleading. The more fragile the operation, the less freedom the skill should leave.

Learning

This skill improves with use. As you work:

• The moment the user corrects you, or something fails and then works a

different way, capture it: python3 "$SKILL/scripts/steer.py" learn note "<one imperative rule>" --kind correction Lessons are atomic rules ("Use X not Y when Z"), never secrets.

• When a lesson from the digest helped, run

python3 "$SKILL/scripts/steer.py" learn confirm <id>; when one was wrong, learn dispute <id> the same way.

• Before finishing, record the outcome:

python3 "$SKILL/scripts/steer.py" learn run ok (or failed with --note).

If a learnings.md exists in this skill, read it too; those are promoted lessons that shipped with the skill.

Gotchas

• Names bite late: lowercase kebab-case, 64 chars max, equal to the

directory name, and the Claude API rejects names containing "claude" or "anthropic". steer validate checks all of this; run it early, not only at the gate.

• A component the skill does not need is context the agent pays for on

every run. When in doubt, leave it out; steer bundle --with ... and one copied section wire one in later.

• The new skill's scripts/steer.py is generated code: never edit it

(steer validate flags edits, packaging refuses them), and keep the TODO gate away from it. Running the finished skill needs Python 3.11 or newer, not steer; the installed CLI is for authoring and for the optional --auto-learn Stop hook.

• One skill, one job. When the design produces two triggers with two

processes, build two skills.

• The new skill only loads reference files it names. Point to each one

("When X, first read references/y.md") or delete it.

References

Branch-only detail lives behind pointers and loads only when needed:

• Picking runtime components: references/choosing-components.md
• Descriptions, bodies, flows, and scripts:

references/writing-the-body.md

• Building from a document, an API, or this conversation:

references/source-material.md

• Reviewing or upgrading an existing skill:

references/improving-a-skill.md