skills-guide

Skills Guide

Package reusable expertise into discoverable capabilities. Skills are modular instructions Claude autonomously activates when relevant—extending your workflow without requiring slash commands.

Contents

• Quick Start
• What are Skills
• Create a Skill
• Structure & Organization
• Best Practices
• Debugging

Quick Start

Personal Skill (available everywhere)

mkdir -p ~/.claude/skills/my-skill-name

Project Skill (shared with team)

mkdir -p .claude/skills/my-skill-name

Create SKILL.md

---
name: Skill Name
description: What it does + when to use it (be specific!)
---

# Skill Name

## Instructions
Step-by-step guidance for Claude

## Examples
Concrete usage examples

What are Skills

Agent Skills package expertise into discoverable, composable capabilities:

• SKILL.md — Instructions Claude reads when relevant
• Supporting files — Optional scripts, templates, reference docs
• Model-invoked — Claude autonomously decides when to use based on description
• Discoverable — No slash commands; integrated with your workflow

Benefits

• Solve recurring problems once, reuse everywhere
• Share expertise across teams via git
• Compose multiple Skills for complex tasks
• Reduce token overhead from repetitive prompting

Create a Skill

Personal Skills: ~/.claude/skills/

Available across all projects. Use for:

• Individual workflows and experimental Skills
• Personal productivity tools
• Utilities you use across multiple projects

Project Skills: .claude/skills/

Shared with your team via git. Use for:

• Team workflows and shared expertise
• Project-specific capabilities
• Utilities team members need together

Team members automatically get Project Skills when they pull your repo.

Plugin Skills

Bundled with Claude Code plugins; automatically available when plugin installed.

Write SKILL.md

Every Skill requires YAML frontmatter + Markdown content.

Required Fields

Field	Limit	Purpose
name	64 chars	Human-readable name
description	1024 chars	What it does + when to use

Optional Fields

Field	Purpose
allowed-tools	Restrict which tools Claude can use (e.g., Read, Grep, Glob)

The description field is critical

Claude uses this to decide whether to activate your Skill. Always include:

1. What it does — Concrete capabilities
2. When to use — Specific triggers and contexts

Good (triggers Claude):

Extract text and tables from PDF files, fill forms, merge documents.
Use when working with PDF files or when the user mentions PDFs, forms, or extraction.

Bad (too vague):

Helps with documents

Naming conventions

Use gerund form (verb + -ing):

• "Processing PDFs"
• "Analyzing spreadsheets"
• "Testing code"
• "Writing documentation"

Structure & Organization

Simple Skill (single file)

For focused, single-purpose capabilities:

commit-helper/
└── SKILL.md

Skill with supporting files

Reference files load on-demand; keep SKILL.md under 500 lines for optimal performance:

pdf-processing/
├── SKILL.md              # Main instructions (quick start)
├── FORMS.md              # Form-filling guide
├── REFERENCE.md          # API reference
├── EXAMPLES.md           # Usage examples
└── scripts/
    ├── analyze_form.py
    ├── fill_form.py
    └── validate.py

Progressive disclosure pattern

High-level overview in SKILL.md:

• Quick start and common use cases
• Links to detailed reference files

## Quick start

Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Advanced features

Form filling: See FORMS.md API reference: See REFERENCE.md Examples: See EXAMPLES.md

### Organization for multi-domain Skills

For Skills covering multiple domains, organize by domain:

bigquery-skill/ ├── SKILL.md └── reference/ ├── finance.md ├── sales.md ├── product.md └── marketing.md

SKILL.md acts as router linking to domain-specific docs.

## Best Practices

### 1. Assume Claude is smart

Don't explain basic concepts. Be concise and direct.

**Verbose** (~150 tokens):

PDF files are a common format containing text, images, and other content. To extract text, you need a library. Many libraries exist...

**Concise** (~50 tokens):

Use pdfplumber for text extraction:

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

### 2. Use examples over explanations

Provide input/output pairs, especially for transformations:

```markdown
## Commit message format

**Example 1:**
Input: Added user authentication with JWT tokens
Output:

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

**Example 2:**
Input: Fixed bug where dates displayed incorrectly
Output:

fix(reports): correct date formatting in timezone conversion

3. Provide utility scripts

Pre-made scripts are more reliable than generated code:

## Utility scripts

**analyze_form.py**: Extract form fields from PDF
```bash
python scripts/analyze_form.py input.pdf > fields.json

validate_boxes.py: Check for overlapping fields

python scripts/validate_boxes.py fields.json

### 4. List required packages

Specify dependencies upfront:

```markdown
## Requirements

```bash
pip install pypdf pdfplumber

### 5. Implement validation loops

For quality-critical tasks, enforce validation checks:

```markdown
## Workflow

1. Make your edits
2. **Validate immediately**: `python scripts/validate.py`
3. If validation fails:
   - Review error message
   - Fix issues
   - Run validation again
4. **Only proceed when validation passes**

6. Use workflows with checklists

For complex multi-step operations:

## Task Progress

- [ ] Step 1: Analyze form
- [ ] Step 2: Create mapping
- [ ] Step 3: Validate mapping
- [ ] Step 4: Fill form
- [ ] Step 5: Verify output

7. Restrict tool access (optional)

Limit which tools Claude can use:

---
name: Safe File Reader
description: Read files without making changes
allowed-tools: Read, Grep, Glob
---

8. Match specificity to task fragility

High freedom (multiple approaches valid):

## Code review process

1. Analyze code structure
2. Check for potential bugs
3. Suggest readability improvements
4. Verify project conventions

Low freedom (exact sequence required):

## Database migration

Run exactly this command (do not modify):
```bash
python scripts/migrate.py --verify --backup

## Debugging

### Skill won't activate?

**Check description specificity**:
- Too vague: `Helps with documents`
- Specific: `Extract text and tables from PDFs. Use when working with PDF files or when the user mentions PDFs, forms, or extraction.`

**Include when-to-use triggers** in description so Claude recognizes your task.

### Multiple Skills conflict?

Use distinct trigger terms:

Instead of:
```yaml
# Skill 1
description: For data analysis

# Skill 2
description: For analyzing data

Use:

# Skill 1
description: Analyze sales data in Excel and CRM exports.
Use for sales reports, pipeline analysis, and revenue tracking.

# Skill 2
description: Analyze log files and system metrics.
Use for performance monitoring, debugging, and system diagnostics.

Check file paths

Verify Skill location:

# Personal
ls ~/.claude/skills/my-skill/SKILL.md

# Project
ls .claude/skills/my-skill/SKILL.md

Verify YAML syntax

Invalid YAML prevents loading:

cat SKILL.md | head -n 10

Ensure:

• Opening --- on line 1
• Closing --- before content
• Valid YAML (no tabs, correct indentation)

Use forward slashes only

• ✓ Good: scripts/helper.py
• ✗ Wrong: scripts\helper.py

Share Skills

With your team via git

1. Create Skill in .claude/skills/
2. Commit to git:

   git add .claude/skills/
   git commit -m "Add team Skill for PDF processing"
   git push
   

3. Team pulls and Skills are immediately available

Test your Skill

Ask Claude questions matching your description:

Can you help me extract text from this PDF?

Claude autonomously activates your Skill if description matches the request.