Claude Agent Skills Framework: Build Specialized AI Agents

What Are Agent Skills?

Agent Skills represent a paradigm shift in how we extend AI capabilities. Rather than hardcoding functionality or manually selecting tools, Skills are organized folders of instructions, scripts, and resources that agents discover and load dynamically to perform specialized tasks.

Think of Skills as expertise modules. When you need to work with PDFs, generate API documentation, or analyze database schemas, Claude doesn't need every detail about these tasks loaded into memory from the start. Instead, it scans available Skills, finds relevant ones based on brief descriptions, and loads complete instructions only when needed.

Why Skills Matter for Development

Traditional AI coding assistants provide general capabilities but struggle with domain-specific workflows. Skills solve this by:

• Packaging domain expertise into reusable, shareable modules
• Managing context efficiently through progressive disclosure
• Enabling team collaboration via git-tracked project skills
• Creating ecosystem extensions through plugin skills

Research from LangChain demonstrates that Claude combined with domain-specific CLAUDE.md instructions (a precursor to Skills) outperformed Claude with full Model Context Protocol (MCP) access, even though CLAUDE.md only included a subset of MCP capabilities. This validates the power of focused, well-structured expertise over broad but unfocused tool access.

SKILL.md File Structure

Every skill begins with a SKILL.md file—a simple combination of YAML frontmatter and Markdown content. Anthropic designed this format to be "simple to create" while powerful enough for complex workflows.

Required YAML Frontmatter

The frontmatter contains only two required fields:

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction.
---

Optional Frontmatter Fields

---
name: secure-api-tester
description: Test API endpoints with authentication, rate limiting, and security validation. Use for API testing and security audits.
allowed-tools: Read, Grep, Bash
---

Markdown Content

Below the frontmatter, write instructions in Markdown. This is what Claude reads when the skill activates:

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction.
---

# PDF Processing

## Quick Start
When a user provides a PDF file path, follow these steps:
1. Use `pdftotext` to extract text content
2. Parse the structure to identify forms, tables, or headings
3. Present extracted content in a structured format

## Form Filling
For PDF form operations:
- Use `pdftk` to fill form fields
- Validate field names before attempting fills
- Preserve original formatting and fonts

## Merging Documents
When merging multiple PDFs:
```bash
pdftk file1.pdf file2.pdf cat output merged.pdf
```

## Examples
- Extract: "Get text from /docs/report.pdf"
- Fill: "Fill the form at /forms/application.pdf with this data"
- Merge: "Combine these 3 PDFs into one document"

## Error Handling
- Check file exists before processing
- Validate PDF format
- Report specific errors (corrupted file, password-protected, etc.)

Directory Structure

Skills can include supporting files alongside SKILL.md:

pdf-processing/
├── SKILL.md              # Main skill definition
├── resources/
│   ├── field-mappings.json
│   └── template-forms/
│       ├── application.pdf
│       └── invoice.pdf
├── scripts/
│   ├── extract.sh
│   └── validate-pdf.py
└── templates/
    └── output-format.md

Reference these files in your SKILL.md instructions. Claude will read them only when needed, maintaining efficient context usage.

Progressive Disclosure Model

Progressive disclosure is the architectural foundation that makes Skills scalable. Instead of loading every skill's complete instructions into Claude's context at startup (which would quickly exhaust the context window), Skills use a three-tier loading strategy:

Why Progressive Disclosure Matters

Anthropic describes this as "like a well-organized manual"—you don't need to read every page to find what you need, just the table of contents and the relevant chapters. This design enables:

• Scalability: Install dozens of skills without context window pressure
• Performance: Only relevant expertise loads, improving response quality
• Flexibility: Add new skills without modifying existing ones
• Maintainability: Update individual skills without system-wide changes

Three Types of Skills

Claude Code organizes skills into three deployment scopes, each serving different collaboration and sharing needs:

Creating Your First Skill

Let's build a practical skill from scratch: a TypeScript Interface Generator that creates interfaces from JSON data.

Step 1: Setup

Create the skill directory in your preferred location:

# Personal skill
mkdir -p ~/.claude/skills/typescript-interface-generator

# Project skill
mkdir -p .claude/skills/typescript-interface-generator

Step 2: Create SKILL.md

---
name: typescript-interface-generator
description: Generate TypeScript interfaces from JSON data, API responses, or data structures. Use when converting JSON to TypeScript types, creating type definitions, or documenting API structures.
allowed-tools: Read, Write, Edit
---

# TypeScript Interface Generator

Generate clean, well-typed TypeScript interfaces from JSON data.

## When to Use
- Converting API responses to TypeScript types
- Creating type definitions from configuration files
- Documenting data structures with proper typing
- Generating interfaces for database schemas

## Instructions

### 1. Analyze Input
When given JSON data:
- Parse the structure to identify all keys and value types
- Detect arrays vs objects vs primitives
- Identify optional fields (present in some objects, missing in others)
- Note union types (fields with multiple possible types)

### 2. Generate Interface
Create a TypeScript interface with:
- PascalCase interface name (ask user if not specified)
- Proper type annotations:
  - `string` for string values
  - `number` for numeric values
  - `boolean` for booleans
  - `Type[]` for arrays
  - Nested interfaces for objects
  - `type | undefined` for optional fields
  - Union types where applicable

### 3. Handle Complex Types
For arrays of objects:
```typescript
interface Item {
  id: number;
  name: string;
}

interface Container {
  items: Item[];
}
```

For optional fields:
```typescript
interface User {
  name: string;
  email?: string;  // Optional
  age: number | undefined;  // May be undefined
}
```

### 4. Add Documentation
Include JSDoc comments for:
- Interface purpose
- Field descriptions (if context available)
- Expected value ranges or formats

## Examples

**Input JSON:**
```json
{
  "user": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com",
    "roles": ["admin", "user"]
  }
}
```

**Output:**
```typescript
/**
 * User data structure
 */
interface User {
  /** Unique user identifier */
  id: number;

  /** Full name */
  name: string;

  /** Email address */
  email: string;

  /** Assigned roles */
  roles: string[];
}

interface Response {
  user: User;
}
```

## Best Practices
- Use PascalCase for interface names
- Use camelCase for field names
- Add `export` keyword if interface will be imported
- Group related interfaces together
- Use `readonly` for immutable fields when appropriate
- Consider using `Partial<T>` or `Required<T>` utility types

## Error Handling
- If JSON is invalid, report parsing error
- If types are ambiguous, ask user for clarification
- If data is too complex, suggest breaking into multiple interfaces

Step 3: Test Your Skill

Restart Claude Code to load the new skill, then test with a natural request:

User: "Generate TypeScript interfaces for this API response:
{
  "data": {
    "posts": [
      {
        "id": 1,
        "title": "Hello World",
        "published": true,
        "author": {
          "name": "Alice",
          "verified": true
        }
      }
    ],
    "total": 1
  }
}"

Claude will automatically invoke the skill and generate properly typed interfaces with nested types and documentation.

Real-World Skill Examples

Let's explore production-ready skills from the Anthropic Skills repository and community contributors.

---
name: code-reviewer
description: Review code for best practices, potential issues, security vulnerabilities, and performance concerns. Use when reviewing PRs, checking code quality, or analyzing codebases.
allowed-tools: Read, Grep, Glob
---

# Code Review

## Review Areas
1. **Code Quality**: DRY, SOLID principles, naming conventions
2. **Security**: SQL injection, XSS, authentication issues
3. **Performance**: N+1 queries, memory leaks, inefficient algorithms
4. **Testing**: Coverage, edge cases, mocking appropriateness
5. **Documentation**: Comments, README updates, API docs

## Output Format
Provide findings as:
- ✅ Strengths
- ⚠️  Warnings (should fix)
- 🔴 Critical Issues (must fix)
- 💡 Suggestions (nice to have)

---
name: api-doc-generator
description: Generate OpenAPI 3.0 documentation from API routes, controllers, or endpoint files. Use when documenting REST APIs or creating Swagger specs.
allowed-tools: Read, Write, Grep, Glob
---

# API Documentation Generator

## Process
1. Scan route files to identify endpoints
2. Extract HTTP methods, paths, and parameters
3. Analyze request/response structures
4. Generate OpenAPI 3.0 specification
5. Include examples and schemas

## Output Includes
- Endpoint descriptions
- Request parameters (path, query, body)
- Response schemas with status codes
- Authentication requirements
- Example requests and responses

---
name: database-migration
description: Create and validate database migrations for schema changes. Use when adding/modifying tables, columns, indexes, or constraints in PostgreSQL, MySQL, or SQLite.
allowed-tools: Read, Write, Bash
---

# Database Migration Helper

## Safety Checks
Before creating migrations:
- Check for data loss risks (dropping columns, changing types)
- Verify index requirements for new columns
- Consider rollback procedures
- Test on development database first

## Migration Structure
1. **Up Migration**: Changes to apply
2. **Down Migration**: Rollback procedure
3. **Data Migration**: Handle existing data
4. **Index Creation**: Add after data migration

## Commands
Provide both ORM syntax and raw SQL for:
- Prisma
- TypeORM
- Sequelize
- Raw SQL with transaction handling

---
name: deployment-checklist
description: Generate deployment checklists and verify production readiness. Use before deploying to staging/production or when setting up CI/CD pipelines.
allowed-tools: Read, Grep, Bash
---

# Deployment Checklist

## Pre-Deployment Verification
- ✅ All tests passing
- ✅ Environment variables documented
- ✅ Database migrations reviewed
- ✅ Error tracking configured
- ✅ Logging implemented
- ✅ Security headers set
- ✅ Performance benchmarks met
- ✅ Rollback plan documented

## Platform-Specific Checks
### Vercel
- Build command configured
- Environment variables set
- Preview deployments tested

### AWS
- IAM roles configured
- Security groups reviewed
- Scaling policies set

Advanced Skill Patterns

Once you master basic skills, these advanced patterns enable sophisticated workflows and domain specialization.

1. Skills with Executable Scripts

Bundle shell scripts, Python helpers, or Node.js utilities that Claude can execute as tools:

performance-analyzer/
├── SKILL.md
└── scripts/
    ├── analyze-bundle.js
    ├── check-lighthouse.sh
    └── compare-metrics.py

# In SKILL.md:
---
name: performance-analyzer
description: Analyze web performance metrics, bundle sizes, and Core Web Vitals. Use when optimizing performance or debugging slow pages.
allowed-tools: Bash, Read
---

## Bundle Analysis
Run `./scripts/analyze-bundle.js` to:
- Calculate JavaScript bundle sizes
- Identify large dependencies
- Suggest code splitting opportunities

## Lighthouse Checks
Execute `./scripts/check-lighthouse.sh [url]` to:
- Run Lighthouse CI
- Compare metrics to thresholds
- Generate performance reports

2. Framework-Specific Skills

Create skills tailored to specific frameworks with deep domain knowledge:

---
name: nextjs-app-router
description: Build Next.js 15 applications using App Router, Server Components, and Server Actions. Use when creating Next.js apps or converting from Pages Router.
allowed-tools: Read, Write, Edit, Bash
---

# Next.js App Router Expert

## File Structure Conventions
- Use `app/` directory for routes
- Server Components by default
- Add "use client" only when needed
- Colocate components with routes

## Metadata API
Always use Metadata API for SEO:
```typescript
export const metadata: Metadata = {
  title: 'Page Title',
  description: 'Description',
  openGraph: { ... }
}
```

## Server Actions
For mutations, create Server Actions in separate files:
```typescript
// app/actions/update-user.ts
'use server'

export async function updateUser(formData: FormData) {
  // Server-side logic
}
```

## Performance Optimizations
- Use `loading.tsx` for Suspense boundaries
- Implement parallel data fetching
- Use `generateStaticParams` for static routes
- Enable incremental static regeneration with `revalidate`

3. Multi-File Resource Skills

Package extensive documentation and templates:

enterprise-patterns/
├── SKILL.md
├── resources/
│   ├── architecture-decision-records/
│   │   ├── adr-template.md
│   │   ├── example-microservices.md
│   │   └── example-event-sourcing.md
│   ├── design-patterns/
│   │   ├── repository-pattern.md
│   │   ├── cqrs-pattern.md
│   │   └── saga-pattern.md
│   └── api-standards/
│       ├── rest-conventions.md
│       ├── graphql-schema-design.md
│       └── versioning-strategy.md
└── templates/
    ├── service-template/
    └── module-template/

# In SKILL.md:
## Architecture Decision Records
When creating ADRs, use template in `resources/architecture-decision-records/adr-template.md`

## Design Patterns
Reference appropriate pattern from `resources/design-patterns/` based on:
- Data consistency requirements → CQRS or Event Sourcing
- Distributed transactions → Saga pattern
- Data access abstraction → Repository pattern

4. Contextual Tool Restrictions

Use allowed-tools to create safe, focused skills:

---
name: security-audit
description: Audit codebase for security vulnerabilities, secrets, and compliance issues. Use when reviewing security or preparing for audits.
allowed-tools: Read, Grep, Glob
# No Write, Edit, or Bash to prevent accidental modifications
---

# Security Audit

## What to Check
1. Hardcoded secrets (API keys, passwords)
2. SQL injection vulnerabilities
3. XSS vulnerabilities
4. Insecure dependencies
5. Missing authentication/authorization
6. Exposed sensitive endpoints

## Grep Patterns
Search for common issues:
```bash
# API keys
grep -r "api[_-]?key.*=.*['"]" .

# Passwords
grep -r "password.*=.*['"]" .

# AWS credentials
grep -r "aws[_-]?secret" .
```

## Reporting
Provide findings with:
- Severity (Critical, High, Medium, Low)
- File location and line number
- Remediation steps

Best Practices & Guidelines

Follow these proven practices to create effective, maintainable skills that integrate seamlessly with Claude Code.

Write Specific Descriptions

Include Concrete Examples

Provide example inputs, outputs, and edge cases in your SKILL.md:

## Examples

### Basic Usage
Input: "Create a React component for a user profile card"
Output: Component with props interface, styled card layout, TypeScript

### With Constraints
Input: "Create a React component using Tailwind CSS, no external dependencies"
Output: Component using only Tailwind classes, accessibility attributes

### Edge Cases
Input: "Create component but data might be undefined"
Output: Component with proper null checks, loading states, error boundaries

Organize by Task Type

Group related skills logically:

.claude/skills/
├── code-quality/
│   ├── code-reviewer/
│   ├── test-generator/
│   └── refactoring-assistant/
├── documentation/
│   ├── api-doc-generator/
│   ├── readme-creator/
│   └── changelog-maintainer/
├── deployment/
│   ├── deployment-checklist/
│   ├── env-validator/
│   └── ci-cd-helper/
└── framework-specific/
    ├── nextjs-app-router/
    ├── django-rest-framework/
    └── express-api-builder/

Version Control for Project Skills

Treat project skills as code:

# .gitignore
# Don't ignore project skills!
# .claude/skills/

# Do commit them
git add .claude/skills/
git commit -m "feat: Add API documentation generator skill"

# Document in README
## Claude Code Skills

This project includes skills for:
- API documentation generation
- Database migration assistance
- Deployment checklists

Use Tool Restrictions Wisely

Restrict tools based on skill purpose:

• Read-only skills (audits, analysis): Read, Grep, Glob
• Code generation (scaffolding, templates): Read, Write, Edit
• Build/deployment (testing, deployment): Read, Bash
• Full capabilities (refactoring, complex workflows): No restrictions

Test Skills Iteratively

Develop skills through iteration:

1. Start simple: Basic SKILL.md with core instructions
2. Test with examples: Use real tasks to validate behavior
3. Add edge cases: Document how to handle errors and unusual inputs
4. Refine descriptions: Adjust to ensure proper activation
5. Add resources: Include scripts and templates as needed