| name | skill-creator |
| description | Expert guidance for creating, structuring, and refining Agent Skills following the open standard. Use when working with skill files, authoring new skills, improving existing skills, or understanding skill architecture and best practices. Use PROACTIVELY when user mentions creating skills, structuring documentation, or building reusable agent capabilities. |
| license | MIT |
| compatibility | agent-skills-standard |
| metadata | {"category":"skill-development","version":"1.2.0","author":"Rodrigo Lago","standard":"https://agentskills.io"} |
Creating Agent Skills
Expert system for creating high-quality Agent Skills following the open standard, with comprehensive templates, validation checklists, and best practices.
What Are Agent Skills?
Agent Skills are folders of instructions, scripts, and resources that AI agents can discover and use dynamically to improve their capabilities. Think of them as plugins for AI agents.
Key Benefits
- Reusable: Write once, use across multiple agent platforms
- Discoverable: Agents can find and activate skills on demand
- Portable: Compatible with Claude, OpenCode, Cursor, VS Code, and 20+ platforms
- Version-controlled: Skills are just folders → perfect for Git
The Agent Skills Standard
This skill follows the Agent Skills open standard, originally developed by Anthropic and adopted by the community.
Supported platforms:
- Claude, Claude Code
- OpenCode, Crush
- Cursor, VS Code
- GitHub Copilot
- Gemini CLI, Roo Code, Goose
- And 15+ more...
Core Principles
1. Skills Are Structured Documentation
Skills are pure markdown documentation that agents load as context. No executable code required.
skill-name/
├── SKILL.md # Entry point (YAML + Markdown)
├── references/ # Detailed documentation
├── templates/ # Reusable templates
└── workflows/ # Step-by-step guides
2. YAML Frontmatter + Markdown Body
---
name: skill-identifier
description: What it does, when to use, examples
---
Your instructions here...
3. Progressive Disclosure
- SKILL.md: < 650 lines (quick reference + essential patterns)
- references/: Deep dives when needed
- templates/: Copy-paste starting points
- workflows/: Guided processes
4. English-First for LLM Efficiency
Write skills in English for optimal LLM performance:
- Faster inference
- Lower token costs
- Better comprehension
- Consistent behavior
5. Verification Loop (Post-Creation Validation)
CRITICAL: Every skill MUST be verified after creation.
Include verification as the final step in any skill creation workflow:
## Verification Loop
After creating any skill:
1. **Syntax Check** - Validate YAML frontmatter parses correctly
2. **Structure Check** - Verify all required files exist
3. **Link Check** - Confirm all internal references work
4. **Size Check** - SKILL.md < 650 lines
IF any check fails:
→ Fix the issue
→ Re-run verification
→ Do NOT report completion until all pass
Why? Professional systems (Claude Code, Codex, Gemini CLI) all require verification loops. Benefits:
- Catches errors before user discovers them
- Builds trust through reliability
- Reduces back-and-forth corrections
- Ensures consistent quality
Quick Start
What would you like to do?
Creating a New Skill
Choose your preferred mode:
Interactive Mode (Recommended for new users):
User: "Quiero crear un skill"
Agent: "¡Vamos paso a paso! ¿Qué problema quieres resolver?"
User: "Analizar código Python"
Agent: "Perfecto. ¿Cómo se llamará? Sugiero: python-analyzer..."
... (continues with guided questions)
Automatic Mode (For experienced users):
User: "Create a skill for analyzing Python code for errors"
Agent: [Creates skill immediately based on description]
Other Actions
Tip: When user says "crear skill" or "create a skill" without details,
prefer Interactive Mode to gather requirements step by step.
Example - Interactive Flow:
User: "Quiero crear un skill"
↓
1. Agent loads skill-creator
2. Agent follows workflows/interactive-creation.md
3. Agent asks: "¿Qué problema resuelve?"
4. User responds, agent confirms
5. Agent asks: "¿Cómo se llamará?"
... (8 phases of guided creation)
4. Agent uses Write tool to create ~/.config/opencode/skills/api-analyzer/SKILL.md
5. Done! Skill is ready to use
Skill Structure
Required Files
| File | Required | Purpose |
|---|
SKILL.md | ✅ Yes | Entry point with frontmatter + instructions |
README.md | ⚠️ Recommended | GitHub documentation |
LICENSE | ⚠️ Recommended | Open source license (MIT suggested) |
Optional Directories
| Directory | Purpose | When to Use |
|---|
references/ | Detailed documentation | Complex skills with multiple concepts |
templates/ | Reusable starting points | Skills that generate content/code |
workflows/ | Step-by-step guides | Multi-step processes |
examples/ | Complete examples | Show real usage patterns |
Minimal Skill Example
See templates/minimal-skill.md for a complete starting template.
Quick structure:
---
name: your-skill-name
description: >-
What it does. When to use it.
<example>User: "..." Assistant: "..."</example>
---
Instructions here...
Frontmatter Specification
See references/frontmatter-spec.md for complete details.
Required Fields
| Field | Format | Description |
|---|
name | kebab-case | Unique identifier, < 64 chars |
description | multi-line | What + When + <example> blocks, < 1024 chars |
Optional Fields
| Field | Example | Purpose |
|---|
license | MIT | SPDX identifier |
compatibility | agent-skills-standard | Platform support |
metadata.category | development | Organization |
metadata.version | "1.0.0" | Semantic versioning |
metadata.author | "Your Name" | Attribution |
metadata.tags | [python, testing] | Discoverability |
Description Best Practices
Rules:
- Include WHAT it does (1 sentence)
- Include WHEN to use (triggers)
- Include at least 1
<example> block
- Keep under 1024 characters
- Write in third person
Naming Conventions
Skill Names (frontmatter name)
Use kebab-case with descriptive nouns or verb phrases:
✅ Good:
code-reviewerapi-documentationdatabase-migrationsecurity-auditprompt-engineering
❌ Avoid:
helper, utils, tool (too vague)my-skill, skill1 (not descriptive)CodeReviewer (wrong case)
Folder Names
Match your skill's name field:
~/.config/opencode/skills/
├── code-reviewer/
├── api-documentation/
└── security-audit/
File Organization
See references/skill-anatomy.md for complete structure breakdown.
Quick Reference
| Directory | Purpose | Files per Directory |
|---|
references/ | Deep dive documentation | One topic per file |
templates/ | Copy-paste starting points | Use {{VAR}} syntax |
workflows/ | Step-by-step processes | Numbered steps |
examples/ | Concrete usage examples | README per example |
SKILL.md Sections
# Skill Name → Brief intro
## Core Principles → High-level concepts
## Quick Start → How to use
## Main Instructions → Detailed guidance
## When to Use → Triggers and cases
## References → Links to refs/
Rule: SKILL.md is the entry point. Keep it < 650 lines. Details go in references/.
Skill Complexity Scale
Choose the right size for your skill:
| Complexity | SKILL.md Lines | Directories | When to Use |
|---|
| 🟢 Micro | 50-150 | None | Single concept (code style, naming conventions) |
| 🟡 Simple | 150-300 | templates/ | Focused domain (doc writer, linter config) |
| 🟠 Standard | 300-500 | refs + tmpl | Full workflow (component creator, API designer) |
| 🔴 Complex | 500-650 | All dirs | Multi-domain system (agent-creator, skill-creator) |
Decision Logic:
IF single concept, no templates needed → Micro
ELSE IF one domain with templates → Simple
ELSE IF full workflow with references → Standard
ELSE IF multi-domain with all directories → Complex
DEFAULT: Start with Micro/Simple. Upgrade only when proven necessary.
Why Smaller is Better:
- Faster to load (less context)
- Cheaper to run (fewer tokens)
- Easier to maintain
- More focused behavior
- Better discoverability
Upgrade Signals:
| Signal | Action |
|---|
| SKILL.md > 300 lines | Consider splitting to references/ |
| Repeated patterns | Create templates/ |
| Multi-step processes | Add workflows/ |
| Multiple unrelated concepts | Split into separate skills |
Token Optimization Guide
Optimize skills for performance and cost:
File Size Guidelines
| File Type | Recommended | Maximum | Notes |
|---|
| SKILL.md | 200-400 lines | 650 lines | Entry point, quick reference |
| Reference | 100-300 lines | 600 lines | Single topic focus |
| Template | 50-200 lines | 400 lines | Copy-paste ready |
| Workflow | 100-400 lines | 800 lines | Step-by-step process |
Token-Saving Patterns
- Progressive Loading - Core in SKILL.md, details in references/
- Links Over Inline - Reference files instead of embedding content
- Tables Over Prose - Structured data is more token-efficient
- Decision Trees - Clear IF/ELSE logic over long explanations
- Examples as Proof - Show don't tell (1 example > 10 paragraphs)
Content Density Targets
| Section Type | Target | Anti-Pattern |
|---|
| Core Principles | 5-7 items max | 15+ principles nobody reads |
| Quick Start | 3-5 steps | Essay-length introduction |
| Tables | 5-10 rows | 50-row reference tables |
| Examples | 2-3 concrete examples | Abstract descriptions |
Rule: If a section exceeds its target, split it into references/.
Validation Checklist
Before publishing a skill, verify:
See references/validation-checklist.md for complete rubric.
Best Practices
Do's ✅
- Write in English - Optimal for LLM processing
- Use clear descriptions - What + when + examples
- Include examples - Show real usage with
<example> blocks
- Organize content - Use references/ for deep dives
- Provide templates - Make it easy to get started
- Document limitations - Be explicit about what skill cannot do
- Version your skill - Use semantic versioning (1.0.0)
Don'ts ❌
| Anti-Pattern | Problem | Solution |
|---|
| No examples | Users don't know when to use | Add <example> blocks |
| Vague description | Agent won't activate skill | Specific triggers + use cases |
| Monolithic SKILL.md | Overwhelming (>650 lines) | Split into references/ |
| Executable scripts | Breaks portability | Pure markdown documentation |
| Missing README | Hard to discover on GitHub | Add README.md |
| No versioning | Breaking changes unclear | Use CHANGELOG.md |
| Skipping Verification | Errors found by users, not author | Always run verification loop |
| Wrong Complexity | Complex skill for simple concept | Start Micro, upgrade when needed |
| No Token Optimization | Bloated, slow loading | Tables over prose, links over inline |
| Missing Limitations | Users try unsupported features | Document what skill cannot do |
| Non-English Content | LLM inefficiency, higher costs | Always write in English |
| No Progressive Disclosure | Everything inline, too long | Core in SKILL.md, details in refs/ |
Skill Creation Process
Method: Direct File Creation
When creating a skill, use the Write tool:
1. Understand purpose (ask questions if needed)
2. Read template: templates/minimal-skill.md
3. Customize for specific use case
4. Use Write tool to create: ~/.config/opencode/skills/<name>/SKILL.md
5. (Optional) Add references/, templates/, workflows/ as needed
Guided Workflow
Two modes available:
🧙 Interactive Mode - workflows/interactive-creation.md
- Ask questions one at a time
- Wait for user responses
- Confirm understanding at each step
- Best for: first-time creators, complex skills
⚡ Automatic Mode - workflows/create-new-skill.md
- Create skill from initial description
- No back-and-forth questions
- Best for: experienced users, clear requirements
Decision Guide:
User says: "Quiero crear un skill" (no details)
→ Use Interactive Mode
User says: "Create a skill for X that does Y and Z"
→ Use Automatic Mode
Post-Creation Verification Loop
CRITICAL: After creating any skill, verify it works correctly.
Verification Steps
head -30 ~/.config/opencode/skills/<name>/SKILL.md | yq .
ls -la ~/.config/opencode/skills/<name>/
wc -l ~/.config/opencode/skills/<name>/SKILL.md
Functional Tests
| Test | How | Expected |
|---|
| Discovery | Search for skill in OpenCode | Skill appears in available skills |
| Activation | Reference skill in context | Agent loads skill successfully |
| Core Function | Use primary feature | Works as documented |
| Edge Case | Empty/ambiguous input | Handles gracefully |
| Links | Click all internal references | All links resolve |
Verification Decision Tree
1. Create skill files
↓
2. YAML syntax valid?
NO → Fix YAML errors → retry
YES ↓
3. All required files present?
NO → Create missing files → retry from step 2
YES ↓
4. SKILL.md < 650 lines?
NO → Split to references/ → retry from step 2
YES ↓
5. Test skill activation
↓
6. Skill works as expected?
NO → Edit content → retry from step 5
YES ↓
7. ✅ Skill ready for use
Report Template
After verification, report:
## Skill Created: {name}
### Configuration
- Complexity: {🟢 Micro | 🟡 Simple | 🟠 Standard | 🔴 Complex}
- Lines: {count}
- Directories: {list}
### Verification
- [x] YAML syntax valid
- [x] Structure complete
- [x] Size within limits
- [x] Activation works
- [x] Links verified
### Usage
- Location: `~/.config/opencode/skills/{name}/`
- Load: Reference in context or skill tool
- Purpose: {brief description}
Success Criteria
A well-structured skill:
- ✅ Has valid YAML frontmatter with
name and description
- ✅ Description includes WHAT, WHEN, and
<example> blocks
- ✅ Written entirely in English (LLM efficiency)
- ✅ Appropriate complexity level (start with 🟢 Micro, upgrade only when needed)
- ✅ SKILL.md < 650 lines (uses references/ for deep dives)
- ✅ Token-optimized (tables over prose, links over inline)
- ✅ Includes at least 1 concrete usage example
- ✅ Documents what it can and cannot do
- ✅ Has README.md for GitHub discoverability
- ✅ Follows Agent Skills standard structure
- ✅ Has been verified post-creation (syntax, structure, activation)
- ✅ Progressive disclosure (core in SKILL.md, details in references/)
- ✅ No executable scripts (pure markdown)
Reference Documentation
Templates
Workflows
Philosophy
"A great skill is like a well-written manual:
- Clear about its purpose (description with examples)
- Focused on one domain (single responsibility)
- Organized for easy reference (SKILL.md + references)
- Portable across platforms (Agent Skills standard)
- Documented for contributors (README + LICENSE)"
Create skills that are focused, clear, and reusable.
Additional Resources
Contributing
This skill is open source (MIT). Contributions welcome:
- Report issues
- Suggest improvements
- Share your skills
Version: 1.2.0
Author: Rodrigo Lago
License: MIT
Standard: Agent Skills (https://agentskills.io)
