| name | write-recipe |
| description | Use when creating a new ra recipe — a complete agent configuration with skills, middleware, and config. |
Writing a Recipe
A recipe is a self-contained agent configuration. Copy the directory, run it — everything works.
Structure
recipes/<name>/
ra.config.yaml # Agent configuration
README.md # What it does, how to run it
skills/ # Bundled skills (MUST be self-contained)
<skill-name>/
SKILL.md # YAML frontmatter + instructions
scripts/ # Optional: run at activation, stdout → context
references/ # Optional: injected as context
middleware/ # Optional: lifecycle hooks
<hook>.ts
Checklist
-
Define the agent — one sentence: "A code reviewer that reads diffs and gives structured feedback."
-
Write skills — skills/<name>/SKILL.md:
- YAML frontmatter:
name, description
- Markdown body: role, process, output format
- Optional
scripts/ for dynamic context (git diff, env vars, etc.)
-
Write config — ra.config.yaml:
agent:
provider: anthropic
model: claude-sonnet-4-6
skillDirs:
- ./skills
maxIterations: 10
mcp:
servers:
- name: github
transport: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
middleware:
afterModelResponse:
- ./middleware/token-budget.ts
-
Add middleware (optional) — common hooks: token budget, tool filtering, logging
-
Write README — install, configure, run
-
Test — cd recipes/<name> && ra --config ra.config.yaml "test prompt"
Rules
- Recipes must be self-contained — bundle all skills inside
skills/, use skillDirs: [./skills]
- Never reference paths outside the recipe directory (
../../skills is wrong)
- Skill scripts should be fast — they block activation
- See existing recipes in
recipes/coding-agent/ and recipes/code-review-agent/ for reference