Skill Creator

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
---
# Skill Name

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

• Validate existing skill → Use checklist: validation-checklist.md
• Understand structure → Read: skill-anatomy.md
• Copy template → Start with: templates/minimal-skill.md

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

Optional Directories

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>
---
# Your Skill

Instructions here...

Frontmatter Specification

See references/frontmatter-spec.md for complete details.

Required Fields

Optional Fields

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-reviewer
• api-documentation
• database-migration
• security-audit
• prompt-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/           # name: code-reviewer
├── api-documentation/       # name: api-documentation
└── security-audit/          # name: security-audit

File Organization

See references/skill-anatomy.md for complete structure breakdown.

Quick Reference

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:

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:

Token Optimization Guide

Optimize skills for performance and cost:

File Size Guidelines

Token-Saving Patterns

1. Progressive Loading - Core in SKILL.md, details in references/
2. Links Over Inline - Reference files instead of embedding content
3. Tables Over Prose - Structured data is more token-efficient
4. Decision Trees - Clear IF/ELSE logic over long explanations
5. Examples as Proof - Show don't tell (1 example > 10 paragraphs)

Content Density Targets

Rule: If a section exceeds its target, split it into references/.

Validation Checklist

Before publishing a skill, verify:

• SKILL.md exists with valid YAML frontmatter
• name field is kebab-case and descriptive
• description includes what/when/examples
• Description has at least one <example> block
• Appropriate complexity level chosen (🟢🟡🟠🔴)
• Instructions are clear and actionable
• Examples demonstrate real usage
• English language throughout
• SKILL.md < 650 lines (split to references/ if longer)
• README.md exists (for GitHub)
• LICENSE file present
• No executable scripts (pure markdown)
• Verification loop completed (syntax, structure, activation)

See references/validation-checklist.md for complete rubric.

Best Practices

Do's ✅

1. Write in English - Optimal for LLM processing
2. Use clear descriptions - What + when + examples
3. Include examples - Show real usage with <example> blocks
4. Organize content - Use references/ for deep dives
5. Provide templates - Make it easy to get started
6. Document limitations - Be explicit about what skill cannot do
7. Version your skill - Use semantic versioning (1.0.0)

Don'ts ❌

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

# 1. Syntax Check - Validate YAML frontmatter
head -30 ~/.config/opencode/skills/<name>/SKILL.md | yq .
# Should parse without errors

# 2. Structure Check - Verify files exist
ls -la ~/.config/opencode/skills/<name>/

# 3. Size Check - Verify SKILL.md length
wc -l ~/.config/opencode/skills/<name>/SKILL.md
# Should be < 650 lines

Functional Tests

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

• Agent Skills Standard: https://agentskills.io
• Anthropic Skills Repo: https://github.com/anthropics/skills
• Agent Skills Spec: https://github.com/agentskills/agentskills
• OpenCode Docs: https://opencode.ai/docs/

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)