build-skill

name	build-skill
description	Creates new AI agent skills following the Agent Skills spec. Load FIRST before writing any SKILL.md. Provides required format, naming conventions, progressive disclosure patterns, and validation. Use when building, reviewing, or debugging skills.
allowed-tools	Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task

Building Skills

Skills extend agent capabilities with specialized knowledge, workflows, and tools.

Quick Start

Minimal viable skill in 30 seconds:

mkdir my-skill && cat > my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Does X when Y happens. Use for Z tasks.
---

# My Skill

Instructions go here.
EOF

Place in .agents/skills/ (project) or ~/.agents/skills/ (global).

Skill Type Decision Tree

What are you building?
├─ Instructions only → Simple skill (SKILL.md only)
│   Example: code-review guidelines, commit message format
│
├─ Domain knowledge → Reference-heavy skill (+ references/)
│   Example: API docs, database schemas, company policies
│
├─ Repeatable automation → Script-heavy skill (+ scripts/)
│   Example: PDF processing, data validation, file conversion
│
├─ Complex multi-step workflow → Multi-file skill (all directories)
│   Example: release process, deployment pipeline
│
└─ Large platform → Progressive skill 
    Example: AWS, GCP, Cloudflare (60+ products)

When to Create a Skill

Create a skill when:

• Same instructions repeated across conversations
• Project-specific conventions differ from generic best practices
• Domain knowledge model lacks (schemas, internal APIs, company policies)
• Workflow requires 3+ steps with specific order
• Code rewritten repeatedly for same task
• Team needs shared procedural knowledge

When NOT to Create a Skill

• Documentation already exists (create a reference instead)
• Pattern is trivial or self-explanatory
• It's a one-off task

Scenario	Do Instead
Single-use instructions	AGENTS.md or inline in conversation
Model already knows domain	Don't add redundant context
< 3 steps, no reuse	Inline instructions
Highly variable workflow	Higher-freedom guidelines
Just want to store files	Use regular directories

Reading Order

Task	Files to Read
New skill from scratch	anatomy.md → frontmatter.md
Optimize existing skill	progressive-disclosure.md
Add scripts/resources	bundled-resources.md
Find skill pattern	patterns.md
Debug/fix skill	gotchas.md

In This Reference

File	Purpose
anatomy.md	Skill directory structures
frontmatter.md	YAML spec, naming, validation
progressive-disclosure.md	Token-efficient design
bundled-resources.md	scripts/, references/, assets/
patterns.md	Real-world skill patterns
gotchas.md	Common mistakes + fixes

Scripts

Script	Purpose
scripts/init_skill.sh	Scaffold new skill
scripts/validate_skill.sh	Validate skill structure
scripts/package_skill.sh	Create distributable zip

Pre-Flight Checklist

Before using a skill:

• SKILL.md starts with --- (line 1, no blank lines)
• name: field present, matches directory name
• description: includes what + when to use
• Closing --- after frontmatter
• SKILL.md under 200 lines (use references/ for more)
• All internal links resolve

Run: ./scripts/validate_skill.sh ./my-skill

Skill Locations

Priority	Location
1	.opencode/skills/<name>/ (project)
2	~/.config/opencode/skills/<name>/ (global)
3	.claude/skills/<name>/ (Claude-compat)

Discovery walks up from CWD to git root. First-wins for duplicate names.

See Also

• Cloudflare Skill - Reference implementation