Skill Best Practices

Skill Best Practices

Reference: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf

Instructions

Step 1: Identify your use case category

Determine which type of skill you're building:

• Document & Asset Creation — consistent output (docs, designs, code)
• Workflow Automation — multi-step processes with consistent methodology
• MCP Enhancement — workflow guidance on top of MCP tool access

Define 2–3 concrete use cases before writing anything (see Planning section below).

Step 2: Create the folder and SKILL.md

• Name the folder in kebab-case (e.g. my-skill-name)
• Create exactly SKILL.md (case-sensitive) inside it
• Write YAML frontmatter with name and description (see Technical requirements)

Step 3: Write the description — this is the most critical part

The description controls when Claude loads your skill. It must include:

• WHAT the skill does
• WHEN to use it (specific trigger phrases)
• Optional: negative triggers ("Do NOT use for...")

See "Writing effective descriptions" for good/bad examples.

Step 4: Write the body instructions

Follow the recommended template: ## Instructions → numbered steps → ## Examples → ## Troubleshooting. Be specific and actionable. Move detailed docs to references/ and link to them.

Step 5: Update CLAUDE.md and README.md

After creating or modifying any skill in this repository, always update the skill tables in both files:

• CLAUDE.md — skill table under "Included Skills" (Trigger column: one-line description of when it fires)
• README.md — skill table under "Enthaltene Skills" (Beschreibung column: German one-liner)

Both files must stay in sync. This step is mandatory and must not be skipped.

Also invoke the cc-best-practices skill when working on skills in this repository to ensure context and session management follow project standards.

Step 6: Validate YAML and skills CLI compatibility

Run the validation script from the repository root before testing or committing:

bash .claude/skills/skill-best-practices/scripts/validate-skills.sh

Fix any FAIL lines before continuing. Common issues:

• description uses block scalar (> or |) → replace with a quoted single-line string
• Sub-keys under a parent mapping key not indented → add two-space indent

After pushing, also run the remote check to confirm npx skills add --list finds all skills:

bash .claude/skills/skill-best-practices/scripts/validate-skills.sh --remote

Step 7: Test triggering and functional behavior

Run 10–20 test queries. Target: skill triggers on ~90% of relevant queries and never on unrelated topics. Iterate on the description until triggering is reliable (see Testing approach).

Step 7: Iterate based on signals

• Undertriggering → add more trigger phrases to description
• Overtriggering → add negative triggers, narrow scope
• Instructions ignored → move critical steps to top, use explicit language

Examples

Example 1: Building a new skill from scratch

User says: "Help me create a skill that plans sprints in Linear"

Actions:

1. Identify category: Workflow Automation + MCP Enhancement
2. Define use case: trigger = "plan sprint", "create sprint tasks"; steps = fetch Linear status → analyze velocity → create tasks
3. Create folder linear-sprint-planner/SKILL.md
4. Write description: "Manages Linear sprint planning workflows. Use when user says 'plan sprint', 'create sprint tasks', or 'set up iteration'."
5. Write step-by-step instructions with Linear MCP tool calls
6. Test with 10 trigger phrases; adjust description if skill doesn't auto-load

Result: Functional skill that auto-triggers on sprint planning requests and executes the full workflow without user re-explaining the steps each time.

Example 2: Reviewing an existing skill

User says: "Review my SKILL.md and suggest improvements"

Actions:

1. Read the SKILL.md frontmatter — check name (kebab-case?), description (WHAT + WHEN? under 1024 chars? trigger phrases present?)
2. Check body — is it under 5,000 words? Are instructions specific and actionable? Is there a Troubleshooting section? Examples?
3. Simulate triggering — would the description cause Claude to load this skill for the right queries?
4. Report findings as: PASS / WARN / FAIL per criterion

Result: Prioritized list of improvements with specific fixes for each issue.

Example 3: Troubleshooting a skill that doesn't trigger

User says: "My skill never loads automatically, I always have to invoke it manually"

Actions:

1. Read the description field — is it too generic? ("Helps with projects" won't work)
2. Check for missing trigger phrases — does it include words users would actually say?
3. Ask Claude: "When would you use the [skill name] skill?" — Claude quotes the description back; gaps become obvious
4. Rewrite description to add specific trigger phrases and retest

Result: Updated description with concrete triggers; skill auto-loads on relevant queries.

What is a skill?

A skill is a folder containing:

• SKILL.md (required): Instructions in Markdown with YAML frontmatter
• scripts/ (optional): Executable code (Python, Bash, etc.)
• references/ (optional): Documentation loaded as needed
• assets/ (optional): Templates, fonts, icons used in output

Core design principles

Progressive Disclosure — three levels:

1. YAML frontmatter: always in system prompt; tells Claude _when_ to load the skill
2. SKILL.md body: loaded when relevant; full instructions
3. Linked files in references/: loaded on demand

Composability — skills work alongside others; don't assume exclusivity.

Portability — works identically across Claude.ai, Claude Code, and API.

Planning: Start with use cases

Before writing, define 2–3 concrete use cases:

Use Case: <name>
Trigger: User says "<phrase>" or "<phrase>"
Steps:
  1. ...
  2. ...
Result: <expected outcome>

Ask yourself:

• What does the user want to accomplish?
• What multi-step workflow is required?
• Which tools are needed (built-in or MCP)?
• What domain knowledge should be embedded?

Three skill categories

Technical requirements

File & folder naming

• Folder: kebab-case only (notion-project-setup) — no spaces, underscores, or capitals
• File: exactly `SKILL.md` (case-sensitive) — no variations
• No README.md inside the skill folder (put docs in SKILL.md or references/)

YAML frontmatter

Minimal required format:

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

`name` (required):

• kebab-case, no spaces or capitals
• Must match folder name

`description` (required):

• MUST include BOTH: what the skill does AND when to use it (trigger conditions)
• Under 1024 characters
• No XML tags (< or >)
• Include specific trigger phrases users would actually say
• Mention file types if relevant

Optional fields:

license: MIT
compatibility: "Requires Python 3.10+"
metadata:
  author: Your Name
  version: 1.0.0
  mcp-server: server-name

Security restrictions — forbidden in frontmatter:

• XML angle brackets (< >)