Skill Creator

.agents/skills/ is the source of truth for repo-local skills. .claude/skills is generated by agent-skills-nix through the Nix dev-shell hook and is gitignored — never edit or commit it.

nix/agent-skills.nix holds the local-only wiring, and the flake's nix-filter includes only .agents/skills in the skill source. There are intentionally no global agent-skills-nix targets and no git-hook skill sync here.

Adding or Editing a Skill

Add a skill when repeated repo work needs a workflow, local references, command sequences, or policy that should load on demand. Otherwise extend an existing skill.

1. Write .agents/skills/<skill-name>/SKILL.md with frontmatter plus concise Markdown.
2. Move conditional detail — long checklists, APIs, examples — into references/*.md and link each one from SKILL.md with a line saying when to read it.
3. Put deterministic repeated operations in scripts/ instead of prose.
4. Add the skill to the Skill Routing list in the root AGENTS.md so agents discover it.
5. Run just fmt after edits.

Frontmatter

Frontmatter carries two required fields, name and description.

The description is the primary discovery mechanism: third person, roughly 20-35 words, stating both what the skill does and the concrete triggers (file types, commands, task classes). A bare label like "Use for tests" leaves the agent unable to route. Frontmatter is always loaded, so keep it near Anthropic's ~100-word budget.

Optional routing fields: paths for Claude-style file matching (comma-separated globs or a YAML list) and globs as a cross-runtime compatibility hint — see .agents/skills/typescript/SKILL.md. Codex-style discovery reads the description, so the triggers belong there too.

Body

Write only what the agent cannot derive itself: commands with their exact flags, files to read, local conventions that are easy to miss, deliberate past decisions, and the validation expected after a change. Restating good practice the model already applies only competes with task context.

• Progressive disclosure. The root AGENTS.md is loaded on every session, so it holds only what an agent needs before it knows what it is doing: repo shape, routing, gotchas. Anything that matters only once a task starts belongs in the skill that owns that task.
• One home per rule. A rule in both AGENTS.md and a skill costs tokens twice and drifts. AGENTS.md keeps the one-line routing; the skill keeps the rule. Between two skills, cross-link by name instead of copying, and merge only when neither half earns its own trigger.
• Point at real code. rust/adapters/codex/src/loader.rs, a fixture, or an existing test beats a paragraph paraphrasing the pattern.
• Never transcribe CLI help. Usage lines, flag lists, and subcommand tables go stale and the agent can run <tool> --help. Write the judgment help output cannot give — when to reach for the tool, which of several tools to pick — and point at the tool.
• Link external docs, don't paste them. When a URL is self-descriptive, put it on its own line with no title and no summary sentence; add context only when the reader needs to know why or when to open it.

https://simonwillison.net/2026/Jul/21/cat-and-thariq/

https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models

Line Budgets

Some agents may preview only the first 200 lines of a file, so keep SKILL.md under 160 lines and each references/*.md under 180, with routing, safety, and workflow instructions above examples and background. Split longer material by decision point or workflow phase, but keep details that are always read together in one file rather than forcing several opens. Reference files are linked directly from SKILL.md; nested reference chains can be missed.

Audit lengths with:

fd . .agents/skills -t f -e md -x wc -l {} | sort -nr