Agent Skill Creation
Agent Skills are capability modules that give AI agents new abilities. Unlike workflows (which guide how to approach tasks), skills define what an agent can do. Skills are portable across 25+ agent products including Claude Code, Cursor, and VS Code.
When to Use
Use this skill when you need to:
-
Create a new reusable AI agent capability
-
Scaffold a skill directory structure
-
Convert an existing guide or workflow into the Agent Skills format
-
Build a capability module for AI agents
About Skills
Skills are modular, self-contained packages that extend AI capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks - they transform a general-purpose agent into a specialized one equipped with procedural knowledge that no model can fully possess.
What Skills Provide:
-
Specialized workflows - Multi-step procedures for specific domains
-
Tool integrations - Instructions for working with specific file formats or APIs
-
Domain expertise - Company-specific knowledge, schemas, business logic
-
Bundled resources - Scripts, references, and assets for complex and repetitive tasks
Process
Step 1: Define the Skill
Before creating the skill, understand it through concrete examples. Ask questions like:
-
"What functionality should this skill support?"
-
"Can you give examples of how this skill would be used?"
-
"What would a user say that should trigger this skill?"
Then clarify its purpose:
What capability does this skill provide?
-
Example: "Process PDF files", "Generate API documentation", "Manage database migrations"
When should it activate? (Critical for the description field)
-
What user requests should trigger this skill?
-
What keywords or contexts indicate this skill is needed?
-
The description is the primary triggering mechanism - include all "when to use" information there, not in the body (the body is only loaded after triggering)
What resources does it need?
-
Scripts for deterministic operations that are repeatedly rewritten?
-
Reference documentation for domain knowledge?
-
Templates or assets for output generation?
What's the scope?
-
Keep skills focused on one capability
-
Split large skills into multiple smaller ones
Step 2: Scaffold the Skill
Run the Samuel CLI command:
samuel skill create <skill-name>
Name Requirements:
-
Lowercase alphanumeric and hyphens only
-
No consecutive hyphens (-- )
-
Cannot start or end with hyphen
-
Maximum 64 characters
This creates:
.claude/skills/<skill-name>/ ├── SKILL.md # Pre-filled template ├── scripts/ # For executable code ├── references/ # For additional docs └── assets/ # For templates, data
Step 3: Write SKILL.md
Edit the generated SKILL.md with:
Required Frontmatter
name: skill-name description: | What this skill does and when to use it. Include specific triggers and keywords. license: MIT metadata: author: your-name version: "1.0"
Description Best Practices:
-
Describe both what and when
-
Include keywords that trigger activation
-
Be specific, not vague ("Process PDF files" not "Helps with documents")
-
Maximum 1024 characters
Body Content
Write clear instructions that tell the AI agent how to use this skill:
-
Purpose: What capability this provides
-
When to Use: Scenarios that trigger this skill
-
Instructions: Step-by-step procedure
-
Examples: Input/output pairs
-
Notes: Warnings, edge cases, best practices
Keep under 500 lines - use reference files for detailed content.
Step 4: Add Resources (Optional)
Scripts (scripts/ )
Add executable code for deterministic operations:
scripts/process.py
def process_data(input_path): # Implementation pass
Script Best Practices:
-
Make scripts self-contained
-
Include helpful error messages
-
Handle edge cases
-
Document parameters
References (references/ )
Add documentation that AI loads on-demand:
references/api-guide.md
API Endpoints
...
Use references for:
-
Detailed technical docs
-
Domain-specific knowledge
-
Large examples
-
Configuration guides
Assets (assets/ )
Add templates and data files:
assets/ ├── template.html ├── config.json └── icons/
Step 5: Validate
Run validation to check against Agent Skills spec:
samuel skill validate <skill-name>
Validation Checks:
-
SKILL.md exists with valid YAML frontmatter
-
Name matches directory name
-
Name format is correct
-
Description is present
-
No fields exceed length limits
Fix any errors before proceeding.
Step 6: Test
Test the skill with real tasks:
-
Load the skill in your AI agent
-
Try scenarios from "When to Use"
-
Verify instructions are followed correctly
-
Check that examples produce expected output
-
Test edge cases
Step 7: Document
If the skill is significant, record in .claude/memory/ :
.claude/memory/YYYY-MM-DD-skill-name.md
Skill Created: <skill-name>
Purpose: Brief description
Key Decisions:
- Why this approach
- Alternatives considered
Testing Notes:
- What worked
- What needed adjustment
Best Practices
Concise is Key
The context window is a public good. Skills share it with everything else: system prompt, conversation history, other skills' metadata, and the actual user request. Default assumption: the AI is already very smart. Only add context it doesn't already have. Challenge each piece of information: "Does this paragraph justify its token cost?"
Good (50 tokens):
Extract PDF Text
Use pdfplumber:
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
**Bad** (150 tokens):
```markdown
## Extract PDF Text
PDF files are a common format... [unnecessary explanation]
Set Appropriate Degrees of Freedom
Match the level of specificity to the task's fragility and variability. Think of the AI as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
Freedom Level
When to Use
Implementation
Example
High
Multiple valid approaches
Text-based instructions
Code review process
Medium
Preferred pattern exists
Pseudocode or scripts with parameters
Report generation
Low
Fragile/critical operations
Specific scripts, few parameters
Database migrations
Use Progressive Disclosure
- Metadata (~100 tokens): Always loaded
- SKILL.md body (<5000 tokens): Loaded on activation
- References/Scripts: Loaded on-demand
Keep SKILL.md lean; move details to reference files.
What NOT to Include
A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation like README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, or CHANGELOG.md. The skill should only contain information needed for an AI agent to do the job at hand.
Bundled Resource Guidelines
- Scripts (scripts/
): Include when the same code is being rewritten repeatedly or deterministic reliability is needed. Scripts may be executed without loading into context, saving tokens.
- References (references/
): For documentation the AI should reference while working. Keeps SKILL.md lean; loaded only when determined needed. If files are large (>10k words), include grep search patterns in SKILL.md. Avoid duplication - information should live in either SKILL.md or references, not both.
- Assets (assets/
): Files not intended to be loaded into context, but used in the output (templates, images, boilerplate code, fonts).
Provide Examples
Examples teach better than explanations:
### Example: User Request
**Input**: "Help me merge these PDFs"
**Output**:
```python
# Code that handles the request
---
## Checklist
Before finalizing your skill:
- [ ] Name follows conventions (lowercase, hyphens, max 64 chars)
- [ ] Description is specific and under 1024 chars
- [ ] SKILL.md body is under 500 lines
- [ ] Instructions are clear and step-by-step
- [ ] Examples show input/output pairs
- [ ] Validation passes (`samuel skill validate`)
- [ ] Tested with real scenarios
- [ ] Scripts handle errors gracefully (if applicable)
---
## Related
- **Agent Skills Specification**: https://agentskills.io/specification
- **Example Skills**: https://github.com/anthropics/skills
- **Skills README**: `.claude/skills/README.md`