| name | building-skills |
| description | Builds an Agent Skill (SKILL.md) end to end with steer: design the trigger and components, scaffold with steer new, write the body, then gate on steer validate and a real run. Use when the user wants to create, write, or scaffold a skill, turn a document, API, or repeated workflow into a skill, or review, fix, or improve an existing skill. Also use when a skill needs credentials, persistent state, enforced steps, background processes, or learning wired in. |
| metadata | {"version":"0.1.0"} |
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
- 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.
- 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.
- Apply past lessons. Run
python3 "$SKILL/scripts/steer.py" learn show and follow what it says; those lessons came from real previous
builds.
- 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:
- 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.
- scaffold (verified): run the agreed command. Completes when
SKILL.md exists in the workspace.
- 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).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
