Title: Agents and Skills Published: July 24, 2026 --- # Agents and Skills ## In this article * [Guiding principle: improve the documentation first](https://developer.wordpress.org/block-editor/contributors/code/agents-and-skills/?output_format=md#guiding-principle-improve-the-documentation-first) * [How agent instructions are organized](https://developer.wordpress.org/block-editor/contributors/code/agents-and-skills/?output_format=md#how-agent-instructions-are-organized) * [Where does new guidance belong?](https://developer.wordpress.org/block-editor/contributors/code/agents-and-skills/?output_format=md#where-does-new-guidance-belong) * [Skill conventions](https://developer.wordpress.org/block-editor/contributors/code/agents-and-skills/?output_format=md#skill-conventions) * [Checklist for adding a skill](https://developer.wordpress.org/block-editor/contributors/code/agents-and-skills/?output_format=md#checklist-for-adding-a-skill) [ Back to top](https://developer.wordpress.org/block-editor/contributors/code/agents-and-skills/?output_format=md#wp--skip-link--target) The Gutenberg repository ships instructions for AI coding agents: `AGENTS.md` files and a `skills/` directory. This document explains how they are organized and what to consider before adding more. ## 󠀁[Guiding principle: improve the documentation first](https://developer.wordpress.org/block-editor/contributors/code/agents-and-skills/?output_format=md#guiding-principle-improve-the-documentation-first)󠁿 Before adding anything to an agent file, ask whether the information would help human contributors too. If it would, it belongs in the public documentation, and the agent files should point to it. Agent-only files are easy to let rot: missed details and stale information linger because nobody audits them, while public docs are continuously read and corrected by contributors. Duplicating documentation into agent files also means the two copies silently diverge. Agent files should route to canonical docs, never fork their content. ## 󠀁[How agent instructions are organized](https://developer.wordpress.org/block-editor/contributors/code/agents-and-skills/?output_format=md#how-agent-instructions-are-organized)󠁿 Agent instructions follow **progressive discovery** — an agent reads only what its current task needs: * **Root [`AGENTS.md`](https://github.com/WordPress/gutenberg/blob/trunk/AGENTS.md)** is loaded in every agent session. It stays lean and routes to everything else:“ if working on X, read the docs for X at this path.” * **Directory `AGENTS.md`** files (for example [`packages/components/AGENTS.md`](https://github.com/WordPress/gutenberg/blob/trunk/packages/components/AGENTS.md)) are loaded when an agent works with files in that directory. They hold rules scoped to that directory only. * **Skills** ([`skills//SKILL.md`](https://github.com/WordPress/gutenberg/blob/trunk/skills/README.md)) are thin, task-scoped guidance — procedures, checklists, or decision trees. An agent reads one when its task matches the skill’s description. * **Linked docs and references** are read only when a procedure step points to them — they carry no cost until then, so depth belongs there. * `CLAUDE.md` files are one-line `@AGENTS.md` redirects for tools that look for that filename; the content always lives in `AGENTS.md`. This structure controls context bloat. The root `AGENTS.md` is a fixed cost in every session, so keep it lean. Skill bodies are read when relevant, so keep them thin and procedural. Everything linked one hop away is effectively free. ## 󠀁[Where does new guidance belong?](https://developer.wordpress.org/block-editor/contributors/code/agents-and-skills/?output_format=md#where-does-new-guidance-belong)󠁿 Work down this list and stop at the first match: 1. **Public documentation** — if the information helps humans too (it usually does), improve the docs and have agent files point there. 2. **Root `AGENTS.md`** — only for facts nearly every task needs: environment setup, universal pitfalls, and the routing list itself. 3. **A directory `AGENTS.md`** — for rules an agent must know when working in one specific directory. 4. **A skill** — for guidance scoped to a kind of task rather than a location: a procedure, checklist, or decision tree an agent should follow when doing that work (running tests, releasing a package, scaffolding a block). ## 󠀁[Skill conventions](https://developer.wordpress.org/block-editor/contributors/code/agents-and-skills/?output_format=md#skill-conventions)󠁿 These conventions match [WordPress/agent-skills](https://github.com/WordPress/agent-skills), so contributors can work in both repositories with one mental model: * One directory per domain: `skills//`, lowercase kebab-case. * `SKILL.md` starts with YAML frontmatter containing only `name` (matching the directory) and `description`. Phrase the description as a trigger: “Use when …”. * Keep the body short and procedural. Link to depth rather than inlining it, and keep every linked file one hop from `SKILL.md`. * Link a doc the agent **must** read as part of the procedure step that needs it(“ read the [guide] before writing your first body”). In testing, if an agent finds a skill that matches its task, it will focus on that task rather than re-considering generalized “read the relevant docs” files from AGENTS.md. * An optional `skills//references/` directory holds agent-specific depth that has no home in the public docs. The [testing skill](https://github.com/WordPress/gutenberg/blob/trunk/skills/testing/SKILL.md) and its [`references/` directory](https://github.com/WordPress/gutenberg/tree/trunk/skills/testing/references) are the live example of these conventions. In skeleton form, a skill looks like: ```language-md --- name: description: Use when . --- # ## … ## By sub-area - ****: read [references/.md](references/.md). ``` Walking through how the live testing skill applies these conventions: * The `description` is what an agent matches against when deciding whether to read the skill, so it names the tasks that should trigger it (“writing, running, or debugging tests…”). * The body routes rather than explains: one line per kind of work, each pointing at a `references/` file one hop away. * A procedure step that applies to every sub-area (planning the test list with the author) lives once in the skill body, not repeated in each reference — each fact has one home, at the highest level where it applies everywhere below. * Each reference file holds only the agent-specific rules for its area and links to the canonical docs for depth. For example, [`references/e2e.md`](https://github.com/WordPress/gutenberg/blob/trunk/skills/testing/references/e2e.md) says “stay headless; never use `--headed` or `--ui`” — modes the e2e guide rightly recommends to humans but which would hang an agent’s session — and then links to that guide for authoring practices. * Nothing restates the root `AGENTS.md` — every agent already has it loaded. * This is progressive disclosure end to end: the description is always visible, the body is read when a testing task starts, and each reference is read only when the work is actually of that kind. ## 󠀁[Checklist for adding a skill](https://developer.wordpress.org/block-editor/contributors/code/agents-and-skills/?output_format=md#checklist-for-adding-a-skill)󠁿 1. Confirm the public docs can’t cover it — improve them first if they can. 2. Create `skills//SKILL.md` following the conventions above. 3. Add a routing entry to the root `AGENTS.md`. 4. Run `npm run lint:md:docs`. First published July 24, 2026 Last updated July 24, 2026 Edit article [ Improve it on GitHub: Agents and Skills ](https://github.com/WordPress/gutenberg/edit/trunk/docs/contributors/code/agents-and-skills.md) [ Previous: Workspace Development](https://developer.wordpress.org/block-editor/contributors/code/workspace-development/) [ Next: Gutenberg Release Process](https://developer.wordpress.org/block-editor/contributors/code/release/)