Standard Skill

Standard Skill Example

This demonstrates the recommended OpenCode skill structure with progressive disclosure.

What This Demonstrates

A standard skill consists of:

• SKILL.md with core content (~1,500-2,000 words)
• references/ directory with detailed documentation
• Progressive disclosure for efficient context usage

This is the recommended structure for most skills.

When to Use Standard Structure

Use this structure when:

• Content exceeds 2,000 words total
• Need detailed documentation
• Have multiple sub-topics
• Want efficient progressive disclosure

This covers 80% of skill use cases.

Structure

standard-skill/
├── SKILL.md
└── references/
    └── detailed-guide.md

SKILL.md contains:

• Overview and key concepts
• Core workflows and procedures
• Quick reference material
• Pointers to references/

references/ contains:

• Detailed patterns and techniques
• Comprehensive documentation
• Troubleshooting guides
• Advanced use cases

Progressive Disclosure in Action

Level 1: Metadata (Always Loaded)

The skill name and description from frontmatter:

• ~50-100 words
• Helps agents decide whether to load skill

Level 2: SKILL.md Body (Loaded When Triggered)

Core content in this file:

• ~1,500-2,000 words
• Essential procedures and workflows
• Quick reference tables
• Loaded when agent decides skill is relevant

Level 3: References (Loaded As Needed)

Detailed documentation in references/:

• 2,000-5,000+ words per file
• Loaded only when agent needs specific details
• Keeps context efficient

Content Allocation Strategy

What Goes in SKILL.md

Include:

• Purpose and overview
• Core workflows (step-by-step)
• Quick reference tables
• Common use cases
• Pointers to references/

Keep focused: 1,500-2,000 words

What Goes in references/

Include:

• Detailed patterns and techniques
• Comprehensive API documentation
• Edge cases and troubleshooting
• Advanced use cases
• Migration guides

Be comprehensive: 2,000-5,000+ words per file

Example: API Design Skill

Here's how a real skill might be organized:

SKILL.md (1,800 words):

# API Design

## Overview
Core principles of RESTful API design...

## Core Workflow
1. Define resources
2. Choose HTTP methods
3. Design URL structure
4. Define response formats
5. Handle errors

## Quick Reference: HTTP Methods
| Method | Purpose      | Idempotent |
|--------|-------------|------------|
| GET    | Retrieve    | Yes        |
| POST   | Create      | No         |
| PUT    | Replace     | Yes        |
| PATCH  | Update      | No         |
| DELETE | Remove      | Yes        |

## Common Patterns
[Brief overview of pagination, filtering, sorting]

## Additional Resources
- **`references/rest-principles.md`** - Detailed REST constraints
- **`references/authentication.md`** - Auth strategies
- **`references/versioning.md`** - API versioning approaches

references/rest-principles.md (2,400 words):

# Detailed REST Principles

## Resource-Oriented Design
[Comprehensive explanation - 800 words]

## Uniform Interface
[Detailed coverage - 600 words]

## Statelessness
[In-depth discussion - 500 words]

## HATEOAS
[Complete guide - 500 words]

references/authentication.md (2,100 words):

# Authentication Strategies

## API Keys
[Detailed guide - 500 words]

## OAuth 2.0
[Comprehensive coverage - 800 words]

## JWT
[Complete explanation - 500 words]

## Best Practices
[Security guidance - 300 words]

Benefits

Context Efficiency

Without progressive disclosure:

• Single file: 6,300 words
• All loaded when skill triggers
• High context cost

With progressive disclosure:

• SKILL.md: 1,800 words (always loaded)
• references/: 4,500 words (loaded as needed)
• 71% reduction in typical context usage

Maintainability

Organized structure:

• Core content separate from details
• Easy to update specific topics
• Clear responsibility per file

Scalability:

• Add new reference files as topics grow
• SKILL.md stays focused
• No single file becomes unwieldy

Creating a Standard Skill

Step 1: Create Structure

mkdir -p my-skill/references
touch my-skill/SKILL.md

Step 2: Write SKILL.md

Create frontmatter and core content:

---
name: my-skill
description: This skill should be used when the user asks to "trigger 1", "trigger 2", or needs specific guidance.
---

# My Skill

## Overview
[2-3 sentences]

## Core Workflow
[Essential procedures]

## Quick Reference
[Tables, commands]

## Additional Resources
- **`references/detailed-guide.md`** - Comprehensive documentation

Step 3: Create Reference Files

Add detailed documentation:

touch my-skill/references/detailed-guide.md

Write comprehensive content in each reference file.

Step 4: Reference Resources

Always mention reference files in SKILL.md so agents know they exist.

When to Upgrade

Upgrade to complete structure when:

• Need working code examples → Add examples/
• Have utility scripts → Add scripts/
• Require automation tools → Add scripts/

See complete-skill example for full structure.

Additional Resources

Reference Files

This skill includes demonstration reference files:

• references/detailed-guide.md - Example of detailed documentation structure

Study this reference to see how to organize comprehensive content separate from core SKILL.md content.

Summary

Standard structure (SKILL.md + references/) is the recommended pattern for most skills:

Use when:

• Content exceeds 2,000 words
• Need detailed documentation
• Want progressive disclosure

Benefits:

• Efficient context usage
• Better organization
• Easy to maintain
• Scalable as content grows

Structure:

skill-name/
├── SKILL.md (1,500-2,000 words)
└── references/
    ├── topic1.md (2,000-5,000 words)
    ├── topic2.md (2,000-5,000 words)
    └── topic3.md (2,000-5,000 words)

This is the sweet spot for most OpenCode skills - focused core content with detailed references available on demand.