[Agents] Add pre-commit check for agent files and skills

[mgoin]

Overview

Add a pre-commit hook that checks agent instruction files and skills, and remove the nested CLAUDE.md files it now rejects. Follow-up to #59638, where a new skill shipped without its .claude/skills symlink and nothing flagged it.

Claims

tools/pre_commit/check_agent_files.py fails on:

• a skill in .agents/skills without a correct .claude/skills symlink, or anything in .claude/skills that is not such a link;
• SKILL.md frontmatter that does not parse, a name that differs from the directory, or a missing or over-long description (limits from the Agent Skills spec);
• line budgets: 200 for the root AGENTS.md, 300 for nested ones (both already in editing-agent-instructions.md), 500 for SKILL.md;
• relative links and heading anchors that do not resolve, in AGENTS.md files and skills;
• any tracked CLAUDE.md.

A description that never says when to use the skill prints an advisory note: and does not fail.

Validation

• cd tests && pytest tools/test_check_agent_files.py: 14 passed. One case per rule, each breaking a minimal repo; wired into the CPU Buildkite job.
• pre-commit run passes on this branch, and the hook is clean on current main apart from the five CLAUDE.md files removed here.
• Run against open PR trees, it catches:

PR	Finding
#57088	unquoted colon in description (frontmatter is not valid YAML), and no symlink
#57786	no symlink
#50527	real SKILL.md under .claude/skills

Details

Removing CLAUDE.md. #58541 removed the root file because Claude Code reads AGENTS.md directly. Per the Claude Code docs, it only does so when there is no CLAUDE.md in the working directory or above it, so starting Claude Code inside rust/ currently skips the root AGENTS.md. I have not reproduced that; it is read from the docs. Removing the nested pointers lets every AGENTS.md load directly.

Trade-offs:

• rust/CLAUDE.md also imported a gitignored AGENTS.override.md (from [Rust Frontend] Move code from vllm-frontend-rs #43283). Claude Code does not read that file on its own, so a local override no longer reaches Claude Code in rust/. Codex is unaffected.
• Claude Code before v2.1.277 does not read AGENTS.md directly. Remove .gemini/ and CLAUDE.md #58541 already accepted this for the root file.

Left out on purpose.

• agents/openai.yaml stays optional and unchecked: it is display metadata for Codex, which discovers .agents/skills without it.
• The three existing descriptions that trigger the advisory note (debug-ima, kernel-microbenchmark, triton-kernel-writing) are unchanged.
• No behavioral skill tests (prompt routing, with/without-skill A/B); this is static checking only.

Anchors are compared on alphanumerics only, because slug rules differ between GitHub and MkDocs. The hook's files: filter only covers agent files locally; CI runs pre-commit with --all-files, so a link broken by a docs change is still caught there.

Not a duplicate: no open PR adds an agent-file check or touches these CLAUDE.md files.

---

Pull Request Checklist

• I used vLLM's /pr-checklist skill. (Mandatory for agents, optional for humans).

• AI assistance was used during the creation of this PR.

• Design Fit: Minimizes impact on core components, reuses existing functionality, and justifies added complexity.

• Testing and Validation: Validates the change and ensures any added tests are meaningful and reliable, with CI coverage or documented CI resource constraints and validation performed outside CI.

• Code Quality and Style: Keeps code and comments clear and concise, and updates relevant documentation and examples.

• Pull Request Contents: Includes a brief summary and relevant links, supports claims with evidence, explains root causes and implementation trade-offs, and follows the contributing guide.

🤖 Generated with Claude Code

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[mergify]

Documentation preview: https://vllm--59657.org.readthedocs.build/en/59657/

[sfeng33]

Thanks!

[benchislett]

Thanks!

[mgoin]

/ci run

[github-actions]

✅ Triggered Buildkite CI #92480 for commit 7209daa0d88f.