Building Agent Skills: A Practical Guide

•4 min read
aianthropicagent-skillsclaudemcp

Building Agent Skills: A Practical Guide

Agent Skills are organized folders of instructions, scripts, and resources that Claude discovers and loads dynamically. Instead of building custom agents for each use case, create reusable skill packages that extend Claude's capabilities with domain-specific expertise.

Skill Structure

Every skill requires a SKILL.md file with YAML frontmatter:

markdown
---
name: PDF Form Filler
description: Extract and fill PDF form fields using Python
---
 
# PDF Form Filling
 
Use the bundled `extract_fields.py` script to identify form fields without loading the entire PDF into context.
 
## Usage
 
1. Run `python extract_fields.py <pdf_path>` to get field names
2. Use the returned field data to fill forms programmatically
 
See `forms.md` for common field patterns.

The progressive disclosure architecture loads this in three levels: metadata (name/description) → core instructions (SKILL.md) → supplementary resources (forms.md). This means Claude only consumes context when necessary, making the system scale even with unlimited bundled content.

When to Build a Skill

Create a skill when:

  • You repeatedly give Claude the same instructions across sessions (convert that knowledge into a skill)
  • A workflow requires domain expertise not in Claude's training data (medical protocols, company processes)
  • You need deterministic operations that code executes faster than token generation (PDF parsing, data transformation)
  • Your team needs shared workflows and conventions (project-specific practices, testing procedures)
  • You're building reusable utilities across multiple projects (deployment scripts, code review checklists)

Skip creating a skill if:

  • It's a one-off task (just use a regular prompt)
  • The instructions are already in Claude's training (standard programming patterns)
  • You're experimenting and the workflow isn't stable yet (iterate first, then capture as a skill)

Code Execution

Skills can include executable scripts for deterministic operations:

python
# extract_fields.py
import PyPDF2
import sys
 
def extract_form_fields(pdf_path):
    with open(pdf_path, 'rb') as file:
        reader = PyPDF2.PdfReader(file)
        fields = reader.get_fields()
        return {name: field.get('/V', '') for name, field in fields.items()}
 
if __name__ == "__main__":
    print(extract_form_fields(sys.argv[1]))

Code execution is more efficient than token generation—sorting algorithms run faster than generating sorted sequences. For more on tokens, see What is a Token?.

Organizing Skills

Personal Skills

Personal Skills are available across all your projects. Store them in ~/.claude/skills/:

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

Use personal Skills for:

  • Individual workflows and preferences
  • Experimental skills you're developing
  • Personal productivity tools

Project Skills

Project Skills are shared with your team. Store them in .claude/skills/ within your project:

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

Use project Skills for:

  • Team workflows and conventions
  • Project-specific expertise
  • Shared utilities and scripts

Project Skills are checked into git and automatically available to team members.

Development Workflow with Symlinks

For project skills you want version controlled, create them in a visible directory and symlink to .claude/skills/:

bash
# 1. Create skill in version-controlled directory
mkdir -p skills/my-skill-name
 
# 2. Create skill files
# skills/my-skill-name/SKILL.md
# skills/my-skill-name/script.py
 
# 3. Symlink to where Claude expects it
mkdir -p .claude/skills
ln -s ../../skills/my-skill-name .claude/skills/my-skill-name
 
# 4. Add to git (ignore .claude directory)
echo ".claude/" >> .gitignore
git add skills/
git commit -m "Add my-skill-name"

This approach:

  • ✅ Makes skills visible (ls skills/ works)
  • ✅ Version controls the actual skill code
  • ✅ Lets Claude find skills in .claude/skills/
  • ✅ Keeps team synced via git

Getting Started

  1. Clone the official skills repository to see examples
  2. Create a directory with SKILL.md and any bundled resources
  3. Load the skill into Claude.ai, Claude Code, or via the Claude Agent SDK

Agent Skills work across all major Anthropic platforms: Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform.

Security note: Only install skills from trusted sources. Malicious skills can introduce vulnerabilities, exfiltrate data, or trigger unintended actions. Audit bundled code, dependencies, and network instructions before deployment.

References