/creating-skill

name: creating-skill
description: Builds and revises a complete skill DIRECTORY — SKILL.md, scripts, references, assets — and packages it. Use for "create a skill for X", "turn this into a skill", "update/improve this skill", "why doesn't my skill trigger", "review this SKILL.md", "package this skill", or when a repeated procedure should become a reusable artifact. Enforces the structure that makes skills work — a concrete procedure rather than a goal statement, an explicit applicability boundary, failure modes with their signals, a runtime verification step, and a description checked against the existing catalogue for confusability. For choosing whether the instruction should be a skill at all rather than project instructions or a prompt, use crafting-instructions. For writing quality inside the prose, use writing-instructions.
metadata:
  version: 2.3.0

Creating Skills

Create portable, reusable expertise that extends Claude's capabilities across contexts.

What a skill is for — read before writing one

A skill is a **procedural anchor**. Measured across 528 paired executions, 65.7% of skill effects come from supplying a usable procedure — setup steps, tool sequence, intermediate checks, pitfalls — and 4.5% from supplying facts the agent lacked (Jiang et al. 2026, arXiv:2608.14036).

Three consequences shape every rule below:

1. **The procedure is the deliverable.** A high-level plan of three to five steps measured at 47.7% success against a 50.0% no-skill baseline. The same experience written as a full SKILL.md measured 79.2%. Vagueness scores worse than silence. 2. **Abstraction costs something.** `skill_guidance_misapplied_or_ignored` runs at 0.8% without a skill and **10.0%** with one. A skill that never says when it does not apply has not paid for itself. 3. **Facts are a reference, not a skill.** Writing one is fine. Call it a reference and do not expect it to change behaviour.

Load [references/skill-utility-evidence.md](references/skill-utility-evidence.md) before authoring or reviewing a SKILL.md. It carries the failure-mode tables behind every requirement here, and reading it is what stops these rules from being followed as ritual.

When to Create Skills

Skills are appropriate when:

• Capability needed across multiple projects/conversations
• Procedural knowledge that applies broadly (not project-specific)
• Instructions should activate automatically on trigger patterns
• Want portable expertise that loads progressively on-demand

Not appropriate when:

• Context is project-specific (use Project instructions instead)
• One-off task (use standalone prompt instead)
• See **crafting-instructions** skill for detailed decision framework

Skill Structure

Every skill is a directory containing:

• `SKILL.md` (required): Frontmatter + imperative instructions
• `scripts/` (optional): Executable code for deterministic operations
• `references/` (optional): Detailed docs loaded on-demand
• `assets/` (optional): Templates/files used in output

Create this structure directly:

mkdir -p skill-name/{scripts,references,assets}

Delete unused directories before packaging.

Naming Convention

Use gerund form (verb + -ing):

• ✅ `processing-pdfs`, `analyzing-data`, `creating-reports`
• ❌ `pdf-helper`, `data-tool`, `report-maker`

Requirements:

• Lowercase letters, numbers, hyphens only
• Max 64 characters
• No reserved words (anthropic, claude)

Frontmatter Requirements

---
name: skill-name
description: What it does. Use when [trigger patterns].
---

**name:** Follow naming convention above

**description:** (max 1024 chars)

• Third person voice: "Processes files" not "I process files"
• WHAT it does + WHEN to use it (trigger patterns)
• Specify: file types, keywords, task types that should activate this skill
• No angle brackets at all — the rule is stricter than "no XML tags". A `->` arrow

or a `>200MB` threshold is rejected on upload just as a `<tag>` is.

**Good examples:**

• "Creates PowerPoint presentations. Use when users mention slides, .pptx files, or presentations."
• "Analyzes SQL queries for performance. Use when debugging slow queries, optimization requests, or EXPLAIN output."

**Ineffective examples:**

• "I can help create presentations" (first person, no triggers)
• "Presentation creator" (no triggers, vague what)
• "Advanced presentation creation with animations" (over-detailed implementation)

The description is critical—it determines when Claude activates this skill.

The description competes against its neighbours

A description is never read alone — it is ranked against every other skill, and the nearest in meaning are what beat it. Confusability, not catalogue size, is the stressor: embedding top-1 falls to 84.1% at a pool of 100 with unrelated distractors and 53.4% with near-neighbour ones, and in a personal catalogue every distractor is a near neighbour.

Four rules, each measured on this catalogue:

1. **Lead with the unit of the question**, not the technology. Users ask about symbols, not about ASTs. 2. **Enumerate literal phrasings a user types.** The skill that scored 4/5 on its own queries is the one whose description contains "de-claude", "humanize this", "this reads like AI". 3. **Separate from a neighbour by OMISSION, never by disclaimer.** A retriever scores bag-of-meaning and cannot represent negation, so "does not debug a Docker build" reads as "Docker build" and pulls you *toward* the thing you disclaimed — measured at +0.05 and +0.10 cosine on two skills. Routing goes in the body under When NOT to use, where an LLM reads it and understands the negation. The description is scored; the body is read. 4. **Do not reuse a sibling's trigger phrases.** `tree-sitting` listed "map this codebase" and "explore repo" — both `exploring-codebases`' territory — and lost all five of its own canonical queries.

**Run the check before shipping.** `oaustegard/claude-workspace