Guide for creating effective agent skills. Use when you want to create a new skill, improve an existing skill, or learn best practices for skill development. Helps codify learned patterns into reusable, discoverable skills.
This skill provides guidance for creating effective skills that extend agent capabilities with specialized knowledge, workflows, and tools.
Skills are modular, self-contained packages that extend agent capabilities by providing:
Think of skills as "onboarding guides" that transform a general-purpose agent into a specialized one equipped with procedural knowledge.
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)
Skills use a three-level loading system:
Keep SKILL.md lean. Move detailed content to references/.
Before creating, understand concrete examples:
Ask clarifying questions if scope is unclear.
Use skills_init to create the full template structure:
skills_init(
name: "my-skill",
description: "Initial description",
directory: ".opencode/skills"
)
This creates:
Fill in the TODO placeholders. Key sections:
Frontmatter - Critical for discoverability:
---