The Agent Skills Playbook
How to package your team's know-how as reusable skills and instruction files — and set them up in Claude, ChatGPT, Codex, and other AI coding agents.
Every team ends up retyping the same instructions to its coding agent: how we write commits, how we review migrations, what a good test looks like. A skill is how you stop doing that.
A skill is a folder with a short instruction file and, optionally, reference documents and scripts. The agent reads only a one-line description up front and loads the rest when a task actually calls for it. That makes skills cheap to install in quantity and easy to share through version control.
This paper explains what skills are, how they differ from prompts, rules files, and tools, how to write one that triggers reliably, and how to set them up in Claude, ChatGPT, Codex, and other agents. It closes with the security and governance practices that keep a shared skill library from becoming a liability.
Write the procedure down once, in a form the agent can load on demand, instead of explaining it in every conversation.
01 — WHY SKILLS EXIST
A coding agent arrives at your repository knowing a great deal about software in general and nothing about how your team works. Closing that gap by hand means long prompts, pasted style guides, and corrections repeated across sessions and across people.
Each developer carries their own prompts. Quality depends on who asked, and the best phrasing lives in someone's notes app.
The procedure is a reviewed file in the repo. Everyone, and every agent, starts from the same instructions.
02 — WHAT A SKILL IS
The design principle is progressive disclosure: the agent pays for information only when it becomes relevant.
Only the name and description are read up front — a few dozen tokens per skill. This is what the agent uses to decide whether the skill is relevant.
When a task matches, the body of SKILL.md is loaded. Keep it focused: the steps, the rules, the gotchas.
Reference files and scripts are opened only when the instructions point at them, so a skill can carry far more material than it costs to have installed.
03 — SKILLS VS. THE ALTERNATIVES
| WHERE IT LIVES | WHEN IT LOADS | BEST FOR | |
|---|---|---|---|
| Prompt | In the chat | Every time you paste it | One-off requests |
| Rules file | In the repo (CLAUDE.md, AGENTS.md) | Always, at session start | Short, universal conventions |
| Skill | A folder with a SKILL.md | On demand, when the task matches | Repeatable procedures with files and scripts |
| Tool / MCP server | A running process | When the agent calls it | Reaching live systems and data |
A useful rule: if it must be true in every session, it is a rule. If it is a procedure for a specific kind of task, it is a skill. If it needs live access to a system, it is a tool.
04 — ANATOMY OF A SKILL
--- name: pr-description description: Writes a pull request description from the current git diff. Use when the user asks for a PR description, PR summary, or release notes for a change. --- # PR description 1. Run `git diff main...HEAD --stat` and read the changed files. 2. Write the description using references/template.md. 3. Lead with WHY the change exists, not a file-by-file list. 4. List anything a reviewer should test by hand. 5. Never include secrets, internal URLs, or ticket text verbatim.
05 — WRITING A SKILL THAT TRIGGERS
The agent decides whether to load a skill from its description alone. State what the skill does and when to use it, using the words a user would actually say.
Helps with PRs.
Writes a pull request description from the current git diff. Use when the user asks for a PR description, summary, or release notes.
Database stuff.
Reviews SQL migrations for locking, rollback, and data-loss risk. Use before applying or approving any migration.
Write numbered steps, not essays. The agent follows instructions better than it absorbs background.
06 — SETTING UP SKILLS IN CLAUDE
# project skill, shared with the team mkdir -p .claude/skills/pr-description $EDITOR .claude/skills/pr-description/SKILL.md # personal skill, available in every project mkdir -p ~/.claude/skills/pr-description
Reads skills from the personal and project skills folders on disk. Best fit for engineering workflows that need the filesystem and shell.
Skills can be enabled in settings and, on supported plans, uploaded as a packaged folder. Document skills (spreadsheets, slides, PDFs) are the common starting point.
Skills can be attached to a request through the code-execution environment, so the same skill works in your own product.
07 — CHATGPT & CODEX
ChatGPT's chat product does not use a skills folder the way Claude Code does, but it has equivalent layers. Use the narrowest one that covers your case.
# AGENTS.md ## Commands - Install: npm ci - Test: npm test - Lint: npm run lint ## Conventions - TypeScript strict mode. No `any` without a comment. - Server logic lives in /lib. Components never call the database. ## Boundaries - Never edit files under /migrations without asking. - Never read .env files. Reference secrets by variable name.
08 — OTHER AGENTS & A PORTABLE LAYOUT
Cursor, Copilot, Gemini CLI and others each have their own rules or instructions file. Rather than maintain a copy per tool, keep one source of truth and let each tool's file reference it.
09 — TEN SKILLS WORTH WRITING FIRST
Turns a diff into a reviewer-friendly summary.
Applies your team's commit format consistently.
Checks changes against your own review checklist.
Writes tests from the requirement, not from the implementation.
Flags locking, missing rollbacks, and data loss.
Reproduces, narrows, and records root cause before fixing.
Summarizes merged changes for users, not developers.
Calls an internal API the way your team expects.
Produces reports and decks in your house template.
Walks a new hire through setup in your repo.
10 — TESTING AND ITERATING
11 — SECURITY AND GOVERNANCE
A skill can instruct the agent and ship scripts that run on your machine. Installing one is closer to installing a package than saving a note.
A reference file or fetched page can contain instructions aimed at the agent. Treat content a skill reads as data, not as commands.
Skills get committed and shared. Reference credentials by variable name; never write the value into a skill.
A skill nobody owns slowly stops matching how the team works, and the agent keeps following it faithfully.
- Read every file in a third-party skill, including scripts, before enabling it
- Pin or vendor skills you depend on rather than tracking someone else's main branch
- Review changes to skills in pull requests, the same as application code
- Give each skill a named owner and a last-reviewed date
- Run agents that use skills inside the permission boundary described in The Agent Data Boundary
See The Agent Data Boundary for the permission architecture that keeps a misbehaving skill from reaching beyond the project.
12 — COMMON MISTAKES
The description is the trigger. Say what the skill does and when to use it.
Split by job. A skill that does five things triggers on the wrong tasks.
Move long reference material into separate files that load on demand.
Always-on conventions belong in CLAUDE.md or AGENTS.md, not in a skill.
Write numbered steps and explicit rules, not background essays.
A skill that has not been run against realistic prompts is a guess.
If a step must be exact (a format, a calculation), put it in code instead of prose.
Unowned skills drift. Assign someone and review on a schedule.
13 — ROLLOUT CHECKLIST
Conclusion
Skills turn individual prompting habits into shared, reviewable infrastructure. The format is simple on purpose: a folder, a markdown file, a description that says when to use it.
Start with one task your team repeats every week. Write it as numbered steps, test it against real prompts, commit it, and give it an owner. The second skill is easier than the first.
Reach out — we're happy to talk through which workflows are worth turning into skills first.
The following resources informed the practices described in this paper.
Agent products change quickly. File locations, feature names, and plan availability described here reflect general behavior at the time of writing and should be confirmed against each vendor's current documentation before you rely on them. Where a detail is vendor-specific, this paper deliberately stays high level.
This publication is an independent work of Toolkit Master. It is not affiliated with, sponsored by, endorsed by, or otherwise associated with Anthropic, OpenAI, Cursor, GitHub, Google, or any other organization referenced herein. References to products, standards, and publications are provided solely for informational and educational purposes. All third-party trademarks, names, and logos remain the property of their respective owners.
This white paper is provided for general informational and educational purposes only. It does not constitute legal, cybersecurity, compliance, or professional advice. The practices described may not be appropriate for every organization or environment, and no representation or warranty is made that following them will prevent security incidents, data loss, or other risks. Toolkit Master assumes no responsibility for actions taken based solely on the information in this publication.