Skills

Skill structure

A skill is a folder in .claude/skills/ containing a SKILL.md file and optionally additional resources (docs, templates, scripts, checklists).

my-skill/
├── SKILL.md              # Instructions + frontmatter (required)
├── reference.md          # Reference documentation
├── checklists/
│   └── quality.md
└── examples/
    └── pattern.ts

SKILL.md frontmatter

---
name: security-guardian
description: OWASP expertise, auth, and data protection
allowed-tools: Read Grep Bash
---

Skills vs Commands

The main difference: a skill can embed a 500-line reference.md file that becomes available on invocation. A command cannot.

Marketplace: npx add-skill

# Install the Vercel bundle (3 skills)
npx add-skill vercel-labs/agent-skills

# Install the Supabase skill
npx add-skill supabase/agent-skills

# Check installed skills
ls ~/.claude/skills/

Marketplace skills pass an automatic 3-layer security audit (Socket, Snyk, Gen) before publication. Over 200 skills available.

Invocation

Skills are triggered like commands, by their name:

/security-guardian          # Direct invocation
/tdd                        # TDD skill
/design-patterns detect     # With argument

Agents can preload skills via the skills: field in their frontmatter — the content is injected into the agent’s context at startup.

Lifecycle and improvement

Two long-term management patterns:

Claudeception — meta-skill that generates new skills from session discoveries. Install: git clone https://github.com/blader/Claudeception ~/.claude/skills/claudeception

Claude Reflect System — improves existing skills by analyzing corrections detected during sessions. Proposes changes before applying them.

Important caveat

Skills are only invoked on explicit activation — evals show automatic invocation in only 56% of cases. For critical instructions that must always apply, use CLAUDE.md or .claude/rules/ rather than a skill.