| name | skill-creator |
| description | Guides repo-local skill creation and updates. Use when adding or editing .agents/skills, root AGENTS.md routing, SKILL.md frontmatter, description trigger quality, references layout, skill scripts, or skill file line budgets. |
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.
- Write
.agents/skills/<skill-name>/SKILL.md with frontmatter plus concise Markdown.
- 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.
- Put deterministic repeated operations in
scripts/ instead of prose.
- Add the skill to the Skill Routing list in the root
AGENTS.md so agents discover it.
- 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
