Complete Skill

Complete Skill Example

This demonstrates the full OpenCode skill structure with all features: references, examples, and scripts.

What This Demonstrates

A complete skill includes:

• SKILL.md with core content (~1,500-2,000 words)
• references/ with detailed documentation
• examples/ with working code samples
• scripts/ with utility tools
• Full progressive disclosure

Use this structure for complex domains requiring comprehensive support.

Structure

complete-skill/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── examples/
│   └── working-example.sh
└── scripts/
    └── validate.sh

When to Use Complete Structure

Use this structure when:

• Need working code examples users can copy
• Have utility scripts for validation or automation
• Require comprehensive documentation
• Building complex domain skill

This is for ~20% of skills with sophisticated requirements.

Three-Level Progressive Disclosure

Level 1: Metadata (Always Loaded)

From frontmatter - agents always see this:

name: complete-skill
description: This skill should be used when the user asks to "demonstrate complete skill structure"...

Size: ~50-100 words
Purpose: Help agents decide whether to load skill

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

This file you're reading now:

• Core workflows and procedures
• Quick reference material
• Pointers to all resources

Size: ~1,500-2,000 words
Purpose: Provide essential guidance

Level 3: Bundled Resources (Loaded As Needed)

references/ - Detailed docs loaded when agents need specifics:

• patterns.md - Common patterns and anti-patterns
• advanced.md - Advanced techniques

examples/ - Working code loaded when agents need samples:

• working-example.sh - Complete runnable script

scripts/ - Utilities executed or loaded as needed:

• validate.sh - Validation tool

Content Allocation

SKILL.md Content

Include here:

• Purpose and overview (you're reading it)
• Core workflows (next section)
• Quick reference tables
• Pointers to all resources

Keep focused: 1,500-2,000 words

references/ Content

Include in reference files:

• Detailed patterns and techniques
• Comprehensive explanations
• Edge cases and troubleshooting
• Advanced use cases

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

examples/ Content

Include in example files:

• Complete working code
• Configuration files
• Templates users can copy
• Real-world usage demonstrations

Make runnable: Users should be able to execute directly

scripts/ Content

Include in script files:

• Validation tools
• Testing helpers
• Automation utilities
• Parsing tools

Make executable: Scripts should run with clear outputs

Core Workflows

Workflow 1: Using References

When agents need detailed information:

1. Agent reads SKILL.md and sees pointer to reference
2. Agent reads specific reference file (e.g., references/patterns.md)
3. Agent applies detailed guidance from reference
4. Reference stays loaded only while needed

Example:

User: "What are the common patterns for this?"
Agent: [Loads skill] → [Reads SKILL.md] → [Sees references/patterns.md mentioned]
       → [Reads references/patterns.md] → [Applies patterns]

Workflow 2: Using Examples

When agents need working code:

1. Agent reads SKILL.md and sees pointer to example
2. Agent reads example file (e.g., examples/working-example.sh)
3. Agent adapts example for user's use case
4. User can run example directly

Example:

User: "Show me how this works"
Agent: [Loads skill] → [Reads SKILL.md] → [Sees examples/working-example.sh]
       → [Reads example] → [Adapts for user] → [User runs script]

Workflow 3: Using Scripts

When validation or automation needed:

1. Agent reads SKILL.md and sees pointer to script
2. Agent executes script (without loading into context)
3. Script returns results
4. Agent uses results to continue

Example:

User: "Validate my configuration"
Agent: [Loads skill] → [Reads SKILL.md] → [Sees scripts/validate.sh]
       → [Executes script] → [Gets validation results] → [Reports to user]

Key benefit: Scripts can execute without consuming context.

Resource Organization

references/patterns.md

Purpose: Common patterns and anti-patterns
Size: ~2,500 words
When loaded: When agent needs pattern guidance

Contains:

• Pattern catalog
• When to use each pattern
• Implementation examples
• Anti-patterns to avoid

references/advanced.md

Purpose: Advanced techniques
Size: ~2,200 words
When loaded: When agent needs advanced guidance

Contains:

• Complex scenarios
• Performance optimization
• Edge case handling
• Integration strategies

examples/working-example.sh

Purpose: Runnable demonstration
Type: Bash script
When loaded: When agent needs code sample

Features:

• Complete working code
• Comments explaining each step
• Can be executed directly
• Demonstrates best practices

scripts/validate.sh

Purpose: Validation utility
Type: Bash script
When loaded: When validation needed (often just executed)

Features:

• Validates configuration or setup
• Returns clear success/failure
• Provides helpful error messages
• Executable without reading

Benefits of Complete Structure

Comprehensive Support

Users get:

• Conceptual understanding (SKILL.md)
• Detailed knowledge (references/)
• Working examples (examples/)
• Automation tools (scripts/)

Efficient Context Usage

Despite comprehensive content:

• Only SKILL.md loaded initially (~1,800 words)
• References loaded when needed (~4,700 words available)
• Examples loaded when needed (~200 words)
• Scripts executed without loading (~150 words)

Total: 6,850 words of content
Typical load: 1,800 words (73% efficiency)

Better Organization

Clear separation:

• SKILL.md: What and how (essentials)
• references/: Why and when (details)
• examples/: Show me (code)
• scripts/: Do it for me (automation)

Creating a Complete Skill

Step 1: Create Structure

mkdir -p my-skill/{references,examples,scripts}
touch my-skill/SKILL.md

Step 2: Write SKILL.md

Core content with pointers:

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

# My Skill

## Overview
[Purpose and key concepts]

## Core Workflows
[Essential procedures]

## Quick Reference
[Tables, commands]

## Additional Resources

### Reference Files
- **`references/patterns.md`** - Common patterns
- **`references/advanced.md`** - Advanced techniques

### Example Files
- **`examples/basic.sh`** - Simple example
- **`examples/advanced.sh`** - Complex example

### Utility Scripts
- **`scripts/validate.sh`** - Validate configuration
- **`scripts/test.sh`** - Run tests

Step 3: Create References

Detailed documentation:

touch my-skill/references/patterns.md
touch my-skill/references/advanced.md

Write comprehensive content (2,000-5,000 words each).

Step 4: Create Examples

Working code samples:

touch my-skill/examples/basic.sh
touch my-skill/examples/advanced.sh
chmod +x my-skill/examples/*.sh

Write complete, runnable examples.

Step 5: Create Scripts

Utility tools:

touch my-skill/scripts/validate.sh
touch my-skill/scripts/test.sh
chmod +x my-skill/scripts/*.sh

Write helpful automation scripts.

Step 6: Reference Everything

Ensure SKILL.md mentions all resources so agents know they exist.

When to Use Each Component

Use references/ when:

• Need detailed explanations
• Have comprehensive documentation
• Cover edge cases and troubleshooting
• Provide advanced techniques

Use examples/ when:

• Users need working code to copy
• Demonstrating complex configurations
• Showing real-world usage
• Teaching through code

Use scripts/ when:

• Same operation repeated frequently
• Need deterministic validation
• Want to avoid rewriting code
• Can automate complex tasks

Additional Resources

Reference Files

Detailed documentation in references/:

• references/patterns.md - Common patterns and anti-patterns
  Study this to see how to organize pattern documentation

• references/advanced.md - Advanced techniques and strategies
  Study this to see how to structure advanced content

Example Files

Working code in examples/:

• examples/working-example.sh - Complete demonstration script
  Study this to see how to write clear, runnable examples

Utility Scripts

Automation tools in scripts/:

• scripts/validate.sh - Validation utility
  Study this to see how to write helpful validation scripts

Summary

Complete structure offers maximum capability:

Components:

skill-name/
├── SKILL.md              (1,500-2,000 words - core)
├── references/           (2,000-5,000 words each - details)
│   ├── patterns.md
│   └── advanced.md
├── examples/             (working code - samples)
│   └── working-example.sh
└── scripts/              (utilities - automation)
    └── validate.sh

Use when:

• Need comprehensive support
• Have working examples to share
• Want automation utilities
• Building complex domain skill

Benefits:

• Users get everything they need
• Efficient context usage (progressive disclosure)
• Better organization and maintainability
• Reusable automation (scripts)

Tradeoffs:

• More effort to create
• More files to maintain
• Only needed for complex domains

For most skills, the standard structure (SKILL.md + references/) is sufficient. Use the complete structure only when examples and scripts provide clear value.