Claude Code Agent Skills

Agent Skills are modular knowledge packages in Claude Code that activate automatically when your task matches their description. Unlike slash commands (explicit invocation) or subagents (isolated workers), skills add expertise to your current conversation without switching contexts.

How Skills Work

Progressive disclosure architecture:

1. At startup, Claude pre-loads only name + description of every installed skill
2. When your request matches a skill’s description, Claude asks permission to load it
3. Full SKILL.md content loads into context only after approval
4. Supporting files (scripts, references) load on-demand as needed

This keeps token costs low until expertise is actually needed.

SKILL.md Structure

The only required file. Two parts: YAML frontmatter + markdown instructions.

---
name: code-reviewer
description: Expert code review focusing on security, performance, and maintainability. Use when reviewing pull requests or examining code quality.
---
 
# Code Review Guidelines
 
## Process
1. Check for security vulnerabilities
2. Evaluate performance implications
3. Assess code readability and maintainability
 
## Reference
See @references/security-checklist.md for OWASP patterns.
 
## Scripts
Run @scripts/lint-check.sh for automated analysis.

Required Fields

Field	Constraints	Purpose
name	Lowercase, hyphens, max 64 chars	Unique identifier
description	Max 1024 chars	Triggers skill activation

Optional Fields

Field	Purpose
allowed-tools	Restrict available tools (security control)
version	Track skill versions
disable-model-invocation	Require manual /skill-name invocation
mode	Mark as behavior modifier (shows in “Mode Commands” section)

Tool Restrictions

---
name: safe-reader
description: Read-only file exploration. Use for audits and reviews.
allowed-tools:
  - Read
  - Grep
  - Glob
---

When active, Claude can only use specified tools without permission prompts.

Directory Structure

Skills can bundle supporting resources:

my-skill/
├── SKILL.md           # Core instructions (required)
├── scripts/           # Executable Python/Bash (zero-context execution)
├── references/        # Supplemental docs (loaded on-demand)
└── assets/            # Templates, binary files

scripts/: Run via Bash without loading into context. Only output consumes tokens.

references/: Link from SKILL.md. Keep one level deep (no nested references).

Best practice: Keep SKILL.md under 5,000 words. Split complex content to sub-files.

Where Skills Live

Location	Scope	Use Case
~/.claude/skills/	All projects	General-purpose (code review, docs)
.claude/skills/	Single project	Team conventions, project workflows
Plugin marketplaces	Installable	Shared across organizations
MCP servers	Remote	Dynamic, API-backed skills

Skills vs Commands vs Subagents

Aspect	Skills	Slash Commands	Subagents
Invocation	Auto (description match)	Manual (/command)	Task delegation
Context	Same conversation	Same or forked	Isolated window
Use case	Expertise injection	Repeatable workflows	Parallel work, isolation
Files	Directory + SKILL.md	Single .md file	Single .md file

Mental model:

• Skills = knowledge Claude applies
• Commands = actions you trigger
• Subagents = workers you delegate to

Slash commands can orchestrate subagents. Subagents can invoke skills. Skills teach Claude how to use tools that MCP provides.

Improving Activation Reliability

Skills activate via LLM reasoning, not algorithmic matching. Two proven approaches for reliable activation (80%+ success vs 50% baseline):

Strong trigger descriptions:

• Include concrete use cases, file types, technical terms
• Write in third person: “Use when reviewing TypeScript files”
• Be specific: “analyzing React component performance” beats “code review”

Prompt injection via hooks:

• Hooks can inject reminders on every prompt
• Forces Claude to evaluate skill relevance continuously
• Higher activation than relying on semantic matching alone

Creating Skills

Interactive: Claude can generate skills from natural language descriptions

Manual:

mkdir -p .claude/skills/my-skill
echo '---
name: my-skill
description: What it does and when to use it
---
 
Instructions here...' > .claude/skills/my-skill/SKILL.md

From templates: Copy from anthropics/skills (44k+ stars)

Example Skills

Brand Guidelines

---
name: brand-writer
description: Apply company voice and style guidelines to content. Use for external communications, documentation, and marketing materials.
---
 
# Brand Voice
 
## Tone
Direct, warm, technically precise. Never corporate speak.
 
## Banned phrases
- "leverage", "synergy", "paradigm shift"
- "at the end of the day"
- "game-changer", "best practices"
 
## Reference
See @references/style-guide.md for complete guidelines.

Test Runner

---
name: test-runner
description: Run and analyze test suites. Use after code changes or when investigating test failures.
allowed-tools:
  - Bash
  - Read
  - Grep
---
 
# Test Workflow
 
1. Detect framework (Jest, pytest, etc.)
2. Run relevant tests
3. If failures, analyze stack traces
4. Suggest fixes with root cause
 
## Scripts
@scripts/detect-framework.sh
@scripts/run-tests.sh

Cost Considerations

Every installed skill adds name + description to every request. 20 skills might add 1,000+ tokens before you ask anything.

Mitigations:

• Delete unused skills
• Use project-level skills over user-level when possible
• Consider disable-model-invocation: true for rarely-used skills

Related

• Claude Code
• Commands for explicit invocation
• Subagents for isolated work
• Hooks for lifecycle automation
• MCP for external tools

Sources

• Agent Skills - Claude Code Docs
• Agent Skills - Platform Docs
• Equipping Agents for the Real World
• Skills Explained - Claude Blog
• GitHub: anthropics/skills
• Awesome Claude Skills
• Claude Skills Deep Dive
• Skills Activation Reliability
• Claude Code Customization Guide