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:

What it does — Concrete capabilities
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

Create Skill in .claude/skills/

Commit to git:

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

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.

Skills Guide

Skills Guide

Contents

Quick Start

Personal Skill (available everywhere)