Directing agents
Write the procedure once; let every agent run it the same way.
A playbook is a written procedure for work that repeats; a skill is that playbook packaged so an agent can load and follow it on demand. This page shows when one is worth writing, what belongs inside, and what stays out.
#Playbooks: the repeatable how
A playbook is the written form of "how we do this here" for a recurring operation: cutting a release, validating before publishing, changing a managed config, responding to a failing deploy. It differs from a rule — a rule says what must always hold; a playbook says what steps to take, in what order, with what checks. Teams have kept playbooks (runbooks) for decades; what's new in AI-native work is that a playbook can now be executed by an agent, not just read by a person — which raises the bar for how precisely it's written.
#Skills: playbooks an agent can load
A skill is the executable packaging: a folder with a SKILL.md entrypoint that an agent loads on demand when the task matches. Keep the source in one place — Groundwork keeps repo skills in skills/ with .claude/skills and .codex/skills as symlinks — so every tool runs the same procedure.
#When a skill is worth creating
A skill is useful when the workflow is repeated, procedural, and easy to get subtly wrong. It is not a second rulebook.
In Groundwork, repo-local skills include docs-alignment, chezmoi-change, macos-default-change, and validate-groundwork. They cover the exact places where hidden coupling matters: keeping docs aimed at AI_THESIS.md, managed files, macOS defaults plus backup/restore, and release validation.
The litmus test for tool-specific skill files is simple: if an agent should follow the text, it belongs in SKILL.md. If a tool only uses it to label or register the skill, it can live beside the skill as metadata. Groundwork validates that any Codex openai.yaml file stays in the second category.
Good skill
"Create a verified PowerPoint deck from this template." It has steps, assets, validation, and a clear finish line.
Bad skill
"Always write clean code and run tests." That belongs in AGENTS.md.
Good adapter
"Claude Code: read AGENTS.md; use @file references when asking about a specific file." Tool behavior lives here, shared policy does not.
AGENTS.md is the reliable contract. Skills are on-demand procedure guides, and discovery varies by tool. Anything the agent must always obey belongs in AGENTS.md; anything step-by-step and repeatable can live in skills/.
#A real one from this repo
Groundwork ships to users through Git tags and GitHub Releases, not through whatever happens to sit on main. That split — main as the rolling edge, tags as the known-good refs people actually pin and pull — is exactly the kind of procedure a person explains once, forgets a step of the second time, and an agent should instead run the same way every time. The cut-release skill (skills/cut-release/SKILL.md) is that procedure written down.
Trigger. The skill states its own condition for when to run, not a schedule: "Run this when the change is release-affecting: it alters what a fresh bootstrap or chezmoi update / update-all delivers... Do not cut a release for internal automation, CI plumbing, or dependency bumps that change nothing a user consumes…" A trigger phrased as a check the reader can answer, not a vague "when appropriate," is what makes a playbook usable by an agent.
Preconditions. Before any tagging happens, three things must all hold, and each is a command, not a feeling:
| Green main | gh run list --branch main --workflow CI --limit 1 — "If red, fix CI first — a red main means nothing can ship." |
| Clean tree | git status -sb shows no divergence, confirmed against origin/main after a fetch. |
| Local validation | scripts/validate-groundwork passes on the machine cutting the release. |
Steps, in order. Choose the version by reading the previous tag and bumping per SemVer (major for user action required, minor for additive tools or docs, patch for fixes only); write release notes for the actual users, in plain language; then tag and release together against the checked SHA, not just HEAD: gh release create vX.Y.Z --target <green-sha> --title "vX.Y.Z" --notes-file -.
Verify. The skill ends with checks anyone — human or agent — can run to confirm the release actually landed: gh release view vX.Y.Z shows the intended notes, git tag --sort=-v:refname | head -1 is the new tag, and that tag's SHA has green CI.
This repo is running proof, not a hypothetical. Pick any release in gh release list — v1.3.0, cut July 2026, is one — and gh release view shows the shape the skill demands: user-facing notes, a tag pointing at a specific green commit rather than whichever was newest. That one happens to have been cut by an agent that loaded this skill and followed it — which is the point: the procedure reads the same to whoever runs it.
What makes this a good playbook is visible in the anatomy itself: every precondition is checkable with a single command instead of a judgment call, the steps have a fixed order that does not depend on who is running them, a verify section closes the loop instead of trusting that the steps worked, and the whole document reads the same way to a person skimming it before a release and to an agent loading it on demand. Nothing here says "usually" or "typically" — it says what to run and what the output should look like.
Try it now
Pick a procedure you have explained to an agent, or to a teammate, more than once — restarting a stuck service, rotating a credential, publishing a build. Write the smallest possible playbook for it: one line for the trigger (when to run this), a numbered list for the steps, one line per precondition that is checkable by command rather than by feeling, and a verify section that confirms the result. Save it as SKILL.md in a skill folder in your practice repo, the same shape as skills/cut-release/ in this one.
#References
- Claude Code skills — project skills,
SKILL.md, and skill discovery paths. - AI agents & rules — the contract layer skills must never replace.