joelhooks/skill-creator

Skill Creator

This skill provides guidance for creating effective skills that extend agent capabilities with specialized knowledge, workflows, and tools.

What Are Skills?

Skills are modular, self-contained packages that extend agent capabilities by providing:

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Project-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex tasks

Think of skills as "onboarding guides" that transform a general-purpose agent into a specialized one equipped with procedural knowledge.

Skill Anatomy

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description, tags, tools)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      - Executable code (run with skills_execute)
    └── references/   - Documentation (load with skills_read)

Progressive Disclosure

Skills use a three-level loading system:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - On-demand as needed

Keep SKILL.md lean. Move detailed content to references/.

Creating a Skill

Step 1: Understand the Use Cases

Before creating, understand concrete examples:

• What triggers should activate this skill?
• What user requests would benefit from it?
• What workflows does it enable?

Ask clarifying questions if scope is unclear.

Step 2: Initialize the Skill

Use skills_init to create the full template structure:

skills_init(
  name: "my-skill",
  description: "Initial description",
  directory: ".opencode/skills"
)

This creates:

• SKILL.md with TODO placeholders
• scripts/ with example script
• references/ with example doc

Step 3: Complete the SKILL.md

Fill in the TODO placeholders. Key sections:

Frontmatter - Critical for discoverability:

---
name: my-skill
description: What it does and WHEN to use it. Be specific about triggering scenarios.
tags:
  - category
  - domain
tools:
  - tool_names_used
---

When to Use - Specific triggering scenarios:

## When to Use This Skill

- When working on X type of task
- When files matching Y pattern are involved
- When the user asks about Z topic

Instructions - Actionable, imperative form:

## Instructions

1. Read the configuration file first
2. Check for existing patterns before creating
3. Always validate output before completing

Examples - Realistic user requests:

## Examples

### Example: Realistic Scenario

**User**: "Help me do X"

**Process**:
1. First step
2. Second step
3. Final step

Step 4: Add Bundled Resources (Optional)

scripts/ - Executable helpers:

• Use for repeated automation
• Token-efficient (run without reading)
• Run via skills_execute

references/ - On-demand documentation:

• Detailed guides too long for SKILL.md
• API documentation
• Complex workflows
• Load via skills_read

Step 5: Test and Iterate

1. Use skills_use to load the skill
2. Try it on real tasks
3. Notice struggles or inefficiencies
4. Update SKILL.md based on experience
5. Test again

Best Practices

Metadata Quality

The name and description determine when the skill triggers:

Good descriptions:

• "Guide for creating MCP servers. Use when building tools that connect LLMs to external APIs."
• "File organization helper. Use when Downloads folder is messy or files need restructuring."

Bad descriptions:

• "A useful skill" (too vague)
• "Does stuff with files" (not actionable)

Writing Style

Use imperative/infinitive form throughout:

• "Read the file first" (not "You should read the file")
• "Check for patterns" (not "Consider checking patterns")

Keep SKILL.md Lean

• Core instructions only (<5k words)
• Move details to references/
• Use examples sparingly
• Delete placeholder sections

Design for Discoverability

• Tags help agents find skills by category
• "When to Use" sections enable proper triggering
• Tools list shows what capabilities the skill uses

Quick Reference

Creating Skills

| Tool | Use When | |------|----------| | skills_init | Want full template structure with TODOs | | skills_create | Have complete content ready to write | | swarm_learn | Converting learned patterns to skills |

Managing Skills

| Tool | Use For | |------|---------| | skills_list | Discover available skills | | skills_use | Activate a skill by loading its content | | skills_read | Load a reference file from a skill | | skills_update | Modify an existing skill | | skills_delete | Remove an obsolete skill |

Execution

| Tool | Use For | |------|---------| | skills_execute | Run a script from a skill | | skills_add_script | Add a new script to a skill |

From Learned Patterns to Skills

When you discover something reusable during work:

1. Identify the pattern - What worked well?
2. Consider scope - Is it project-specific or universal?
3. Use swarm_learn - Document the learning
4. Create the skill - Use create_skill=true or skills_init
5. Test and refine - Iterate based on usage

Skills make swarms smarter over time by preserving learned knowledge for future agents.