Add progressive-discovery pattern for agent instructions and skills

[jeryj]

What?

Establishes a documented pattern for how AI-agent instructions are organized in the Gutenberg repository, and lands the first skill (testing):

• Root AGENTS.md becomes a lean router with a Progressive discovery section: contributor docs, skills, and directory guides are read only when the task needs them.
• New top-level skills/ directory: skills/testing/SKILL.md intro point with references/ files for Jest, PHP, and e2e specifics.
• New contributor guide at docs/contributors/code/agents-and-skills.md.

Why?

Agent guidance in the repo is currently ad hoc (root AGENTS.md, one per-directory file in packages/components/), with no documented convention for contributors. By providing a general structure, we have a way to start contributing to improve agent success in coding in Gutenberg.

How?

Follows conventions from WordPress Agent Skills to progressively disclose skills to prevent context bloat and confusing agents:

• Content is placed by trigger: always-loaded (root AGENTS.md: env setup, code quality, pitfalls, router) / location-triggered (directory AGENTS.md) / task-triggered (skills/) / on-demand (docs and references). Each fact has one home, at the highest level where it applies to everything below it.
• The testing command block moved from root AGENTS.md into the skill's per-type references; the shared wp-env-test requirement lives once in SKILL.md. Non-discoverable trap rules (PHP build-time function prefixing, per-package CHANGELOG.md entries) moved to Common pitfalls.
• The guidance doc's example is a skeleton (not a copy of the live skill) so it cannot drift; the live example is linked instead.

Testing Instructions

1. Start a fresh agent session with default configuration: claude (interactive), or for a captured run: claude -p "Run the e2e tests for the paragraph block" --verbose --output-format stream-json > run.jsonl.
2. Run grep -o '"file_path":"[^"]*"' run.jsonl to list every file read.
3. Confirm the file-read list includes skills/testing/SKILL.md and skills/testing/references/e2e.md, and that those reads appear before the first test command.
4. Confirm the file-read list does NOT include skills/testing/references/php.md or skills/testing/references/jest.md
5. Run grep -o '"command":"[^"]*"' run.jsonl to list every shell command.
6. Confirm the command list contains npm run wp-env-test status before any wp-env-test start.
7. Confirm it contains a spec path after npm run test:e2e -- (e.g. editor/blocks/paragraph.spec.js) and does not contain --headed, --ui, or --debug. Cross-check: no browser window opened during the run.
8. Start a new agent session: claude -p 'Add an e2e test for the paragraph block that checks that the `&` key is not output as `&` in the editor' --verbose --permission-mode acceptEdits --output-format stream-json > run.jsonl
9. Run grep -o '"file_path":"[^"]*"' run.jsonl to list every file read.
10. Confirm the file-read list includes the relevant docs and sklls, docs/contributors/code/e2e/README.md, skills/testing/SKILL.md and skills/testing/references/e2e.md, and that those reads appear before the first test command.

Use of AI Tools

Authored with Claude Code (Claude Fable 5) in an interactive session, with structure and content directed and reviewed by the PR author. The comparison against WordPress/agent-skills conventions was also AI-assisted and human-verified.

🤖 Generated with Claude Code

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: jeryj <jeryj@git.wordpress.org>
Co-authored-by: bgrgicak <berislavgrgicak@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[bgrgicak]

How does this help? We could test it on a couple of examples where we introduce a bug into either the code or test and see if it makes the correct decision.

I'm worried that the current wording could be misleading. Maybe something like this phrase could work better, but I haven't tested it.

There might be a good skill already available somewhere for fixing failing tests.

## Fix test failure

Before fixing a test failure, investigate the rot cause of the failure. If the test is failing due to it being outdated, update the test to match the code. If it's timing out, fix the timeout root cause, increase the timeout as a last resort.
Update the code in case the test failure was introduced by a bug in the code.

[jeryj]

I've had the agent try to fix a failing test by changing the core code. Trying to keep it focused on the important core task rather than immediate satisfaction of "Fixing the test." However, maybe this is not needing and the proper fix is the developer improving their prompting.

I'm unattached to this and happy to remove it. Core piece I want to accomplish is just the overall pattern.

[ciampo]

Should we recommend npm run test:unit:php (or npm run test:php when lint is desired), because those scripts run PHPUnit inside the configured wp-env test environment

[ciampo]

If we plan on doing some test-driven development, I'm afraid this section will prevent it?

[jeryj]

Good point. Happy to remove it. Main point for the PR is scaffolding the overall structure of agents and skills. I'd rather be more minimal (remove this line) and discuss specific agent instructions in a follow-up PR.

[ciampo]

I noticed we're repeating the wp-env-test across a couple of files, should we unify it under the skill.md file for applicable environments?

[jeryj]

I believe it's only relevant for php and e2e, so I put them in their separate files.

[ciampo]

From the canonical e2e guide, it seems like headless mode is not supported in Linux. Maybe we can tweak the guidance here to say "use headless when supported, as per the canonical e2e testing guide"

[jeryj]

Sure. It doesn't need to be as assertive as it is.

[jeryj]

@bgrgicak @ciampo - My main concern here is the overall architecture pattern and guidelines for adding the agent instructions and skills. The testing skill is meant to be minimal and improved in follow-ups, so the intention isn't a great final testing skill state right now.

[github-actions]

Flaky tests detected in 657ee4b.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/30108411927
📝 Reported issues:

• [Flaky Test] should cut and paste individual blocks with collapsed selection #80248 in /test/e2e/specs/editor/various/copy-cut-paste.spec.js

[ciampo]

So far, no concerns from my end. I suspect we'll find out only by gathering evidence about how different agents do

[aduth]

Nit: If we have a qualifier like "in a package" that refers to a specific place in the codebase, that's a good signal that it belongs in a localized AGENTS.md within the related folder, i.e. packages/AGENTS.md, so that this doesn't need to be loaded into agent context if an agent is working on files outside of packages.

(h/t @simison for his original suggestion to this in #78166 (comment))

[jeryj]

I'm also finding that notes about discovery from the AGENTS.md loaded at runtime is pretty much ignored by the time the agent actually performs the task. Skills seem to be more reliable for procedural tasks than AGENTS.md. I say, let's give it a try in a couple ways and see which structure the agent more reliably follows.

[talldan]

I find that this rule results in agents adding changelog entries per commit rather than per PR. (I end up with multiple entries per PR)

Not sure if that's acceptable, it goes against how it usually works where the PR is linked at the end of a changelog entry.

Usually the local agents aren't even aware of the PR number (it doesn't exist yet), so they aren't able to reference a PR, but also don't stop to ask (in true AI agent fashion).

Anyway, I think this rule is somewhat counterproductive if we want PR links in changelog entries.

[aduth]

@talldan In the spirit of treating AGENTS.md as a collection of AI scar-tissue, maybe it'd help to just add a sentence or two detailing expectations around those specific problems?

i.e. "Only include a single changelog per branch. Don't include a link if a pull request isn't opened yet."

Would you want to open a pull request with that?

It also occurs to me that the "See docs/contributors/code/managing-packages.md." may not be entirely effective in a few ways: the document itself doesn't have much guidance and links to yet another article that AI agents may choose to ignore, and in general we're pretty loose in documenting the issues you've described. "Maintaining changelogs" does say "for each pull request", but that's not very prescriptive. There's literally nothing about links! We can't be surprised that agents mess this up if we're not even documenting it.

[ciampo]

Only include a single changelog per branch

I've had PRs introducing, at the same, a bug fix and a breaking change. Why wouldn't we want multiple entries per PR, when they make sense?

[aduth]

Sure, that's fine. It's just an example. Let's write it as we want it.

[talldan]

Yeah, I think multiple entries is valid, but perhaps not quite one per commit 😅

We should probably only really log for changes that have an external impact.

I'm very happy to update it, though as I mention I think it'll lead to missing PR references. I already see that in a few cases. Perhaps that's better than no changelog entry.

[jeryj]

I'm happy for this to get tweaked and updated as well. It's being a little over-zealous with the changelog entries I think :)

[Mamaduka]

Not sure if dropping these helped the agents, mine always tried to start non-testing env. Am I missing something? Maybe this is worth restoring.

Regresses #78718.

[jeryj]

Yeah, I think its still not hitting the agent paths right. I think it's fine to revert this PR or add these lines back in. I want to tidy up and land the tests in #80812 so we have a clear baseline to work off of for bringing in skill improvements.