Create a Skill

Skill Anatomy

Every skill is a folder with at least one file — SKILL.md:

my-skill/
├── SKILL.md          # Required: YAML frontmatter + markdown instructions
├── scripts/          # Optional: executable scripts
├── references/       # Optional: reference documents
└── assets/           # Optional: templates, configs, binary resources

SKILL.md Format

---
name: my-skill
description: >-
  One-line description. Use when [trigger condition].
  Do NOT use when [anti-trigger].
license: MIT                    # optional
allowed-tools: Read, Grep, Glob # optional: restrict tool access
metadata:                       # optional
  author: your-name
  version: "1.0.0"
  domain: frontend
---

# My Skill

Detailed instructions for the AI agent...

Writing a Good Description

The description field is the routing rule — it determines when the agent loads your skill. Be specific:

Good

description: >-
  Use when reviewing pull requests, conducting code quality audits,
  or identifying security vulnerabilities. Invoke for PR reviews,
  code quality checks, refactoring suggestions.

Bad

description: A helpful skill for code stuff.

Best Practices

1. One skill, one responsibility

Don't create a "do everything" skill. Split broad capabilities into focused skills.

2. Keep SKILL.md concise

Aim for under 500 lines / 5000 tokens. Put detailed reference material in references/ subfolder.

3. Progressive disclosure

The agent reads content in order:

1. Frontmatter — decides whether to load the skill
2. SKILL.md body — core instructions
3. Referenced files — only when needed

Structure your SKILL.md so the most important instructions come first.

4. Start with instructions, add scripts later

Begin with a pure-instruction skill. Once it's stable and you find yourself repeating actions, extract them into scripts.

5. Test before sharing

Run the skill in a real Claude Code session. Check that:

• It triggers on the right prompts
• It does NOT trigger on unrelated prompts
• The instructions produce correct behavior

Add to This Vault

1. Create a new folder under skills/:

mkdir skills/my-new-skill

2. Write your SKILL.md

3. Link it to Claude Code:

ln -s "$(pwd)/skills/my-new-skill" "$HOME/.claude/skills/my-new-skill"

4. Add a documentation page under docs/skills/my-new-skill.md

5. Update docs/.vitepress/config.mjs sidebar entry