Agent-Skills.md

Agent Skills: Skill Creator

Use when running the skill validator or applying frontmatter conventions (trigger-led description, <=250 chars). Triggers on "validate skill", "skill validator", "skill-creator", "create skill", "lint skill", "skill compliance", "sharpen skill".

UncategorizedID: buvis/home/create-skill

Repository

buvis/home
buvis
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/buvis/home/tree/HEAD/.claude/skills/create-skill

Skill Files

Browse the full folder contents for create-skill.

Download Skill

Loading file tree…

.claude/skills/create-skill/SKILL.md

Skill Metadata

Name
create-skill
Description
Use when running the skill validator or applying frontmatter conventions (trigger-led description, <=250 chars). Triggers on "validate skill", "skill validator", "skill-creator", "create skill", "lint skill", "skill compliance", "sharpen skill".

Skill Creator

Create effective skills that extend Claude Code with specialized knowledge, workflows, and tools.

About Skills

Skills are modular packages that give Claude Code procedural knowledge it cannot derive from the codebase alone. A skill is a directory with a required SKILL.md and optional supporting files.

Skills follow the Agent Skills open standard. They work across Claude Code, Claude.ai, and other adopting tools.

What Skills Provide

  1. Specialized workflows - multi-step procedures for specific domains
  2. Tool integrations - instructions for working with specific file formats or APIs
  3. Domain expertise - company-specific knowledge, schemas, business logic
  4. Bundled resources - scripts, references, and assets for complex and repetitive tasks

Core Principles

Concise Is Key

The context window is a shared resource. Skills share it with the system prompt, conversation history, other skills' metadata, and the user's request.

Default assumption: Claude is already very smart. Only include knowledge Claude does not already have. Challenge each piece of information: "Does Claude really need this?" and "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations.

Set Appropriate Degrees of Freedom

Match specificity to fragility and variability:

High freedom (text instructions): Multiple approaches are valid, decisions depend on context.

Medium freedom (pseudocode or parameterized scripts): A preferred pattern exists but some variation is acceptable.

Low freedom (specific scripts, few parameters): Operations are fragile, consistency is critical, or a specific sequence must be followed.

Think of it as path width: a narrow bridge with cliffs needs guardrails (low freedom), while an open field allows many routes (high freedom).

Anatomy of a Skill

skill-name/
├── SKILL.md           (required - frontmatter + instructions)
├── scripts/           (optional - executable code)
├── references/        (optional - docs loaded into context as needed)
└── assets/            (optional - files used in output, not loaded into context)

SKILL.md (required)

  • Frontmatter (YAML between --- markers): name and description control when the skill triggers. The description is the primary trigger mechanism - Claude reads it to decide relevance. All "when to use" information belongs here, not in the body.
  • Body (Markdown): Instructions loaded only AFTER the skill triggers.

See references/frontmatter.md for the complete field reference.

scripts/

Executable code for tasks requiring deterministic reliability or that would otherwise be rewritten repeatedly.

  • Scripts can be executed without loading into context (token-efficient)
  • Claude may still read scripts for patching or environment-specific adjustments
  • Always test scripts by running them before shipping

references/

Documentation loaded into context on demand to inform Claude's process.

  • Database schemas, API docs, domain knowledge, company policies
  • Keeps SKILL.md lean while making information discoverable
  • For large files (>10k words), include grep search patterns in SKILL.md
  • Information should live in either SKILL.md or references, not both

assets/

Files used in output, not loaded into context.

  • Templates, boilerplate code, images, icons, fonts
  • Claude copies or modifies these files as part of the output
  • Example: assets/hello-world/ for a frontend boilerplate project

What NOT to Include

  • README.md, INSTALLATION_GUIDE.md, CHANGELOG.md, or other auxiliary docs
  • Setup and testing procedures
  • User-facing documentation about the skill itself

A skill contains only what Claude needs to do the job.

Progressive Disclosure

Skills use a three-level loading system:

  1. Metadata (name + description) - always in context (~250 chars max)
  2. SKILL.md body - when skill triggers (<500 lines recommended)
  3. Bundled resources - as needed (unlimited; scripts can run without context loading)

Keep SKILL.md under 500 lines. Split content into separate files when approaching this limit. When splitting, reference files from SKILL.md and describe clearly when to read them.

See references/patterns.md for progressive disclosure patterns.

Skill Creation Process

  1. Understand the skill with concrete examples
  2. Plan reusable resources (scripts, references, assets)
  3. Initialize the skill directory
  4. Edit the skill (implement resources and write SKILL.md)
  5. Validate the skill
  6. Iterate based on real usage

Naming

  • Lowercase letters, digits, and hyphens only; max 64 characters
  • Prefer short, verb-led phrases that describe the action
  • Namespace by tool when it improves clarity (e.g., gh-address-comments)
  • Directory name must match the skill name

Step 1: Understand the Skill

Skip only when usage patterns are already clearly understood.

Gather concrete examples of how the skill will be used:

  • "What should this skill support?"
  • "Can you give examples of how it would be used?"
  • "What would a user say that should trigger this?"

Ask the most important questions first. Avoid overwhelming the user. Conclude when there is a clear sense of the skill's scope.

Step 2: Plan Reusable Resources

For each concrete example, consider:

  1. How would you execute this from scratch?
  2. What scripts, references, or assets would help when doing this repeatedly?

Examples:

  • PDF rotation: same code each time -> scripts/rotate_pdf.py
  • Frontend webapp: same boilerplate each time -> assets/hello-world/
  • BigQuery queries: rediscovering schemas each time -> references/schema.md

Step 3: Initialize the Skill

Run the init script to generate a template:

python3 ~/.claude/skills/create-skill/scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets]

Examples:

python3 ~/.claude/skills/create-skill/scripts/init_skill.py my-skill --path ~/.claude/skills
python3 ~/.claude/skills/create-skill/scripts/init_skill.py my-skill --path .claude/skills --resources scripts,references

Skip this step if the skill already exists and you are iterating.

Step 4: Edit the Skill

The skill is being created for another instance of Claude to use. Include information that is beneficial and non-obvious. Think: what procedural knowledge, domain-specific details, or reusable assets would help Claude execute these tasks?

Start with Resources

Implement scripts/, references/, and assets/ files first. This may require user input (e.g., brand assets, API docs). Test scripts by running them.

Write SKILL.md

Frontmatter:

  • name: the skill name (lowercase, hyphens, max 64 chars)
  • description: the primary trigger mechanism. Keep under 250 characters (the validator warns above 250). All "when to use" info goes here - the body is only loaded after triggering.

See references/frontmatter.md for additional frontmatter fields (invocation control, subagent execution, tool permissions, etc.).

Writing effective descriptions:

Descriptions must describe triggering conditions, not summarize the skill's workflow. When a description summarizes workflow, Claude may follow the description as a shortcut instead of reading the full skill body.

# BAD: summarizes workflow - Claude may follow this instead of reading skill
description: Deploy to staging by running tests, building docker image, and pushing to k8s

# GOOD: trigger conditions only
description: Use when deploying to staging. Triggers on "deploy staging", "push to staging".
  • Start with "Use when..." to focus on triggers
  • Include specific symptoms, scenarios, and file types
  • Write in third person (injected into system prompt)
  • Use keywords Claude would search for (error messages, tool names, symptoms)

Body: Use imperative/infinitive form. Structure by workflow, task, reference, or capabilities - whichever fits the skill's purpose.

Dependencies: if the skill needs anything outside its own directory - another skill, a plugin skill, an external CLI, a file under ~/.claude, an external service - state it in a ## Dependencies section right after the intro. Name each dep and what happens when it is missing (hard failure, or which fallback runs). Namespace plugin skills as plugin:skill. Frontmatter is the wrong home for this: metadata never reaches the model at runtime, the body loads exactly when the skill triggers. See brush or run-autopilot for the shape.

Design for compliance: a skill that runs unattended, on another harness, or produces evidence-based conclusions (research, audit, exploration) gets executed by an agent under pressure. Design enforcement in from the start instead of discovering it over benchmark rounds: demand checkable artifacts (receipts, machine-parseable status lines, gates that echo numbers) instead of adverbs; bundle a self-check script and define done as "checker passes, output pasted"; give every run an honest-partial path (INCOMPLETE that ships) so faking is never the only road to COMPLETE; split gather-from-write across fresh sessions where fabrication is possible. Mechanisms and evidence: references/sharpening.md.

Token efficiency:

  • Frequently-loaded skills: aim for <200 words total
  • Other skills: <500 words in SKILL.md body
  • Move heavy reference to separate files
  • Don't repeat what's in cross-referenced skills
  • Reference other skills by name, not @ paths (@ force-loads files, burning context)

Before validating, scan references/common-pitfalls.md for friction patterns hit by prior skill builds: cross-script imports in flat scripts/, Echo's name-led duplicate detection, missing chmod +x on scripts, path solicitation for user-supplied files (skills don't take CLI args), batched state changes (per-decision changes must be enforced as immediate, not eventual), "three options" must mean three distinct alternatives (not "mine + your own + skip"), card-text and picker-options must share one canonical order AND one label scheme (otherwise users re-map between A/B/C/D and 1/2/3/4 and trust drops), review-style skills need a comprehension pass before a critique pass (without it, findings drift to surface flaws and miss structural issues), and the inline-awk recipe for migrating from a monolithic command file.

Step 5: Validate the Skill

Run the validator to check structure, frontmatter, AND every fenced bash command against the environment it will actually run in (aegis prefer_tools deny set, the permission allowlist, and the no-persistent-shell contract):

python3 ~/.claude/skills/create-skill/scripts/validate_skill.py <path/to/skill-folder>

Fix any reported errors and re-run. The live-profile lints are ERRORs, each naming its replacement: grep/find/cat/head/tail (even inside pipes) → rg/Read/bare-run; a standalone NAME=value assignment → inline the value (shell state never survives to the next Bash call); a cd x && y chain → use absolute paths; a bare script path outside a skills dir → invoke via its interpreter; an author $VAR → inline it or use ${CLAUDE_SKILL_DIR}. A skill that ships commands its own hooks would deny is self-sabotage; this gate is where it stops (PRD 00083).

Step 6: Iterate

Casual iteration: use the skill on real tasks, notice struggles, update, retest.

Sharpening a skill that must perform unattended or on another harness is benchmark work; run it as a controlled loop or it eats days (full protocol in references/sharpening.md):

  1. Preflight the harness before every run: current copy synced (symlinks dereferenced, scripts/ + references/ present), explicit slash activation, model pinned, fresh session with priors hidden. A run on a broken harness produces zero signal on the skill text.
  2. Kill early: no first mandatory artifact within minutes means a dead run; kill it and fix the harness instead of paying for the full iteration.
  3. Eval against a frozen baseline, one eval file per iteration; fixes stay generic (benchmark specifics go to examples); where the run beats the baseline, improve the baseline in place.
  4. Never restate an ignored rule - diagnose why it was ignored, then escalate that failure one level: prose rule -> forced artifact -> mechanical check -> coupling check -> structural change. A failure on its third round jumps straight to structural.

Platform Details

See references/platform.md for:

  • Skill placement hierarchy (personal, project, enterprise, plugin)
  • String substitutions ($ARGUMENTS, ${CLAUDE_SKILL_DIR}, etc.)
  • Dynamic context injection with shell commands
  • Invocation control matrix
  • Relationship to legacy .claude/commands/ files