Creating Skills

Build your own custom skills for Claude Code Setup.

Skill Types

Using /skill-creator

The easiest way to create a skill:

/skill-creator

The skill walks you through an 8-step flow: use cases, skill type, name + description, problem-first/tool-first framing, pattern selection, folder structure, content drafting, and testing. See the Skill Creator feature page for the full outline.

Progressive Disclosure

Skills use a three-level loading system. Understanding this keeps SKILL.md small and performant:

Move depth into references/ rather than bloating SKILL.md. Each references/NN-*.md file is self-contained.

Manual Creation

Directory Structure

~/.claude/custom/skills/
└── my-skill/
    └── SKILL.md

SKILL.md Format

---
name: my-skill
description: What this skill does
type: context
applies_to: [python, fastapi]
file_extensions: [".py"]
---
 
# Skill Content
 
Instructions and standards here...

Context Skill Example

---
name: api-standards
description: REST API design standards
type: context
applies_to: [python, typescript, nodejs, fastapi, express]
file_extensions: [".py", ".ts"]
---
 
# API Design Standards
 
## Endpoints
 
- Use nouns, not verbs: `/users` not `/getUsers`
- Use plural nouns: `/users` not `/user`
- Nest resources: `/users/{id}/orders`
 
## HTTP Methods
 
| Method | Purpose | Response |
|--------|---------|----------|
| GET | Read | 200 + data |
| POST | Create | 201 + created resource |
| PUT | Replace | 200 + updated resource |
| PATCH | Update | 200 + updated resource |
| DELETE | Delete | 204 no content |
 
## Error Responses
 
\`\`\`json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable message",
    "details": [...]
  }
}
\`\`\`

Command Skill Example

---
name: create-api-spec
description: Create OpenAPI specification
type: command
---
 
# Create API Spec
 
When invoked, create an OpenAPI 3.0 specification:
 
1. Analyze existing routes in the codebase
2. Generate openapi.yaml with:
   - Info section with project details
   - All endpoints with parameters
   - Request/response schemas
   - Error responses
3. Save to docs/openapi.yaml

Frontmatter Fields

Security rules

• No XML angle brackets (< or >) anywhere in frontmatter — security restriction to prevent prompt injection.
• No claude- or anthropic- prefix in the name field — reserved by Anthropic.
• No README.md inside the skill folder — Anthropic skill convention.

Writing the description

The description decides whether your skill ever triggers. Structure it as:

[What it does] + [When to use it, with trigger phrases] + (optional) [Key capabilities]

Include concrete phrases a user might actually say — not implementation details. Example:

description: End-to-end customer onboarding for PayFlow. Handles account creation, payment setup, and subscription activation. Use when the user says "onboard new customer", "set up subscription", or "create PayFlow account".

Optional Files

Beyond SKILL.md, skills can include additional files:

my-skill/
├── SKILL.md              # Required — skill definition
├── deps.json             # System dependencies to install
├── references/           # Reference docs Claude can read
├── assets/               # Templates, reusable content
├── scripts/              # Executable code (Python, Bash, Node)
└── test-project/         # Example project for testing

Rule of thumb: if Claude reads and applies the content, it’s a reference. If Claude copies and modifies the content, it’s an asset. If the task needs determinism (validation, parsing, math), write a script and call it from SKILL.md.

deps.json

Declares system dependencies that the installer handles per platform:

{
  "dependencies": [
    {
      "name": "yt-dlp",
      "install": {
        "macos": "brew install yt-dlp",
        "debian": "apt-get install -y yt-dlp",
        "arch": "pacman -S --noconfirm yt-dlp"
      }
    }
  ]
}

references/

Markdown files that Claude reads alongside the SKILL.md. Useful for code review checklists, pattern libraries, or API references that would make the main SKILL.md too long.

assets/

Skeletons the user or skill copies and modifies — templates, worked examples, schemas. For example, create-slidev-presentation includes deck templates (starter, conference, workshop, lightning) here.

scripts/

Executable code for deterministic steps. Use when language interpretation is unreliable: validation, parsing, file manipulation, computing metrics. Scripts are deterministic; prose instructions are probabilistic. Call them from SKILL.md:

Before processing, validate the input:
 
\`\`\`bash
python scripts/validate.py {filename}
\`\`\`
 
Do not proceed if the script exits non-zero.

test-project/

A working example project. standards-gradle includes a full Gradle project that demonstrates the conventions from the skill.

Common Patterns

Most skills fit one of five patterns — identify which before writing instructions. Full structures in the Skill Creator patterns reference:

Overriding Built-in Skills

Put your skill in ~/.claude/custom/skills/ with the same name:

Built-in: ~/.claude/skills/standards-python/
Custom:   ~/.claude/custom/skills/standards-python/

→ Custom wins

Related

• Skill Creator — interactive /skill-creator walkthrough with full references
• Customizing — custom commands, scripts, MCP servers
• Auto-Loading Skills — how context skills load