skill-creator

# 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 `just fmt` 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: ```yaml --- 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: ```yaml 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: ```yaml 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: ```yaml 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: ```sh fd . .agents/skills -t f -e md -x wc -l {} | sort -nr ``` ## References Use reference files when details are conditional: ```text .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.