writing-claude-skills
Create effective Agent Skills following the agentskills.io specification. Use when creating new skills, reviewing existing skills, or improving skill descriptions. Covers SKILL.md format, naming, descriptions, structure, progressive disclosure, and testing patterns.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for developing high-quality Agent Skills based on the agentskills.io specification. It guides users through the entire lifecycle of skill creation—from defining metadata and directory structures to optimizing token usage and testing activation triggers—ensuring AI agents remain modular, efficient, and context-aware.
Use Cases
- Standardizing AI Agent Development: Use this skill to ensure all team members follow a consistent format (SKILL.md) when building new agent capabilities for modular AI systems.
- Optimizing Token Consumption: Apply progressive disclosure patterns and token budget guidelines to prevent context overflow and reduce latency in complex agentic workflows.
- Improving Agent Reliability: Follow the testing and activation protocols to verify that skills trigger correctly for specific user intents while avoiding unrelated activation.
- Refining Legacy Prompts: Convert repetitive instructions or generic system prompts into structured, reusable Agent Skills to improve maintainability and performance.
- Architecting Complex Agentic Systems: Design directory structures and multi-stage loading processes that allow agents to scale without hitting context limits.
| name | writing-claude-skills |
|---|---|
| description | Create effective Agent Skills following the agentskills.io specification. Use when creating new skills, reviewing existing skills, or improving skill descriptions. |
| allowed-tools | Read, Grep, Glob |
Writing Agent Skills
Agent Skills are modular packages that extend AI agent capabilities. Skills are directories containing a SKILL.md file with YAML frontmatter and Markdown instructions.
Progressive Disclosure
Skills load in three stages to optimize context:
- Discovery (~50-100 tokens): Only names and descriptions at startup
- Activation (<5000 tokens): Full SKILL.md when task matches description
- Execution: Referenced files load only when needed
Token budget: Keep main SKILL.md under 500 lines. Move detailed content to supporting files.
SKILL.md Structure
---
name: skill-name-here
description: What it does. Use when [triggers]. Covers [keywords].
allowed-tools: Read, Grep, Glob # optional
---
[Markdown body with instructions, examples, guidelines]
Required Fields
name
1-64 characters, lowercase alphanumeric with hyphens. Must match parent directory name.
Include domain when capability could apply to multiple areas: mcp-server-development not server-development.
description
Critical field--agents use this to decide when to activate.
Pattern: "[Capability]. Use when [triggers]. Covers [keywords]."
Directory Structure
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: extended documentation
└── assets/ # Optional: templates, data files
Body Content
- Opening Context: Brief purpose and activation triggers
- Philosophy: Guide decision-making before prescriptive rules
- Guidelines: Focused, actionable guidance with examples
- Anti-patterns: What to avoid with examples
- Remember: Core philosophy reminders
Tone: Bold, opinionated, directive. Use imperative mood.
Content Principles
- Actionable over theoretical: Patterns to follow, not abstract concepts
- Examples over explanation: Show don't tell
- Negative space: What NOT to do matters
- Token efficiency: Every line must justify its context cost
Common Mistakes
| Mistake | Fix |
|---|---|
| Overly broad scope | Separate skills for each domain |
| Missing activation triggers | Add "Use when..." with scenarios |
| Just a list of rules | Explain WHY before HOW |
| Redundant with tools | Guide decision-making, not just run tools |
Testing
- Activation: Verify skill loads for trigger words, not for unrelated work
- Clarity: Ask teammate "When would you use this?"
- Effectiveness: Compare results with and without skill
Skills vs Agents
| Scenario | Skill | Agent |
|---|---|---|
| Guidance during work | Yes | No |
| Simple, frequent tasks | Yes | No |
| Complex autonomous tasks | No | Yes |
| Multi-step orchestration | No | Yes |
When to Create a Skill
Create when you see: repetitive instructions, generic outputs needing refinement, domain expertise gaps, consistency enforcement needs, repeated workflows.
Remember
- Specific beats generic - In naming and content
- Trigger words matter - Include terms users naturally mention
- One skill, one job - Focus trumps comprehensiveness
- Token efficiency - Every line earns its place
- Test activation - Verify the skill loads when expected
Skills are prompt engineering at scale. Make every word count.