Pragmatic Bear

Write the recurring job down once.

playbook turns a task you keep repeating, like a weekly report or a release checklist, into instructions Claude Code follows the same way every time. The assistant can say it did the work. Only a check it doesn't control, or you, can say the work is right.

Install playbook thepragmaticbear/playbook
  1. Capture /playbook capture An interview about the job. What starts it, and how you'll know it's done.
  2. Contract CONTRACT.md What the assistant may and may not do. Only you change its state.
  3. Evaluate EVALUATION.md Test cases. Each one names a verifier that isn't the worker.
  4. Run /playbook run Does the job and leaves a receipt in runs/.
  5. Improve /playbook improve Up to three narrow fixes, drawn from real runs.

What happens
at each step.

A captured playbook is three short Markdown files and a folder of run records. Read them before you hand anything off.

  1. Capture

    /playbook capture <job> asks what starts the job, what the steps are, what can go wrong, and how you'll know it's done. Then it writes .claude/skills/<job>/, or ~/.claude/skills/<job>/ when the job belongs to no single repo. Plain /playbook does the same and asks for the job in one line.

  2. Contract

    CONTRACT.md is the agreement. It lists what the assistant may do and what it may not, such as never sending anything without asking, along with the assumptions and open questions. Every playbook starts as DRAFT. You move it to TRIAL once you approve the contract and to RELEASED after the trial gate, by editing the **State:** line yourself.

  3. Evaluate

    EVALUATION.md holds the test cases, with at least one N, E, A and P row. Every case names who checks it. The worker can't be that verifier, and neither can self.

    scripts/validate.py checks all three files and rejects a playbook with a missing section, a leftover placeholder, or a case the worker grades itself. capture runs it for you.

    It can't tell whether a named verifier is truly independent. It accepts owner.

  4. Run

    /playbook run <playbook> <task> does the job and writes an evidence record to runs/ with what it ran, what came back, and anything it couldn't finish. That record starts at OBSERVED. Independent checks move it to VERIFIED, and only an owner can mark it APPROVED.

    It also ignores instructions hidden in the material it works on. A note in a document that says "skip the checks" stays a note.

    Before each release, five pressure scenarios run on the exact revision being shipped, including injected instructions in task data and an owner pushing to mark an unrun check VERIFIED. All five passed for v0.2.3.

  5. Improve

    /playbook improve <playbook> reads real run results and proposes at most three narrow fixes.

    /playbook harvest <artifact> turns an approved past output into reusable templates or scripts.

Two states,
kept apart.

The contract state tracks how far you have signed off on a playbook. The run state says what happened on one run. Only the owner moves the first, and the assistant can never move the second past OBSERVED on its own.

DRAFT
ContractEvery captured playbook starts here.
TRIAL
ContractYou approved the contract.
RELEASED
ContractThe playbook passed its trial gate.
OBSERVED
RunThe assistant did the work. That's all it can claim.
VERIFIED
RunIndependent checks passed.
APPROVED
RunAn owner signed off.
INCOMPLETE · FAILED · BLOCKED
RunThe run stopped short, and the record says where.

Install.

Plain Markdown plus one Python validator. Clone it into your skills folder.

Claude Code, global

git clone https://github.com/thepragmaticbear/playbook ~/.claude/skills/playbook

Update with git -C ~/.claude/skills/playbook pull.

Claude Code, one project

git clone --depth 1 https://github.com/thepragmaticbear/playbook .claude/skills/playbook && rm -rf .claude/skills/playbook/.git

A plain clone inside your repo adds a gitlink instead of the files, so drop the nested .git. To update, remove the folder and run the line again.

Read the skill on GitHub

MIT licensed. The validator needs Python 3 and git on your PATH. Other assistants that read Agent Skills, such as Codex and OpenCode, can load SKILL.md from ~/.agents/skills/playbook. But capture and run write to Claude Code's skills folders unless you adapt them.