Skill Building Guide

Official reference for building Claude skills, distilled from Anthropic's Complete Guide to Building Skills for Claude.

Critical Rules (Never Violate)

Naming

• •SKILL.md must be exactly SKILL.md (case-sensitive). No variations (SKILL.MD, skill.md)
• •Skill folder: kebab-case only. No spaces, underscores, or capitals
  • •Good: notion-project-setup
  • •Bad: Notion Project Setup, notion_project_setup, NotionProjectSetup
• •No README.md inside skill folder. All docs go in SKILL.md or references/
• •Skills named with "claude" or "anthropic" prefix are reserved

YAML Frontmatter

• •Must use --- delimiters (three dashes, nothing else on the line)
• •No XML angle brackets in frontmatter - security restriction
• •name field: kebab-case, no spaces/capitals, should match folder name
• •description field: under 1024 characters, must include WHAT and WHEN

Frontmatter Format

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

Optional fields: license, compatibility (1-500 chars), metadata (author, version, mcp-server, etc.), allowed-tools

The Description Field (Most Important Part)

The description is how Claude decides whether to load your skill. Get this right.

Formula: [What it does] + [When to use it] + [Key capabilities]

Good descriptions include:

• •Specific trigger phrases users would actually say
• •File types if relevant
• •Clear scope boundaries
• •Negative triggers when needed ("Do NOT use for X")

Good example:

description: Analyzes Figma design files and generates developer handoff
documentation. Use when user uploads .fig files, asks for "design specs",
"component documentation", or "design-to-code handoff".

Bad examples (avoid):

• •Too vague: description: Helps with projects.
• •Missing triggers: description: Creates sophisticated multi-page documentation systems.
• •Too technical: description: Implements the Project entity model with hierarchical relationships.

Progressive Disclosure (Three-Level System)

1. •Level 1 - Frontmatter: Always loaded into system prompt. Just enough for Claude to know WHEN to use the skill. Keep minimal.
2. •Level 2 - SKILL.md body: Loaded when Claude thinks the skill is relevant. Core instructions and guidance.
3. •Level 3 - Linked files: references/, scripts/, assets/. Claude discovers and loads as needed.

Keep SKILL.md under 5,000 words. Move detailed docs to references/.

Writing Instructions

• •Be specific and actionable: Run python scripts/validate.py --input {filename} not Validate the data
• •Put critical instructions at the top, use ## Important or ## Critical headers
• •Use bullet points and numbered lists, not prose paragraphs
• •Include error handling with specific remediation steps
• •Reference bundled resources clearly: consult references/api-patterns.md for rate limiting guidance

Skill Use Case Categories

Quality Gates

Before finalizing any skill, verify against these gates:

1. •Frontmatter valid? Consult references/technical-requirements.md
2. •Description effective? Consult references/writing-effective-skills.md
3. •Right pattern chosen? Consult references/patterns.md
4. •Tested properly? Consult references/testing-checklist.md
5. •Common issues addressed? Consult references/troubleshooting.md
6. •Ready to share? Consult references/distribution.md

Problem-First vs. Tool-First

• •Problem-first: "I need to set up a project workspace" - Skill orchestrates MCP calls in right sequence. Users describe outcomes.
• •Tool-first: "I have Notion MCP connected" - Skill teaches Claude optimal workflows. Users have tool access; skill provides expertise.

Most skills lean one direction. Knowing which framing fits your use case helps choose the right pattern from references/patterns.md.