Skill Architect

Create high-quality OpenCode skills.

Quick Start

What is a Skill?

Skills are domain knowledge packages with optional scripts and resources:

my-skill/
├── SKILL.md          # Instructions (always loaded)
├── scripts/          # Executable code
├── references/       # Documentation (loaded on demand)
└── assets/           # Templates, images, files

Location: .opencode/skills/<name>/

Use a skill when you need:

• Executable scripts for external APIs or complex operations
• Reference documentation for domain knowledge
• Templates or assets for output generation
• Multi-step workflows with decision trees

Context Efficiency

Skills load into the main context window. To keep context lean:

1. Keep SKILL.md under 500 lines - Move details to references/
2. Use subagents for heavy analysis - They run in isolated context
3. Progressive disclosure - Load references only when needed
4. Scripts execute, not read - Zero token cost

When to Use Subagents

For comprehensive skill analysis, delegate to the @skill-analyzer subagent.

Creating a Skill

Phase 1: Discovery

Understand what the skill needs to do:

1. List 3-5 concrete use cases
2. Identify what Claude doesn't already know (proprietary formats, APIs, sequences)
3. Determine if scripts are needed (repetitive operations, external APIs)

Phase 2: Choose Archetype

Select the pattern that fits your use case (see references/archetypes.md):

Phase 3: Scaffold

npx tsx scripts/init.ts <name>

Creates the directory structure with a template SKILL.md.

Phase 4: Implement

Write your SKILL.md following these guidelines:

1. Keep it under 500 lines - Move details to references
2. Start with a decision tree - Help Claude pick the right workflow
3. Show, don't tell - Concrete examples beat abstract descriptions
4. Include error recovery - What to do when things fail

Phase 5: Validate

npx tsx scripts/validate.ts .opencode/skills/<name>

Fix any errors and address warnings.

Phase 6: Iterate

Test with real queries. Refine based on what you observe.

Writing Effective Instructions

Four core principles (details in references/patterns.md):

1. Claude is Already Smart

Don't explain obvious things. Focus on what Claude doesn't know:

• Proprietary formats and schemas
• Business-specific logic
• Required sequences and dependencies

2. Match Specificity to Fragility

3. Show, Don't Tell

• Concrete examples > abstract descriptions
• Input/output pairs for format expectations
• Real error messages with solutions

4. Progressive Disclosure

• SKILL.md = entry point (always loaded)
• references/ = details (on demand)
• scripts/ = execute without reading

Skill Structure

SKILL.md

The main entry point. Must have YAML frontmatter:

---
name: my-skill
description: >
  [What it does]. Use when: (1) [Trigger 1], (2) [Trigger 2], (3) [Trigger 3].
---

Required fields:

Optional fields:

---
name: my-skill
description: >
  [What it does]. Use when: (1) [Trigger 1], (2) [Trigger 2].
license: MIT                      # License identifier
allowed-tools:                    # Restrict which tools the skill can use
  - read
  - write
  - bash
metadata:                         # Custom metadata
  version: "1.0"
  author: "Team Name"
---

scripts/

Executable code. Prefer TypeScript (npx tsx).

references/

Documentation loaded on demand. Use for content over 100 lines.

assets/

Files used in output (templates, images). Not loaded into context.

Scripts Reference

init.ts

npx tsx scripts/init.ts my-tool

Creates .opencode/skills/my-tool/ with template files.

validate.ts

npx tsx scripts/validate.ts .opencode/skills/my-tool

Errors (must fix): Missing SKILL.md, invalid frontmatter, bad name/description

Warnings (should fix): Over 500 lines, missing references, weak description

Common Mistakes

Subagent: skill-analyzer

For deep analysis without bloating main context, use:

@skill-analyzer Analyze the skill at .opencode/skills/my-tool

The subagent runs in its own context and returns a concise summary.

Examples

See references/examples/ for annotated skills:

• deploy-buddy.md - Workflow skill
• stripe-sync.md - Integration skill