skill-creator

name	skill-creator
description	Guides authoring agent-facing instructions following Anthropic's SKILL.md best practices. Use when adding or editing skills under `agents/skills/`, rules in `claude/rules/`, `CLAUDE.md`, or `agents/shared/` fragments — frontmatter, references, and routing included.

Skill Creator

Use this skill when creating or updating local skills under agents/skills/ in this dotfiles repo. They are deployed to ~/.agents/skills/ and ~/.config/claude/skills/ via nix/modules/home/agent-skills.nix (auto-enabled by skills.enableAll = [ "local" ]).

The Body and Documentation references sections below apply to every agent-facing instruction file here, not just skills: claude/rules/*.md, claude/CLAUDE.md, and agents/shared/*.md. Rules and CLAUDE.md are loaded on every session, so they are the least forgiving place to be verbose — keep them to judgement the agent cannot derive on its own.

Workflow

1. Decide whether a new skill is needed. Add one only when repeated work needs a specialised workflow, local references, command sequences, or policy that should trigger on demand. Otherwise extend an existing skill.
2. Create or update agents/skills/<skill-name>/SKILL.md with YAML frontmatter and concise Markdown.
3. Keep SKILL.md focused on workflow and navigation. Move detailed examples, APIs, or long checklists into references/*.md linked directly from SKILL.md.
4. Add scripts under scripts/ for deterministic, repeated, or fragile operations — see the Scripts section below for when a script beats inline commands.
5. Stage only the skill directory and deploy: git add agents/skills/<skill-name> && nix run .#switch. Avoid git add . so unrelated working-tree changes (especially nix/modules/home/programs/codex.nix, which can contain private repo names) are not picked up. agent-skills.nix enables every directory under local automatically — no allow-list edit needed.

Frontmatter

Required fields:

https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices

---
name: skill-name
description: One or two sentences. What the skill does and when to use it.
---

Constraints:

• name: max 64 chars, lowercase letters / numbers / hyphens only, no anthropic or claude.
• description: max 1024 chars, non-empty, third person, no XML tags. Include both what and when. Frontmatter is always loaded, so keep it tight — aim for ~20-35 words (~100-250 chars).

Good:

description: Creates atomic Conventional Commits. Use when committing code changes, splitting hunks into revertable units, or writing detailed commit messages.

Bad:

# Vague
description: Helps with commits.
# First person
description: I can help you write commits.
# Way too long, no clear trigger
description: This skill is a comprehensive commit assistant that analyses changes and produces beautifully formatted commit messages following all the best practices...

Body

Keep the body procedural and repo-specific:

• Commands to run, with exact flags.
• Files or references to read.
• Local conventions that are easy to miss.
• Validation expected after changes.
• Small good/bad examples that prevent common mistakes.

Avoid explaining generic concepts the model already knows. Aim for under 500 lines; split larger content into references/.

Rules that are easy to violate without noticing:

• One term per concept, used consistently throughout.

• No time-sensitive wording ("after August 2025…"); put superseded guidance in an "old patterns" section instead.

• Concrete examples, never abstract placeholders.

• One default per task, not a menu of equivalent options.

• Forward-slash paths only.

• MCP tools written as Server:tool_name.

• Reference links one level deep from SKILL.md — agents only preview nested files.

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

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

• https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

Documentation references

Don't paste large chunks of external docs into the skill — they go stale and cost tokens. Point at the authoritative source instead:

• When a URL is self-descriptive, include the URL directly without adding a title or summary.

• Public docs: include the canonical docs URL (e.g. https://vitest.dev/api/) so the agent can fetch the current version when needed.

• Installed libraries: if the skill is about a package present in node_modules/, instruct the agent to read the docs the package ships locally — they match the installed version and need no network. Many packages now publish docs on npm for exactly this.

https://ryoppippi.com/blog/2025-12-14-publish-docs-on-npm-en

For API details, read `node_modules/<package-name>/README.md`
(or `node_modules/<package-name>/docs/**/*.md` if the package ships a docs folder).

Find them with fd README.md node_modules/<package-name> or fd -e md . node_modules/<package-name>/docs.

• CLI tools: never transcribe usage, flags, or subcommands — the agent can run <tool> --help itself, and a copy goes stale. Write the judgement the help output cannot give (when to reach for the tool, which of several tools to pick, what not to do with it) and point at <tool> --help for the mechanics.

  Clone it with `ghq` instead of `git clone` into `/tmp`. See `ghq --help` for usage.
  

• Relevant repo files (local skills only): if concrete files in this repo are the source of truth for the skill, list them by path so the agent reads the real thing instead of a stale copy. The vitest-testing skill's Key Files section is the model — it names vitest.setup.ts, test-db.ts, etc. by path.

Overlap between skills

When two skills cover related ground, prefer the lightest fix that removes the duplication:

1. Cross-link — if each skill is still distinct but they touch, link them by name rather than copying text. E.g. vitest-testing says "Use the tdd skill when …". The shared detail lives in one skill; the other points to it.
2. Merge — only when the skills are genuinely the same workflow and neither earns its own trigger. Fold one into the other and delete the empty directory.

Never paste the same instructions into two skills — pick a single home and link to it.

Dynamic context

Use !`command` inside fenced blocks to inject live state (current branch, tool version, detected test runner). Prefer dynamic blocks for environment info; keep static text for workflow steps and best practices.

https://code.claude.com/docs/en/skills#inject-dynamic-context

References

Two thresholds for SKILL.md length:

• ~150 lines — consider splitting. Once the body passes this, it is usually no longer a tight, scannable workflow. Move conditional or long-form detail into references/*.md. The vitest-testing skill is the model: a ~50-line SKILL.md that routes to ten focused references/*.md files.
• ~500 lines — hard ceiling (Anthropic guidance). Never exceed this; split aggressively before you get here.

Reference files load only when the agent follows the link, so splitting keeps the always-loaded surface small without losing detail. When a skill passes the soft threshold, or when deciding whether a section earns its own file, read references/splitting.md.

Scripts

When an operation is deterministic and repeated, add a script under scripts/ — it is executed, not loaded, so only its stdout costs tokens. For when to use one and the rules (execution intent, shebangs, error handling, no magic constants), read references/scripts.md.

Token budget

Skill metadata (name + description across all skills) is preloaded into the system prompt. If Codex or Claude reports descriptions were trimmed to fit the skills context budget, shorten descriptions first, then disable unused skills in agent-skills.nix.