# Building Skills > 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… - **Type:** Skill - **Install:** `agentstack add skill-bh-rat-steer-building-skills` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [bh-rat](https://agentstack.voostack.com/s/bh-rat) - **Installs:** 0 - **Category:** [Security](https://agentstack.voostack.com/c/security) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [bh-rat](https://github.com/bh-rat) - **Source:** https://github.com/bh-rat/steer/tree/main/skills/building-skills - **Website:** https://steer-docs.vercel.app/ ## Install ```sh agentstack add skill-bh-rat-steer-building-skills ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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. 2. **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. 3. **Apply past lessons.** Run `python3 "$SKILL/scripts/steer.py" learn show` and follow what it says; those lessons came from real previous builds. 4. **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 --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. 2. **scaffold** (verified): run the agreed command. Completes when SKILL.md exists in the workspace. 3. **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). 4. **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. 5. **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. 2. **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. 3. **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. 4. **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 "" --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 `; when one was wrong, `learn dispute ` 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` ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [bh-rat](https://github.com/bh-rat) - **Source:** [bh-rat/steer](https://github.com/bh-rat/steer) - **License:** MIT - **Homepage:** https://steer-docs.vercel.app/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-bh-rat-steer-building-skills - Seller: https://agentstack.voostack.com/s/bh-rat - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.