Skip to main content
Ralphy’s agent intelligence lives in two layers. Playbooks are role and domain instruction docs under docs/playbooks/*.md — the agent reads them on demand when the routing table in AGENTS.md matches a user intent. Skills are slash-invocable workflows under .agents/skills/<name>/SKILL.md — narrow, deterministic, with a single CLI command and a defined input → output contract. Both exist for the same reason: keep the agent from improvising on topics where the codebase already has a known-good answer.
Browse every built-in skill at a glance — including trigger phrases and input → output contracts — on the Skills gallery on the landing page.

​
Playbooks

A playbook is a plain Markdown file. No frontmatter, no slash-command, no skill activation. It is read by the agent via the Read tool after AGENTS.md routing matches an intent. The eleven playbooks today: Each playbook starts with “Read this when:” so the agent confirms the match before diving in. Each lists its Sub-docs at the top — for example, researcher.md points at researcher/yt-dlp.md and researcher/tiktok-extract.md for tool-specific deep-dives. The agent reads sub-docs on demand once the sub-task is identified. The rule from docs/playbooks/meta.md rule 6: when the agent feels “I know how to do this, I’ll skip the read” — that feeling is the bug. Across 10 shipped postmortems, confidence-without-reading was the highest-cost failure mode. The cost of reading is ~10 seconds; the cost of being wrong is $1-50 + 30-90 minutes of user-flagged cleanup.

​
The routing table

The routing table in AGENTS.md maps user intent to a playbook. A simplified excerpt: Composition. A request that spans roles is a chain in role order. “Make a video in the style of <url> for <brand>” → researcher → scenarist → art-director → editor. The producer playbook is the wrapper for end-to-end. Batch (N ≥ 3). Always producer → batch from-template. Never a hand-rolled loop. The full table lives in AGENTS.md and is auto-imported into the system prompt by CLAUDE.md, so it is always in context.

​
Skills

A skill is a folder under .agents/skills/<name>/ with a single SKILL.md that follows the agentskills.io convention: YAML frontmatter + Markdown body. The frontmatter is the trigger contract (the description renders in Claude Code’s slash-command menu); the body is the playbook the agent reads once the skill fires. The seven skills today, in the order they appear under .agents/skills/: The skill body follows a conventional section order — ## Trigger, ## Hard invariants, ## Workflow, ## Outputs, ## Cookbook — see docs/skills-format.md for the authoring guide.

​
Two namespaces

Skills ship in two namespaces: The install wizard (ralphy skill install) installs the user set by default. ralphy skill install --dev opts into the maintainer set. The split exists so a tester running /<TAB> on a fresh install does not see release, backlog, and maintainer authoring tools. A skill in the maintainer namespace ships through the same lint and installer plumbing as a user skill — it is the same format, just gated behind the --dev flag in the installer.

​
Playbooks vs. skills

The two layers solve different problems. Playbooks are role docs. They are read by the agent when a user intent matches a row in the routing table. They cover roles (scenarist, art-director, editor, producer, core) and domains (hyperframes, intake). No frontmatter, no activation contract — they are just Markdown the agent reads. Skills are workflows. They have a deterministic input → output contract and a single CLI command. They are slash-invocable (/evaluator <path.mp4>) and they produce specific artifacts on disk. The agent invokes a skill when the user types the slash command, or when the routing table points the agent at a skill (e.g. “evaluate this video” → /evaluator). The old role-shim skills (ralph-art-director, ralph-core, ralph-editor, ralph-producer, ralph-scenarist) were removed in favor of direct routing via AGENTS.md → playbooks. If you need to invoke a role, you say the role-utterance (“compose the video”) and the routing picks the right playbook. You no longer need a slash command for the everyday flow.

​
When to write a playbook vs. a skill

The decision tree:
  • Write a playbook when the work is a role the agent plays (writing scripts, generating prompts, composing videos). Playbooks branch — the same playbook handles many sub-tasks. The producer playbook handles end-to-end and batch and save-as-template — three different sub-tasks, one role.
  • Write a skill when the work is a workflow with a single artifact (URL → research report, mp4 → eval report, project → template). Skills are linear — input → workflow → output. They have a slash command. They have hard invariants enforced by the skill body.
A red flag for the wrong choice: a skill that branches into “now you decide what to do next” is probably a playbook. A playbook that ends “produce this specific artifact at this specific path” is probably a skill.

​
The agent’s start-of-session discipline

From docs/playbooks/meta.md, five files to read at session start:
  1. AGENTS.md — auto-loaded by CLAUDE.md.
  2. MODELS.md — checked before every model call.
  3. CLI.md — verb / flag reference cheatsheet.
  4. The closest sibling postmortem under .ralphy/workspaces/<ws>/projects/<id>/postmortem/02-lessons.md.
  5. The matched playbook from AGENTS.md routing — read fully before acting.
The closest-sibling postmortem rule is the highest-leverage 10 minutes of a session. Sibling = same template kind, same category, same aesthetic register. Reading the lessons file from the closest prior project saves $5-20 of regen burn that would otherwise rediscover the same lessons.

​
Adding a new playbook or skill

For a new playbook:
  1. Drop a docs/playbooks/<role>.md file. Start with “Read this when:” so the agent can confirm the match.
  2. List sub-docs at the top with a “When to read it” column.
  3. Add a row to the routing table in AGENTS.md mapping intent to the new playbook.
  4. (Optional) Add canonical utterances to docs/use-cases.md.
For a new skill:
  1. Create .agents/skills/<name>/SKILL.md with valid frontmatter (name, description ≤ 1536 chars).
  2. Pick a namespace — user for user-facing, maintainer for maintainer-only.
  3. Follow the section order — ## Trigger, ## Hard invariants, ## Workflow, ## Outputs, ## Cookbook.
  4. Run bun run lint:skills — CI runs the same lint.
  5. Add a row to the routing table in AGENTS.md if the skill should fire from a user-intent match.
See docs/skills-format.md for the full skill authoring guide, including the “writing a great description” section that covers the 1536-char trigger budget.