AGENTS.md

Context for coding agents that work in this repository. This repo holds agent skills about Rust; it contains no Rust crate and no build system. Do not add one. The compile harness in checks/ and the fixture crates in evals/outcome/ are test inputs, not products.

Project overview

rust-skills is a public catalog of agent skills for Rust work, distributed through skills.sh and installed with the vercel-labs skills CLI. The content must stay free of private identifiers.

Layout is flat. One directory per skill:

skills/<name>/SKILL.md          the skill itself, always present
skills/<name>/references/*.md   optional deep material, loaded on demand
README.md                       the catalog table, the install bundles, and the routing graph
bundles.toml                    install bundles: bundle -> ordered skill names
AGENTS.snippet.md               the always-on router a consumer pastes; every skill once
.claude-plugin/                 the plugin marketplace for Claude Code and Codex, one plugin per bundle
scripts/validate-skills.py      catalog checks (tests: scripts/test_validate_skills.py)
scripts/agent-hook.py           post-edit hook that runs the validator for agents (tests: scripts/test_agent_hook.py)
.claude/settings.json           Claude Code project settings: the post-edit hook
.codex/hooks.json               Codex project hooks: the same post-edit hook
scripts/catalog-ceilings.toml   ratchet: accepted values over a limit, which may only shrink
scripts/drift-report.py         toolchain and crate drift report behind the weekly workflows
tests/routing-cases.md          phrase -> skill, checked against every description
evals/                          routing, plugin, and outcome evaluations; evals/README.md says what they prove
checks/                         compile-check harness for the rust examples; check.sh runs CI
docs/releasing.md               tags, versioning, evaluations before a tag, repository settings
CHANGELOG.md, SECURITY.md       release history; security scope and how to report
.github/                        CI, drift, client-compat, and plugin-eval workflows; CODEOWNERS; templates
research/                       primary-source findings and catalog decisions

There is no nesting below skills/<name>/, apart from references/. Do not add scripts, assets, or index files unless a task asks for them.

The SKILL.md contract

Each SKILL.md starts with YAML frontmatter that follows the Agent Skills specification. Three keys, and nothing else by default:

---
name: rust-unsafe
description: Use when adding or reviewing an unsafe block, a raw-pointer dereference, or a transmute ... Covers E0133, E0793, and unsafe attributes.
license: BSD-3-Clause
---

Rules:

• name must equal the directory name. Use lowercase letters, digits, and hyphens.
• description is one line, 1024 characters maximum. It is the only text an agent reads before it decides to open the skill, and some runtimes keep only its start when many skills are installed: Codex 0.166.0 cuts each description to share one skill-list budget, so the start is the part every runtime shows. Start with Use when and the task, then put the strongest trigger terms in the first sentence. Say what the skill covers in one clause. Prefer categories of user intent over keyword lists; keep exact tokens a user pastes (error codes, lint, tool, crate, and API names). Aim for 300 to 600 characters. Do not write "you", a capability inventory, or a catch-all such as "any Rust change". Add a "not for X" boundary only where a sibling skill is a likely misroute.
• license is BSD-3-Clause for every skill in this repo.
• Add no other frontmatter key unless a task asks for it.

The body starts at an # Title heading directly after the frontmatter.

Authoring conventions

• Write in ASD-STE100 Simplified Technical English: short sentences, simple present tense, active voice, one instruction per sentence.
• Use the imperative for instructions. Write Run cargo nextest run --no-fail-fast, not You may want to consider running the tests.
• Give concrete commands, flags, file names, and thresholds. Generic advice has no value in a skill; the agent already knows it. Keep Rust-specific guardrails that prevent a correctness, soundness, security, ABI, release, or tooling error, even when a strong model often knows them.
• Remove every project-specific path, crate name, package name, and internal tool name. The skills must apply to any Rust workspace.
• Tag every code block with a language: rust, bash, toml, yaml, kotlin, swift, text.
• Keep SKILL.md under 500 lines and 4,800 estimated tokens; the validator enforces both. Put gotchas, triage tables, verifier commands, and escalation rules first. Move conditional material, long examples, and background to references/<topic>.md. Link each reference from SKILL.md at the point of need with the condition to read it ("Read references/x.md when ..."). A reference over 100 lines starts with a short contents list.
• Do not add a "When to use this skill" section. The description does that job, and the body loads only after the agent chose the skill.
• Name another skill by its name only ("the rust-security skill, when it is installed"). An install of one skill has no sibling directories, so a path into another skill is a dead link. For a skill in another bundle, state the rule in one sentence with a command or API name.
• Give each rule one home in the catalog. Other skills point to the owner in one line.
• State the verifier: which command proves which claim, when to run it, and what a green result does not prove. Scale it to the risk. Do not add "double-check" or "verify again" steps.
• Use "never", "always", "must", and severity labels only for a correctness, safety, data-loss, or irreversible-release hazard, and give the reason. Mark a team preference as a default.
• Skills run on many models and agents. Do not describe how a model behaves, and do not require a harness feature (subagents, plan mode, nightly, a specific test runner) without a fallback.
• Label a dated fact with its version or date ("as of Rust 1.98.1"). Do not write "at time of writing". Re-run a measurement before you change its toolchain label.
• Prefer a triage table (symptom, cause, fix) over prose for failure handling.
• Compile any Rust example that is meant to be complete before you commit it. bash checks/check.sh does this for the whole catalog. A snippet that does not compile teaches the wrong thing with full confidence.
• Never write a function with an empty body under a non-unit return type. fn f() -> Result<T> { // implementation } does not compile; write todo!(). This is the single most common defect the compile check finds.
• Never define one name twice in a single code block to show a before and an after. Use two blocks. One block cannot hold both, and a reader cannot tell which definition is live.
• Tag a fence that must not compile: ```rust,compile_fail for a deliberate error demonstration, and name the code when you know it: ```rust,compile_fail,E0499. The gate then requires that code, so the block proves what the prose says it proves.
• Tag a portable behavior probe ```rust,run and define fn main(). CI first requires clean compilation, then builds and runs it on the native host. Keep it on the standard library. A run block cannot contain TODO, FIXME, todo!(), or unimplemented!().
• Tag ```rust,ignore only for code no cargo check can judge: a build-script include!, a nightly-only feature, a failure that arrives at monomorphization, or a crate the harness cannot hold (the list is in checks/Cargo.toml). It is the one way out of the gate, and nothing else removes a block from it. Prefer fixing the example.

How to add a skill

1. Create skills/<name>/.
2. Write skills/<name>/SKILL.md with the frontmatter above and a body that follows the authoring conventions. Add skills/<name>/references/*.md only for material that is conditional or does not fit in the size budget.
3. Add one row to the catalog table in README.md, in the section that matches the subject. Link the name to skills/<name>/SKILL.md. Add one node to the routing diagram, one row to AGENTS.snippet.md, and the name to one bundle in bundles.toml and its plugin entry in .claude-plugin/marketplace.json. Every skill appears exactly once in each.
4. Add at least one row to tests/routing-cases.md: a phrase a user is likely to type, and the new skill. The phrase must appear in the new description, early enough that Codex still shows it once the new skill shares the bundle's budget. CI checks both; check.sh checks the Codex part only when npx is available. A skill with no routing case fails validation. The check is a regression lint, not proof that routing works: do not add a keyword to a description only to satisfy it.

How to verify a change locally

One command runs every gate CI runs, on the toolchain checks/rust-toolchain.toml pins:

bash checks/check.sh

A green run locally means a green run in CI. The gates that can be missing are the skills-CLI discovery step and the Claude Code and Codex plugin install steps, which all need npx; check.sh says so when it skips them. check.sh writes only under checks/ and a temporary directory, so run and rerun it without asking.

While you edit descriptions, bundles.toml, or .claude-plugin/, run the fast form. It skips the cargo gates (the example compile check, the behavior probes, and the outcome fixtures) and keeps the catalog, unit-test, and client gates. With warm npx caches it takes under a minute, against about two and a half for the full run (measured 2026-11-02). A green --fast run is not a green CI run: run the full command before a pull request.

bash checks/check.sh --fast

CI splits the same command in two jobs. Validate catalog runs --fast, and Compile-check examples runs --no-clients, which skips the three npx gates. Both jobs run the catalog and unit-test gates; each cargo gate and each client gate runs in one job only.

.claude/settings.json (Claude Code) and .codex/hooks.json (Codex) run scripts/agent-hook.py after each file edit. When the edit touches a file that scripts/validate-skills.py reads, the hook runs the validator and, on a failure, gives its problems to the agent next to the tool result, so the agent fixes them in the same turn. Claude Code runs the hook in a trusted folder; Codex runs it once you trust it in /hooks. A client loads the hook of the folder where its session starts, so an edit in another worktree gets no report. The hook covers the validator only; it does not compile examples or install plugins, and it stays silent when it cannot run (no script, no git root, or a Python without tomllib). Tests: scripts/test_agent_hook.py.

1. Catalog structure

python3 scripts/validate-skills.py checks, for every skill:

• frontmatter keys stay inside the spec with the three required keys; name equals the directory name; description is one plain line of 80 to 1024 characters; SKILL.md is at most 500 lines;
• every frontmatter value survives a real YAML parser unchanged: no : , no #, no leading indicator character, because the skills CLI and the agent runtimes read the file with one;
• every Markdown link resolves from the file that holds it and stays inside the skill directory, every references/*.md code span exists, and no file names a skills/<name>/ repository path;
• every phrase in tests/routing-cases.md still appears in the description it routes to, and every skill has at least one routing case;
• the README catalog and its Mermaid routing graph name every skill on disk exactly once;
• every skill is in exactly one bundle of bundles.toml, and each bundle has a README install row; AGENTS.snippet.md names every skill exactly once in at most 60 lines;
• .claude-plugin/marketplace.json has the full-catalog plugin and one <name>-<bundle> plugin per bundle, each with source "./", the bundle's skills in bundles.toml order, a correct "N Rust agent skills" count, the BSD-3-Clause license, and no version; and no .claude-plugin/plugin.json exists (docs/releasing.md says why for both);
• descriptions stay under 5,000 characters per bundle (about 2,000 tokens, the skill listing of a 200K-context client) and 20,000 in total, and each body stays under 4,800 estimated tokens (characters / 2.5; the calibration is in research/token-calibration-2026-10.md);
• a reference to a skill in another bundle carries a fallback with a code span in the same or the next sentence, and no description claims a phrase of evals/routing/negative-cases.md.

A value already over a limit sits in scripts/catalog-ceilings.toml. The validator fails when it grows and warns when it shrinks; then lower the entry, or remove it once the value is under the limit. Never raise an entry to make a change pass; the one exception is a cross-bundle fallback sentence, which may raise body_tokens by its own size. --report budget prints sizes, and --report cross-refs lists every reference that has no fallback.

2. Compile and behavior-check the examples

Every ```rust block in skills/ is read, and its fence decides what happens to it; the rules are under "Authoring conventions" above, and checks/README.md has the phases and commands. checks/baseline.txt is empty and should stay empty: fix the example instead of adding a line. A block that names a type or value the prose defines is a fragment, and rustc checks nothing that touches that name. Supply the name in checks/preludes/<skill>.toml. A fragment that checks/fragments.txt does not list fails the gate; that file holds two blocks no prelude can complete, so do not add to it. Add a crate to checks/Cargo.toml when a skill starts using it, or every block that imports it silently degrades to a fragment.

check.sh then runs npx skills add ./ --list, which lists the skills and installs nothing. Run it after any frontmatter edit. The CLI and the agent runtimes parse frontmatter with a real YAML parser: a : in a description once hid a whole skill, and a # cut one in half. plain_scalar_problem in scripts/validate-skills.py rejects both, but the CLI is the only end-to-end proof.

Next, check.sh runs checks/plugin_install.py with the Claude Code CLI that CLAUDE_CODE_VERSION in check.sh pins. In a throwaway config directory it runs claude plugin validate ., adds this checkout as a marketplace, installs the full-catalog plugin and one plugin per bundle, and compares the skills of claude plugin details with skills/ and bundles.toml. A marketplace entry that is neither fails. It needs no API key and does not touch ~/.claude. Run it after any edit to .claude-plugin/ or bundles.toml. A green result proves what a local-path install loads, which Claude Code reads in place; it does not prove a GitHub install, which copies the plugin to the cache.

Last, check.sh runs the same script with the Codex CLI that CODEX_VERSION pins. Codex copies the whole marketplace root into its cache, ignored build output included, so the script first exports the files git tracks or would track. For each plugin it uses a new throwaway CODEX_HOME and an environment without OPENAI_* or CODEX_* variables, runs codex plugin marketplace add on the export and codex plugin add, and compares the plugin's skills in codex debug prompt-input, the list a session puts in front of the model, with skills/ and bundles.toml. It does not prove a Git-hosted marketplace or a model's choice of skill.

The same Codex run checks what each description still says after Codex shortens it. Codex shares one budget for the skill list among every listed skill and cuts each description to fit. In a fresh install, with only Codex's four own skills beside the plugin, every bundle must show every tests/routing-cases.md phrase of its skills; one cut-off phrase fails the gate. Fix a failure by moving the phrase toward the start of its description, or by shortening the descriptions of that bundle. The full-catalog plugin only prints its count, because it overflows the budget. Codex also lists the skills under ~/.agents/skills, so the gate moves HOME to a throwaway directory as well, and it fails when any other skill shares the list. A green result covers the default budget of a fresh install; a consumer with other skills installed sees shorter descriptions.

What main enforces

Branch protection, not convention, guards main: it requires the Validate catalog and Compile-check examples checks and a Code Owners review, and rejects direct pushes, force-pushes, deletion, and unsigned commits (docs/releasing.md lists every setting). npx skills add copies main into consumers' agent directories, so an unchecked commit is a supply-chain change.

Do not run skills remove inside this repository

npx skills remove --skill <name> treats this repository's own skills/ directory as an install location and deletes the source directory, even when you never ran skills add. The deletion is silent and not staged in git, so an uncommitted skill is lost outright. Use npx skills add ./ --list or npx skills use ./ --skill <name> to inspect; neither writes to skills/. Test an install and a removal in a scratch directory, never in this checkout.

Pull request conventions

• One skill per pull request where practical. A catalog-wide edit, such as a rename of a shared term, may touch many files in one pull request.
• Commit subject: skill(<name>): <what changed>, for example skill(rust-unsafe): add Tree Borrows review checklist. For repository-level files use docs: <what changed> or chore: <what changed>.
• Do not mention Claude, Claude Code, or Anthropic in commit messages or pull request text.
• Do not add Co-Authored-By trailers.
• Update the README.md catalog row in the same pull request that adds or renames a skill.

Releases and evaluations

Tag every catalog actualization, on a green main commit only. The plugin never sets version, so its version is the installed commit SHA. Run evals/plugin before every tag and after any model-default change, and record the results in research/ with the model IDs. docs/releasing.md has the release commit, the versioning rule, and the evaluation commands.