skill-creator

name	skill-creator
description	Guides repo-local skill creation and updates. Use when adding or editing .agents/skills, SKILL.md frontmatter, references, scripts, or skill routing.

Skill Creator

Use this skill when creating or updating repo-local skills under .agents/skills/. Generated .claude/skills content is managed by agent-skills-nix and must not be edited or committed.

Workflow

1. Decide whether a skill is needed. Add one only when repeated repo work needs specialized workflow, local references, command sequences, or policy that should trigger on demand.
2. Create or update .agents/skills/<skill-name>/SKILL.md with YAML frontmatter and concise Markdown instructions.
3. Keep SKILL.md focused on core workflow and navigation. Move detailed examples, APIs, or long checklists into references/ files linked directly from SKILL.md.
4. Add scripts under scripts/ only for deterministic or repeated operations that are better executed than rewritten.
5. Update the root AGENTS.md Skill Routing list when adding a repo-local skill that agents should discover before work.
6. Keep skill and reference files below the line budgets in this guide.
7. Let the Nix dev shell refresh generated local agent skill targets through its shell hook.
8. Run pnpm run format after edits and use the normal repo validation level for the change.

Local Skill Management

Repo-local skills are the source of truth under .agents/skills. The .claude/skills directory is generated by agent-skills-nix through the Nix dev-shell hook, ignored by Git, and should not be used as an edit target.

See nix/agent-skills.nix for the local-only agent-skills-nix wiring. The flake uses nix-filter so only .agents/skills is included in the local skill source. Keep skill source files under .agents/skills; do not add global agent-skills-nix targets or git hook skill sync for this repository.

Frontmatter

Required fields:

---
name: skill-name
description: Describes what the skill does and when to use it.
---

Follow Anthropic's skill authoring guidance from the Agent Skills best practices and skill structure docs:

• The description field is the primary discovery mechanism.
• Write descriptions in third person.
• Include both what the skill does and concrete contexts, trigger phrases, file types, commands, or task classes for when to use it.
• Avoid vague descriptions such as "helps with docs" or "processes files".
• Keep metadata concise because skill names and descriptions are always loaded; Anthropic's size guidance treats frontmatter as roughly 100 words.

Optional file routing fields:

• Use paths for Claude-style file matching. It may be a comma-separated glob string or a YAML list.
• Add globs as a compatibility hint when a skill should trigger for file types across agent runtimes.
• For cross-agent repo-local skills that should apply to TypeScript or JavaScript, include both:

paths:
  - '**/*.ts'
  - '**/*.tsx'
  - '**/*.js'
  - '**/*.jsx'
globs: '*.ts,*.tsx,*.js,*.jsx'

• Do not rely only on path metadata for Codex-style discovery; keep the description explicit about the file types and actions that should trigger the skill.

For this repo, prefer one or two short sentences, usually around 20-35 words. Do not compress a description so far that it becomes only a label; the agent still needs enough trigger context to choose the skill reliably.

Good pattern:

description: Guides ccusage Rust tests. Use when adding or fixing cargo tests, CLI snapshots, Claude model pricing, LiteLLM compatibility, or Rust fixture-backed parser and loader tests.

Weak pattern:

description: Use for tests.

Body

Keep the body procedural and repo-specific:

• Commands to run.
• Files or references to read.
• Local conventions that are easy to miss.
• Validation expected after changes.
• Small examples that prevent common mistakes.

Avoid explaining generic concepts the model already knows. The skill body is loaded only after the skill triggers, but it still competes with task context once loaded.

Line Budgets

Assume some agents may preview only the first 200 lines of a skill or reference file. Keep each file comfortably below that limit, with the most important routing, safety, and workflow instructions near the top.

Targets:

• Keep SKILL.md under 160 lines.
• Keep each references/*.md file under 180 lines.
• Split longer material by decision point or workflow phase, then link the specific file from SKILL.md.
• Do not put required instructions below examples, troubleshooting notes, or optional background.

Audit with:

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

References

Use reference files when details are conditional:

.agents/skills/example-skill/
├── SKILL.md
└── references/
    ├── api.md
    └── examples.md

Link reference files directly from SKILL.md and say when to read each one. Avoid nested reference chains because agents may only preview intermediate files.

Split references by when they are read, not just by heading. If several details will almost always be needed together, keep them in one reference file instead of forcing agents to open multiple small files.