Playbook for AI agents

The team codes with several AI agents (Claude Code, Codex, Cursor, OpenCode, Copilot). This folder turns the playbook into context those agents load in every product repository, and CI keeps it in sync.

What a product repository receives

Path	What	Read by
AGENTS.md, between <!-- playbook:begin --> and <!-- playbook:end -->	core.md plus an index of the skills	Codex, Cursor, OpenCode, Copilot; Claude Code through CLAUDE.md
CLAUDE.md	One @AGENTS.md line	Claude Code
.agents/skills/playbook-*/, .claude/skills/playbook-*/	One skill per convention, loaded when the task matches	.agents/skills: Codex, Cursor, OpenCode, Copilot. .claude/skills: Claude Code, Cursor, OpenCode, Copilot
.agents/playbook/	README.md, handbook/, conventional/ and templates/, copied verbatim	Any agent, by path from a skill

Nothing else in the repository is touched. The repository's own text in AGENTS.md and CLAUDE.md, and its own skills, stay as they are.

Two skill folders are needed because no single one is read by every agent (checked 2026-09-28): Claude Code reads only .claude/skills, and Codex reads only .agents/skills. Claude Code reads AGENTS.md natively only when a repository has no CLAUDE.md, which is why the @AGENTS.md import is added.

Files here

File	What
core.md	Always-on rules. Loaded into every agent session in every repository, so it stays short (core_max_lines in bundle.json)
skills/<name>/SKILL.md	One skill per convention, in the Agent Skills format: a trigger description, a checklist, and the path of the full doc
bundle.json	Each skill's index line (when) and the source docs it summarizes (sources); where skills and docs go in a repository
targets.json	The repositories that receive sync merge requests

Changing a rule

1. Edit the doc under conventional/ or templates/ as usual.
2. Update the matching skills/<name>/SKILL.md checklist in the same merge request. The agent:check job fails if a source doc changes and its skill does not. For a wording-only edit that changes no rule, put [agent-skip] in the merge request description.
3. After merge, agent:sync opens or updates one merge request per enabled target, on branch chore/playbook-agent-sync.

A skill summarizes; it does not copy. Values that change on their own schedule, such as image digests, stay only in the source doc, and the skill tells the agent to copy them from there.

Adding a skill

1. Create skills/playbook-<topic>/SKILL.md with name: playbook-<topic> and a description saying when to use it (1-1024 characters, one line).
2. Add it to bundle.json with when and sources.
3. Run the checks below.

Adding a repository

Add it to targets.json with "enabled": true. The token in the PLAYBOOK_SYNC_TOKEN CI/CD variable (masked, protected; scopes api and write_repository; Developer role) must be able to push to the repository and open merge requests in it. Preview what the repository would get first:

scripts/build-agent-bundle.sh
scripts/apply-agent-bundle.sh --dry-run ../path/to/repo

Your own Claude Code, in every repository

Until the sync reaches a repository, or for repositories it never will, install the playbook into your personal Claude Code:

scripts/install-claude-global.sh              # re-run after pulling the playbook
scripts/install-claude-global.sh --uninstall

It copies the docs to ~/.claude/playbook/, the skills to ~/.claude/skills/playbook-*/ with paths rewritten to point there, and the core rules to ~/.claude/rules/playbook.md, which Claude Code loads in every session. Your own ~/.claude/CLAUDE.md / AGENTS.md and your other skills are never edited. In a synced repository the same rules also arrive through AGENTS.md; they are identical, so nothing conflicts.

Running the checks locally

scripts/check-agent-drift.sh                       # structure, frontmatter, core.md size
DIFF_BASE=origin/main scripts/check-agent-drift.sh # plus source/skill drift for your changes
tests/agent-bundle/run.sh                          # end-to-end against throwaway repositories

The scripts need bash, git, jq and curl.