---
title: '59657'
pageLayout: default
slug: thoughts/inference/vllm-prs/59657
permalink: https://aarnphm.xyz/thoughts/inference/vllm-prs/59657.md
generator:
  quartz: v4.6.0
  hostedProvider: Cloudflare
  baseUrl: aarnphm.xyz
full: https://aarnphm.xyz/llms-full.txt
---
# [#59657](https://github.com/aarnphm/aarnphm.github.io/issues/59657) \[Agents\] Add pre-commit check for agent files and skills

[vllm-project/vllm#59657](https://github.com/vllm-project/vllm/pull/59657) · mgoin · MERGED · created 2026-10-01T17:38:10Z · merged 2026-10-02T16:38:23Z

## 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](https://github.com/aarnphm/aarnphm.github.io/issues/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](https://agentskills.io/specification));
- 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](https://github.com/aarnphm/aarnphm.github.io/issues/57088) | unquoted colon in `description` (frontmatter is not valid YAML), and no symlink |
| [#57786](https://github.com/aarnphm/aarnphm.github.io/issues/57786) | no symlink                                                                      |
| [#50527](https://github.com/aarnphm/aarnphm.github.io/issues/50527) | real `SKILL.md` under `.claude/skills`                                          |

## Details

**Removing `CLAUDE.md`.** [#58541](https://github.com/aarnphm/aarnphm.github.io/issues/58541) removed the root file because Claude Code reads `AGENTS.md` directly. Per the [Claude Code docs](https://code.claude.com/docs/en/memory#agents-md), 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 [#43283](https://github.com/aarnphm/aarnphm.github.io/issues/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. [#58541](https://github.com/aarnphm/aarnphm.github.io/issues/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.

---

<details>
<summary> Pull Request Checklist </summary>

- [x] I used vLLM’s `/pr-checklist` skill. (Mandatory for agents, optional for humans).

- [x] AI assistance was used during the creation of this PR.

- [x] **Design Fit:** Minimizes impact on core components, reuses existing functionality, and justifies added complexity.

- [x] **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.

- [x] **Code Quality and Style:** Keeps code and comments clear and concise, and updates relevant documentation and examples.

- [x] **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.

</details>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---

## comments

**mergify** (2026-10-01T17:38:46Z):

Documentation preview: [https://vllm—59657.org.readthedocs.build/en/59657/](https://vllm--59657.org.readthedocs.build/en/59657/)

**benchislett** (2026-10-01T18:56:41Z):

Thanks!

**mgoin** (2026-10-01T19:49:56Z):

/ci run

**github-actions** (2026-10-01T19:50:17Z):

✅ Triggered [Buildkite CI #92480](https://buildkite.com/vllm/ci/builds/92480) for commit `7209daa0d88f`.

