creating-skills

name	creating-skills
description	Create Claude skills following best practices: structure, naming, descriptions, progressive disclosure, testing, and converting sources into skills. Use for authoring or improving skills, or encoding a book, guide, codebase, PR history, or visual reference corpus into skills. Triggers: create a skill, SKILL.md, taste.md, convert this book/repo/images to a skill.

Official Documentation

Conversion playbooks (read the matching reference): references/converting-books-to-skills.md (books/guides/docs -> skills) · references/converting-codebases-to-skills.md (OSS repos + PR history -> skills) · references/converting-visual-references-to-skills.md (image/reference corpora -> visual-taste skills) · references/skill-creator.md (Anthropic's bundled guide + init/package scripts). Source map: references/sources.md; parked candidates: references/coverage-gaps.md.

• Skills Overview — How skills work, architecture, structure
• Quickstart — Create your first skill
• Best Practices — Authoring guidelines
• Using Skills with the API — Programmatic usage

Core Principles

1. Concise is Key

The context window is shared. Only add what Claude doesn't already know.

Ask yourself:

• "Does Claude really need this explanation?"
• "Can I assume Claude knows this?"
• "Does this paragraph justify its token cost?"

Details: references/conciseness.md

2. Set Appropriate Degrees of Freedom

Freedom Level	Use When	Example
High (text instructions)	Multiple approaches valid	Code review guidelines
Medium (pseudocode)	Preferred pattern exists	Report generation template
Low (exact scripts)	Operations are fragile	Database migrations

Details: references/degrees-of-freedom.md

3. Test with All Models

Skills effectiveness depends on the underlying model.

Model	Consider
Haiku	Does the skill provide enough guidance?
Sonnet	Is the skill clear and efficient?
Opus	Does the skill avoid over-explaining?

SKILL.md Structure

---
name: skill-name (lowercase, hyphens, max 64 chars)
description: What it does + when to use it (max 1024 chars)
---

[Body content - under 500 lines]

Details: references/skill-structure.md

Naming Convention

⚠️ House divergence — this corpus uses noun phrases, not gerunds (House Style rule 4 below): "hardware-product-design", not "designing-hardware". The gerund form below is the official suggestion; both are sanctioned, but match the corpus you're in.

Official suggestion: gerund form (verb + -ing):

Good	Avoid
processing-pdfs	helper
analyzing-spreadsheets	utils
managing-databases	documents

Writing Descriptions

Always write in third person. The description is injected into the system prompt.

Template (official minimal shape — in this corpus, use the fuller House Style rule 1 shape: what + when + boundary clause + triggers, ~350–450 chars):

[What it does]. Use when [trigger context].

Example:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Details: references/description-writing.md

Progressive Disclosure

SKILL.md is an overview that points to detailed materials. Claude reads files on-demand.

skill-name/
├── SKILL.md              # Overview (< 500 lines)
├── reference.md          # Detailed guide (loaded when needed)
├── examples.md           # Usage examples
└── scripts/
    └── utility.py        # Executed, not loaded into context

Key insight: Scripts' outputs consume tokens, not their contents.

Details: references/progressive-disclosure.md

House Style (this corpus — 2026-06 audit)

Rules layered on top of the official guidance, derived from a ~40-skill corpus with a routing eval:

1. Descriptions: ~350–450 chars, never the 1024 cap. The cap is an API limit, not a budget; all descriptions preload into every session (~40 × 450 ≈ 4.5k tokens here). Shape: What it does (verb-led). Use when <3–5 situations>. <Boundary clause>. Based on <credit>. Triggers: <6–8 query-like terms>. The validator warns >700.
2. Boundary clauses are sacred. Dense corpora have near-neighbors (8 Rails skills, 5 SwiftUI skills, 6 motion/polish skills). Clauses like "DEFAULT school; escalate on named pains" or "Distinct from X's perf audit" exist because of real routing misses — compress, never drop. The official one-liner examples assume no neighbors; the shape generalizes, the length doesn't.
3. The routing eval is the gate. After any description change, new skill, or consolidation, run routing probes: give a fresh agent the descriptions only and a set of realistic prompts, and check each routes to the intended skill. Add 1–2 probes (plus a control that must NOT route to the new skill) with every new skill. In this repo, the probe method and fixtures live in docs/ (see the routing-probes sections of docs/skill-library-ops.md; scripts/check_vercel_routing_probes.py verifies the recorded probe packet). This is the docs' "build evaluations first" applied to discovery.
4. Naming: noun phrases by task shape, never by industry (house divergence from the official gerund suggestion above — both are sanctioned; consistency within the corpus is what matters). "hardware-product-design", not "designing-hardware" or "fintech-skills".
5. Body budget: <5k tokens (Agent Skills spec recommendation), 500-line hard max. On compaction only the first 5,000 tokens of an invoked skill are re-attached (25k shared across skills) — front-load the load-bearing rules; push long quotes, walkthroughs, and per-source detail to references/. Reference files >100 lines get a ## Contents block (partial reads see full scope).
6. Knowledge-skill anatomy (talk/article-derived skills): Sources block with titles+speakers → task-shape framing sentence → principle sections with verified, cited quotes (short by default; larger chunks are fine when the passage itself is the load-bearing artifact — always attribute: speaker, work, video ID/URL) → Checklist → "Relationship to other skills" (bidirectional) → staleness note separating durable doctrine from fast-decaying specifics.
7. Gotchas are the highest-signal content (Anthropic's internal finding). Populate from observed failures, not anticipation — the corpus analog is the verified-quote + failure-driven-rule discipline (e.g. source-sweep was born from a real sampling failure).

Checklist Before Shipping

Core quality:

• Description says what AND when
• SKILL.md body under 500 lines
• Examples are concrete, not abstract
• File references one level deep
• Consistent terminology

Code and scripts:

• Scripts solve problems (not punt to Claude)
• Error handling is explicit
• Required packages listed
• Forward slashes only (no Windows paths)

Testing:

• Tested with Haiku, Sonnet, and Opus
• Tested with real usage scenarios

Details: references/authoring-checklist.md