jyasuu/agent-skills

Agent Skills

Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources that Claude uses automatically when relevant.

Quick Start

# A basic skill structure
---
name: my-skill
description: Brief description of what this Skill does
---

# My Skill

## Instructions
Clear, step-by-step guidance for Claude to follow

## Examples
Concrete examples of using this Skill

Why use Skills

Skills provide domain-specific expertise that transforms general-purpose agents into specialists. Unlike prompts, Skills load on-demand and eliminate repetitive guidance.

Key benefits:

• Specialize Claude: Tailor capabilities for specific domains
• Reduce repetition: Create once, use automatically
• Compose capabilities: Combine Skills to build complex workflows

How Skills Work

Skills leverage Claude's VM environment with filesystem access. They exist as directories containing instructions, executable code, and reference materials.

Three Levels of Loading

| Level | When Loaded | Token Cost | Content | |-------|-------------|------------|---------| | Level 1: Metadata | Always (startup) | ~100 tokens | name and description from YAML frontmatter | | Level 2: Instructions | When triggered | Under 5k tokens | SKILL.md body with guidance | | Level 3+: Resources | As needed | Unlimited | Bundled files executed via bash |

Progressive disclosure ensures only relevant content occupies the context window.

Skill Directory Structure

my-skill/
├── SKILL.md              # Main instructions
├── GUIDE.md              # Additional guidance
├── REFERENCE.md          # API reference
└── scripts/
    └── helper.py         # Utility scripts

Instructions: Additional markdown files with specialized guidance Code: Executable scripts that Claude runs via bash Resources: Reference materials like schemas, templates, examples

Skill Structure

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

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance]

## Examples
[Concrete examples]

Field Requirements

name:

• Maximum 64 characters
• Lowercase letters, numbers, and hyphens only
• Cannot contain XML tags
• Cannot use reserved words: "anthropic", "claude"

description:

• Must be non-empty
• Maximum 1024 characters
• Cannot contain XML tags
• Should explain what the Skill does AND when to use it

Creating Custom Skills

For Claude Code

1. Create a directory in .claude/skills/
2. Add a SKILL.md file with YAML frontmatter
3. Optionally add supporting files (guides, scripts, resources)
4. Claude discovers and uses them automatically

.claude/skills/
├── my-skill/
│   ├── SKILL.md
│   └── scripts/
│       └── helper.sh
└── another-skill/
    └── SKILL.md

For Claude API

1. Create Skill as a directory with SKILL.md
2. Upload via Skills API (/v1/skills endpoints)
3. Reference skill_id in the container parameter
4. Requires beta headers:
   • code-execution-2025-08-25
   • skills-2025-10-02
   • files-api-2025-04-14

For Claude.ai

1. Create Skill as a directory with SKILL.md
2. Zip the skill directory
3. Upload through Settings > Features
4. Available on Pro, Max, Team, Enterprise plans

Best Practices

Writing Effective Skills

Be specific about when to use:

description: Extract text from PDF files using pdfplumber. Use when user mentions PDFs, text extraction, or document processing.

Include concrete examples:

## Examples

To extract text from a PDF:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Organize progressively:

• Quick start first
• Common workflows
• Advanced scenarios
• Reference materials

Bundling Resources

Use scripts for reliability:

# Scripts execute without loading code into context
$ bash validate.sh
Validation passed

Include reference materials:

• API documentation
• Database schemas
• Code examples
• Templates

Security Considerations

Use Skills from trusted sources only:

• Audit thoroughly: Review all files bundled in the Skill
• External sources are risky: Skills fetching external content pose risks
• Tool misuse: Malicious Skills can invoke tools in harmful ways
• Data exposure: Skills with sensitive data access could leak information
• Treat like installing software: Only use Skills from trusted sources

Cross-Surface Availability

| Surface | Custom Skills | Pre-built Skills | |---------|---------------|------------------| | Claude API | Yes | Yes (pptx, xlsx, docx, pdf) | | Claude Code | Yes (filesystem-based) | No | | Claude.ai | Yes (uploaded) | Yes (pptx, xlsx, docx, pdf) |

Custom Skills do not sync across surfaces - manage separately for each.

Runtime Environment

Claude API:

• No network access
• No runtime package installation
• Pre-configured dependencies only

Claude Code:

• Full network access
• Local package installation only

Claude.ai:

• Varying network access (depends on settings)

Pre-built Agent Skills

Available immediately:

• PowerPoint (pptx): Create presentations, edit slides, analyze content
• Excel (xlsx): Create spreadsheets, analyze data, generate charts
• Word (docx): Create documents, edit content, format text
• PDF (pdf): Generate formatted PDF documents and reports

Sharing Models

| Surface | Scope | |---------|-------| | Claude.ai | Individual user only | | Claude API | Workspace-wide | | Claude Code | Personal (~/.claude/skills/) or project-based (.claude/skills/) |

Advanced Patterns

Chaining Skills

Combine Skills to build complex workflows:

1. Skill A processes input
2. Skill B transforms output
3. Skill C validates results

Environment-Aware Skills

Design Skills to adapt to runtime:

## Runtime Notes

- Claude API: Use pre-installed packages only
- Claude Code: Can install packages locally
- Adjust behavior based on available tools

Progressive Disclosure

Structure Skills so Claude loads only what's needed:

# Main Skill

## Quick Start
Essential information for common tasks

## Advanced Usage
Detailed guidance when needed

See [REFERENCE.md](REFERENCE.md) for complete API documentation.

Troubleshooting

Skill Not Loading

1. Verify SKILL.md exists in skill directory
2. Check YAML frontmatter is valid
3. Ensure name uses only lowercase letters, numbers, hyphens
4. Confirm description is non-empty

Permission Issues

• Claude Code: Check .claude/skills/ directory permissions
• Claude API: Verify beta headers are set correctly
• Claude.ai: Confirm plan includes code execution

Context Overflow

• Move detailed reference to separate files
• Use scripts for complex operations
• Structure with progressive disclosure

File Reference

• Authoring Best Practices
• Use Skills with Claude API
• Use Skills in Claude Code
• Agent Skills SDK