The skill: download build-your-agent for your coding agent

The pages before this one are knowledge: what is true, cited to the book and to the installed SDK. A coding agent also needs the other half, the procedure: what to read first, what to produce, when "done" is done, and where to stop and ask. The book keeps the two apart as well. Its loop has a skill, project knowledge written down once so no run starts from nothing, ¹ and its labs hand the coding agent a brief that says what to build, in what order, and what wins when the brief and the installed SDK disagree. ² This page is that half for this room.

Download

Download build-your-agent-skill.zip (version 2.2, 2026-10-12). The same procedure is this page, so a tool with no skills folder can read it as plain text at https://sor.razarizwan.com/md/agent/build-your-agent-skill.md.

Inside, one folder named build-your-agent:

How it is written

The skill follows the page on writing skills, which is to say the book's rules and OpenAI's. It is in the Agent Skills format: a folder whose name matches the name in SKILL.md, a description that says what the skill does and when to use it, and a body under 500 lines so an agent loads it whole once it decides the skill applies. ³ The description front-loads the situations and the phrases that should trigger it, and says when it should not, because a host with many skills installed may shorten descriptions to fit its budget. ⁴

The body is instructions, not a script. OpenAI's guidance is to prefer instructions over scripts unless deterministic behaviour or external tooling is needed, to keep each skill focused on one job, and to rely on progressive disclosure: the host loads only the name and description at first, and the full SKILL.md when the skill is selected. ⁴ So the skill says how to think through each step, names the record page that settles it, and leaves the knowledge in the record. The one deterministic step, probing the installed SDK, is a script.

The skill says when; the record says how. Nothing in the skill is knowledge that is not on a page of this record. Each step names the page to read before the step, every template in assets/ is a copy of a template on a page and names that page, and when a copy and its page differ, the page wins. This is what makes the record the one place the method lives. The first version of this skill held method of its own: it asked for a single spec.md and nothing else, and no page said otherwise, so the worker built from it had no research, no plan and a four-section spec, while the book behind the spec page already asked for four artifacts. ⁵ Two places that each hold their own version of the method is the failure this rule exists to prevent.

Install

Unzip into the skills directory your tool reads, keeping the folder name.

mkdir -p .claude/skills
unzip build-your-agent-skill.zip -d .claude/skills
# then, inside Claude Code: /build-your-agent

Claude Code reads .claude/skills/<name>/SKILL.md in the project and ~/.claude/skills/<name>/SKILL.md for all projects, follows the Agent Skills open standard, and runs a skill when its description matches or when you type /name. ⁶ Codex scans .agents/skills in the working directory, its parents and the repository root, plus ~/.agents/skills, and activates a skill explicitly with $skill-name or implicitly when a request matches its description. ⁷ OpenCode searches .opencode/skills, .claude/skills and .agents/skills in the project, and their global equivalents, and loads a skill by name. ⁸ A tool with no skills folder gets the same procedure by pasting SKILL.md as the first message of the session.

Attach the record

The skill reads the record through MCP when the server is attached: https://sor.razarizwan.com/mcp, three tools, search, outline and read. The door answers only with an access key, which takes a minute to get at razarizwan.com/access: enter an email, type the code it receives, and the address arrives with the key inside it. The key is the last segment of the address, so no client has to send a header (?key=YOUR_KEY after /mcp is accepted as well). In Claude Code that is one command, and /mcp afterwards shows the server as connected: ⁹

claude mcp add --transport http raza-sor "https://sor.razarizwan.com/mcp/YOUR_KEY"

In Codex, OpenCode, ChatGPT or claude.ai, add the same address with the key in the tool's MCP or connector settings, authentication "none". The server is required: when the skill finds no raza-sor tools in its tool list it stops and sends the person to the access page rather than building from anything else. Only when an attached server fails does it fall back to each page's raw markdown at https://sor.razarizwan.com/md/agent/<page>.md, which needs no key, and it records which pages came from the fallback. Either way, the knowledge comes from the record, and the skill only says which page to read when.

Start

One line and your work, in your words:

Use build-your-agent. Here is the job my team does and how: ...

The agent creates progress.md and sends one opening message: what it assumes about the depth (a demo, unless you say production), the model and whether it is free or paid, and the rest of the blanks, each already filled in from your words for you to correct. Then it reads the work with you into a delegation map, answers the three gates, and stops for your approval of the spec before it writes a line of code. Whatever the depth, you are handed one page with a password, an upload, a Run button and a chat box.

The eight non-negotiables

These are in SKILL.md, and they are the record's rules, not new ones:

1. Record first, memory never. Every rule the agent applies comes from a page it read this session, and the page id goes beside the work in the progress file. What the record does not cover is said to be uncovered, with what was searched, never invented.
2. No code before the human approves the spec in their own words, recorded with the date. The agent never writes the approval line.
3. Tests before tool bodies, the probe before SDK code. The installed SDK and its live documentation win over any page here.
4. Anything that must hold regardless of the model lives in code: a threshold, a category rule, a duplicate check, an ownership filter, computed in a tool body and tested there. Identity comes from the harness, never from chat. The rule and its reasons are on the build page.
5. A worker that talks to people is natural by design. The five rules on the experience page are acceptance criteria: every record a person owns has a tool that lists it; the private part of a message is refused while the public part is answered; a well-formed question never ends in a hard error; a fact appended by code belongs to the question; unscripted questions are graded beside the golden set.
6. Every instruction the agent writes is a prompt, written under the AI prompting guide.
7. Secrets never enter code, chat, a commit or an image. Deploying, spending money, sending anything outside the project, and any tool that changes the world need the human's word, recorded.
8. Never invent a human, a task, a proven run or an example to satisfy a gate. The progress file is read first and updated last; commit after every step, and a step with no commit is not done.

How it talks to the person

The person on the other side is usually not an engineer, and the record's pages carry the rules for talking to them; the skill only says when they apply. Every question is still asked, because a skipped question is a default the model fills and the worker goes wrong there; what changes is the pace.

• The opening round first. Before the work is read, one message proposes the depth (demo by default, or production), the model provider and free or paid, and every other blank it can fill from the person's words, each answer pre-selected and marked as the assumption, so the person corrects only what is wrong (demo or production, "The opening round").
• Rounds, not single questions. The blanks a step needs are gathered into one message, as a short list, so the person answers a round at a time (spec page, "How this record runs the interview").
• Three answers with every question, the third always "in your own words". A proposed answer is accepted or corrected, never assumed.
• Plain words, technical blanks last. Which system holds the data, which platform, a path or a key are placeholders on the map until the tools are wired at step 9 (understand the work, "How to ask for the blanks").
• Proven runs are proposed, then corrected, when none are ready; a run stays PROPOSED until the person confirms it, and the gate counts only confirmed runs (from plan to worker).
• The person is handed a page, not an API: one page with a password, an upload, a Run button and a chat box that answers in the person's own language and politely refuses what is outside the work, plus three plain lines: the address, where the password lives, and where the code lives with the command that runs it again (the worker's page, "What the person is handed").

Where the files go

The book's rule is that every feature ships with its spec in specs/, with the constitution in the rules file at the root, CLAUDE.md or AGENTS.md, and the research, the spec and the plan as files in the feature's folder. ⁵ This room extends that rule to every document about one worker, so a stranger opening the repository finds the whole decision trail in one folder:

AGENTS.md                       the constitution, six to eight lines
progress.md                     the memory between sessions, read first, updated last
specs/<worker>/
  delegation-map.md             step 1: the person's steps, owners, criteria, gates, baseline
  gates.md                      step 2: the three gates, proven runs, promotions, the shape
  experience-brief.md           step 3: the eleven sections and the natural-behaviour criteria
  research.md                   step 4: the one-page findings document
  spec.md                       step 4: behaviour only, six sections, approved by the human
  governance-record.md          step 5: case, data, capability, people, evidence
  plan.md                       step 7: the how, reviewed by the human before code
src/<worker>/                   the factory, the tools, the guardrails, the CLI, the door
tests/                          one test per acceptance criterion, and the loop test
datasets/golden.json            the golden set, an origin on every case
datasets/unscripted.json        the unscripted set
scripts/run_evals.py            the runner
Dockerfile, Dockerfile.vercel   the sealed bundle, and the Vercel build

The task list is the agent's own tracked checklist, one commit per task, so the git log reads like the list; it is written out as tasks.md in the same folder only when the tool has no task tool or the human wants the breakdown reviewed as a document. ⁵ The templates in the skill's assets/ folder fill the first seven of those files.

The ten steps

Each step names the page that settles it. The agent reads the page before the step, quotes its rules rather than paraphrasing them, and checks the step against the "Done when" column and the closing list of the page before calling it done.

The table is the production depth. At demo depth, the default, every step is kept and produces less, as the step-by-step table on demo or production says; the depth chosen in the opening round is written at the top of progress.md.

The progress file

The harness page gives the spine: a progress file the run reads first and updates last, with what is done, what is in progress and what needs a human. ¹ This room's version adds the gates the human passed in their own words, the commits, and the facts each step must leave behind, so that a new session, or a new agent, can continue without a transcript. The skill ships it as assets/progress.md.

# progress.md

Task (one line, in the human's words):
Started:
Record read from: (MCP / raw markdown / web)

## Steps

| # | Step | Status | Proof (file, command, date) | Record pages read |
| --- | --- | --- | --- | --- |
| 1 | Understand the work (delegation map, baseline) | | | |
| 2 | Gates, proven runs, shape (STOP if rejected) | | | |
| 3 | Experience brief | | | |
| 4 | Constitution, research, spec (STOP for approval) | | | |
| 5 | Governance record (OPEN QUESTIONS routed) | | | |
| 6 | SDK probe, failing tests | | | |
| 7 | Plan (STOP for review), worker and harness | | | |
| 8 | Evals: golden set, unscripted set, baseline | | | |
| 9 | Ship (STOP before deploy), five-stage checklist | | | |
| 10 | Report | | | |

## Human gates (the human's own words, with the date; never written by the agent)

Task given by:
Proven runs by hand (dates; PROPOSED until the human confirms):
Spec approved by:
Governance open questions answered by:
Plan reviewed by:
Deploy approved by:

## Commits

| Step | Commit |
| --- | --- |

## SDK

Installed openai-agents version:
Provider (OpenAI default / other):
Default model the probe printed:
Pin written to pyproject.toml:
Probe run on (date):

## Shape

Five answers (Q1 to Q5):
Pattern chosen:
Most likely objection, and the answer:

## Harness

- Constitution file:
- Spend cap set by the human (yes/no):
- Tools: allow / ask (needs_approval, with the autonomy stop) / deny (not given):
- Listing and lookup tools scoped by identity:
- Pre-commit hook:
- Typed output where parsed:
- Three stops (success condition, limit, no-progress check):
- Streaming and tracing wired:

## Evals

Golden set size, categories, origins:
Unscripted set size and author:
Validation script:
Rubric version and bars per category:
Grader calibration (agreement, false passes):
Baseline (date, judge model, overall, by category, unscripted on its own line):
Schedule and hold-outs:

## End-to-end checklist

| Stage | Done when | Proof |
| --- | --- | --- |
| Laptop | Boots clean; /health ok; /docs lists both endpoints; smoke test exits 0 | |
| Container | Image builds; /health ok from inside; smoke passes; rebuild after one edit is fast | |
| Live URL | /health ok over HTTPS from another device; smoke passes; one cold start recovered | |
| Behaviour | Golden set and unscripted set pass their bars against the live /runs, across several runs | |
| Gates | Guardrail blocks; approval pauses and resumes on approve, stops on reject; max_turns ends a run | |

## Handed over

Live address:
Project path:
Run command:

## Done

- (date): what was proven

## In progress

-

## Open, needs a human

-

Adapting to any niche

The record teaches how to read work, not one business, and the skill is written so that it can build a worker for a niche this record never named. The agent derives the worker from the person's own workflow:

• Every noun they manage becomes a read tool; every record they own becomes a list tool and a get tool, scoped by the identity the harness supplies; every action becomes a draft-and-propose tool behind needs_approval; every number that matters becomes a computation in a tool body; every DECISION row on their step table becomes a constitution line and a check in code.
• Their real runs become golden cases with origins; their own words become the unscripted set; their gates become the approval tests; their measured baseline becomes the number to beat.
• Their vocabulary names the tools, plainly, for the action; their language is the language of the instructions.
• The worked example is a teaching illustration. An agent that finds itself copying it has stopped reading the person's work.

Updating a worker that already exists

A spec is written once and then kept alive, never frozen; the record's rule on the spec page is to change the spec first, in the same commit as the code, then re-derive the code. The skill carries that as part of step 10: read progress.md and spec.md; change the spec first, or interview until the change can be written into it; write the failing test, then the code; rerun the whole eval suite and add the new case to the golden set; re-run the SDK probe if the SDK moved; record the change and the commit in progress.md.

What changed in version 2.0

Version 1.1 was a phase-by-phase list of files to produce, and it held method of its own. Its first real run showed what a list does: a coding agent followed the phases it could tick and skipped the ones it could not, wrote the "user" and the proven runs itself, and never committed. Version 1.1 answered that with rules. A second test build, a support worker for a fictional shop built from this record and the skill and reviewed by the owner with sixteen questions that were not in its test set, passed every scripted question and failed the natural ones: no tool listed the person's own records, a message with a private half and a public half was refused whole, a boilerplate sentence was appended to the wrong answer, and a well-formed question ended in an error. ¹⁰ The same build had one spec file with four sections and no research or plan, because the skill had asked for exactly that, while the book asks for four artifacts. ⁵ None of that was a missing rule. It was a skill that told the agent what files to write instead of where the method lives and what a good worker feels like to the person using it.

So version 2.0 changes the shape. The skill says when; the record says how. It is written as judgement, what each step is for, what to read, what to produce, where to stop, with every how on a page and every template a copy of one. It adds the delegation map, the shape decision, the experience brief, the governance record, the plan reviewed before code, the unscripted eval set and the five natural-behaviour rules, all from the pages added to this room on 2026-09-09, and the folder layout above. The install and the download URL are unchanged, and the MCP attachment now carries the access key described above, so a copy installed from version 1.1 is replaced by unzipping version 2.0 over it.

What changed in version 2.1

Two builds from version 2.0, a support worker in Claude and a shop assistant in Codex, both from this record over MCP, produced sound maps, gates and specs, and both wore the owner out on the way: one question per message for the whole interview, technical blanks (which system, which platform, a repository path) asked before the work itself, a hard stop on three dated runs the owner had not written down, developer words the owner had to look up, and a finished build that was a folder of files rather than an address to open. None of that is a missing rule; it is the pace and the words.

Version 2.1 keeps every question and every gate and changes how they reach the person, on the pages: the interview runs in rounds with three answers offered per question (write the spec); connection details are placeholders until the deploy step and proven runs are proposed for correction, labelled until confirmed (understand the work, from plan to worker); and the deploy step hands over the live address, the code's path and the run command in plain words (deploy page). The map gains a connections block and the gates file a confirmed column. Install and download are unchanged; unzip version 2.1 over version 2.0.

What changed in version 2.2

A demo build from version 2.1, a mortgage follow-up worker on invented data from a production-grade brief, did everything the record asked and still failed its owner three ways: it took far too long, it used more than half of the owner's model allowance on one project, and it was handed over as an API behind a token that only a terminal could test. A switch of provider at the end cost a second round of work. (demo or production, "What a test build showed".)

Version 2.2 decides the size of the build before it starts, and changes what the person receives:

• An opening round proposes the depth (a demo by default, or production) and the model provider, free or paid, with every other blank pre-filled for correction (demo or production).
• Two depths of the same ten steps, and an upgrade path from demo to production that changes the spec first and never rebuilds.
• One page for every worker, at both depths: a password, an upload, a Run button whose numbers come from code, and a chat box that replies in the person's own language and script, answers anything about the work, politely refuses the rest, and keeps to a daily limit (the worker's page).
• Claude and Grok wired and checked, beside Gemini on its free tier, so no build guesses a provider's endpoint or model id (use another model).

The package gains assets/opening-round.md and assets/worker-page.py. Install and download are unchanged; unzip version 2.2 over version 2.1.

Keeping it current

The skill points at pages; the pages carry the dates. When the SDK pages reach their review date and are re-verified, the skill needs no change. When a step changes in the record, the version on this page changes with it, and the zip is rebuilt; the skill's metadata.version and this page always say the same number.