# Skill Creator

> 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: `ccusage/skill-creator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ccusage/skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ccusage/skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ccusage (https://skillmd.com/u/ccusage)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ccusage/skill-creator

---


# 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:

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