# Skill Templates

Copy-paste templates for common skill patterns. Use these as starting points when creating new skills.

## Table of Contents

1. [Simple Skill (Knowledge Only)](#simple-skill)
2. [Tool Integration Skill](#tool-integration-skill)
3. [Workflow Skill](#workflow-skill)
4. [Documentation Skill](#documentation-skill)
5. [Testing Your Skill](#testing-your-skill)

---

## Simple Skill

For skills that provide knowledge without scripts or complex resources.

**Use when:** The skill provides guidance, best practices, or reference information that can be explained in text.

### Directory Structure

```
simple-skill/
└── SKILL.md
```

### SKILL.md Template

```markdown
---
name: simple-skill
description: This skill should be used when the user asks to "TRIGGER_PHRASE_1", "TRIGGER_PHRASE_2", or needs help with SPECIFIC_TASK
license: MIT
compatibility: opencode
metadata:
  category: CATEGORY
  version: "1.0.0"
---

# Simple Skill Name

Brief description of what this skill covers.

## Overview

High-level explanation of the domain or topic.

## Common Tasks

### Task 1: Description

Step-by-step instructions:

1. First step with code example
2. Second step with code example
3. Third step

### Task 2: Description

Step-by-step instructions:

1. First step
2. Second step

## Best Practices

- Bullet point 1
- Bullet point 2
- Bullet point 3

## Important Notes

- Critical caveat 1
- Critical caveat 2
```

### Example: Git Commit Guidelines

```markdown
---
name: git-commit-guide
description: This skill should be used when the user asks to "write a commit message", "format a commit", "conventional commits", or needs help with Git commit standards
license: MIT
compatibility: opencode
---

# Git Commit Guidelines

Follow conventional commits specification for clear, structured commit messages.

## Format

```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

## Types

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style (formatting, semicolons, etc)
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks

## Examples

```bash
# Feature
feat(auth): add OAuth2 login support

# Fix with scope
fix(api): resolve null pointer in user endpoint

# Breaking change
feat(db)!: migrate to PostgreSQL
```

## Rules

- Use imperative mood: "add" not "added"
- Don't capitalize first letter
- No period at end
- Keep first line under 72 characters
```

---

## Tool Integration Skill

For skills that interact with command-line tools and include automation scripts.

**Use when:** The skill wraps a CLI tool, provides automation, or requires executable scripts.

### Directory Structure

```
tool-skill/
├── SKILL.md
├── scripts/
│   └── helper.sh
├── references/
│   └── advanced-usage.md
└── evals/
    └── evals.json
```

### SKILL.md Template

```markdown
---
name: tool-skill
description: This skill should be used when the user asks to "TRIGGER_PHRASE_1", "run TOOL_NAME", "TOOL_NAME commands", or work with TOOL_NAME
license: MIT
compatibility: opencode
metadata:
  category: tools
  version: "1.0.0"
---

# Tool Name Integration

Interact with TOOL_NAME for SPECIFIC_PURPOSE.

## Quick Start

Basic usage:

```bash
tool-name --option value
```

## Common Operations

### Operation 1: Description

```bash
# Example command
tool-name command --flag
```

Explanation of what this does.

### Operation 2: Description

```bash
# Example command
tool-name another-command
```

## Scripts

Use helper scripts in `scripts/`:

- `scripts/helper.sh` - What this script does

## Advanced Usage

For detailed options and edge cases, see `references/advanced-usage.md`.

## Important Notes

- Requirement 1
- Requirement 2
- Common pitfall
```

### scripts/helper.sh Template

```bash
#!/bin/bash
#
# Helper script for TOOL_NAME operations
#

set -euo pipefail

# Configuration
DEFAULT_OPTION="value"

# Functions
show_help() {
    cat << EOF
Usage: $0 [OPTIONS]

Helper script for TOOL_NAME

Options:
    -h, --help      Show this help message
    -v, --verbose   Enable verbose output
    -o, --option    Specify option value

Examples:
    $0 --verbose
    $0 --option custom-value
EOF
}

# Parse arguments
VERBOSE=false
OPTION="$DEFAULT_OPTION"

while [[ $# -gt 0 ]]; do
    case $1 in
        -h|--help)
            show_help
            exit 0
            ;;
        -v|--verbose)
            VERBOSE=true
            shift
            ;;
        -o|--option)
            OPTION="$2"
            shift 2
            ;;
        *)
            echo "Unknown option: $1"
            show_help
            exit 1
            ;;
    esac
done

# Main logic
main() {
    [[ "$VERBOSE" == true ]] && echo "Running with option: $OPTION"
    
    # Your tool integration logic here
    echo "Helper script executed successfully"
}

main "$@"
```

### Example: Docker Helper

```markdown
---
name: docker-helper
description: This skill should be used when the user asks to "manage docker containers", "build docker images", "docker compose operations", or work with Docker workflows
license: MIT
compatibility: opencode
---

# Docker Helper

Streamline Docker container and image management.

## Quick Commands

### List Running Containers

```bash
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
```

### Clean Up System

```bash
# Remove stopped containers, unused networks, dangling images
docker system prune -f
```

## Scripts

Use helper scripts:

- `scripts/container-logs.sh` - View and follow container logs
- `scripts/cleanup.sh` - Safe cleanup of unused resources

## Docker Compose

### Start Services

```bash
docker compose up -d SERVICE_NAME
```

### View Logs

```bash
docker compose logs -f SERVICE_NAME
```

## References

- `references/compose-patterns.md` - Advanced compose configurations
- `references/troubleshooting.md` - Common issues and solutions
```

---

## Workflow Skill

For skills that guide multi-step processes or complex procedures.

**Use when:** The skill orchestrates a sequence of steps, decisions, or collaborative tasks.

### Directory Structure

```
workflow-skill/
├── SKILL.md
├── scripts/
│   ├── step-validator.sh
│   └── automation.sh
├── references/
│   ├── decision-matrix.md
│   └── examples/
│       └── sample-workflow.md
└── evals/
    └── evals.json
```

### SKILL.md Template

```markdown
---
name: workflow-skill
description: This skill should be used when the user asks to "WORKFLOW_NAME", "perform WORKFLOW_TASK", "WORKFLOW_VERB process", or needs help with WORKFLOW_DOMAIN
license: MIT
compatibility: opencode
metadata:
  category: workflow
  version: "1.0.0"
---

# Workflow Name

Guide the WORKFLOW_PROCESS from start to finish with validation at each step.

## Prerequisites

Before starting, ensure:

1. Requirement 1
2. Requirement 2
3. Requirement 3

## Workflow Overview

```
Step 1 → Step 2 → Step 3 → Completion
   ↓         ↓         ↓
Validate  Validate  Validate
```

## Step-by-Step Process

### Step 1: Preparation

**Objective:** What to accomplish in this step

**Actions:**
1. Action item 1
2. Action item 2

**Validation:**
- [ ] Check item 1
- [ ] Check item 2

**Script:** `scripts/step-validator.sh --step 1`

### Step 2: Execution

**Objective:** What to accomplish in this step

**Actions:**
1. Action item 1
2. Action item 2

**Validation:**
- [ ] Check item 1
- [ ] Check item 2

**Decision Point:**

If CONDITION_A:
- Follow path A (see `references/path-a.md`)

If CONDITION_B:
- Follow path B (see `references/path-b.md`)

### Step 3: Verification

**Objective:** Final checks and completion

**Actions:**
1. Run verification command
2. Review output

**Validation:**
- [ ] All checks pass
- [ ] No errors in logs

## Automation

For automated execution:

```bash
scripts/automation.sh --full
```

## Troubleshooting

See `references/troubleshooting.md` for common issues.

## Examples

Complete workflow examples in `references/examples/`.
```

### Example: Release Workflow

```markdown
---
name: release-workflow
description: This skill should be used when the user asks to "create a release", "publish a new version", "tag a release", or prepare software for deployment
license: MIT
compatibility: opencode
---

# Release Workflow

Guide the complete release process from version bump to deployment.

## Prerequisites

- [ ] All tests passing
- [ ] CHANGELOG.md updated
- [ ] Version number decided

## Workflow

### Step 1: Pre-Release Checks

**Actions:**
1. Run full test suite: `npm test`
2. Verify CHANGELOG.md is current
3. Check for uncommitted changes

**Validation:**
```bash
scripts/pre-release-check.sh
```

### Step 2: Version Bump

**Actions:**
1. Update version in package.json
2. Update CHANGELOG.md with release date
3. Commit with message: `chore(release): bump version to X.Y.Z`

**Validation:**
- [ ] Version updated in all files
- [ ] CHANGELOG.md has date
- [ ] Commit created

### Step 3: Create Tag

**Actions:**
1. Create annotated tag: `git tag -a vX.Y.Z -m "Release X.Y.Z"`
2. Push tag: `git push origin vX.Y.Z`

**Validation:**
```bash
scripts/verify-tag.sh vX.Y.Z
```

### Step 4: GitHub Release

**Actions:**
1. Draft release notes from CHANGELOG
2. Create GitHub release
3. Attach artifacts if needed

**Command:**
```bash
gh release create vX.Y.Z --notes-from-tag
```

## Decision Matrix

See `references/decision-matrix.md` for:
- Version numbering (semver vs calver)
- Pre-release vs stable
- Hotfix procedures
```

---

## Documentation Skill

For skills focused on writing, reviewing, or managing documentation.

**Use when:** The skill helps create documentation, enforces standards, or provides writing guidelines.

### Directory Structure

```
docs-skill/
├── SKILL.md
├── references/
│   ├── style-guide.md
│   ├── templates/
│   │   ├── README-template.md
│   │   └── API-doc-template.md
│   └── examples/
│       └── sample-docs/
├── assets/
│   └── diagram-template.png
└── evals/
    └── evals.json
```

### SKILL.md Template

```markdown
---
name: docs-skill
description: This skill should be used when the user asks to "write documentation", "create a README", "document this code", "review docs", or needs help with technical writing
license: MIT
compatibility: opencode
metadata:
  category: documentation
  version: "1.0.0"
---

# Documentation Helper

Create clear, consistent, and effective technical documentation.

## Quick Start

### Create README

Start with the template:

```bash
cp references/templates/README-template.md ./README.md
```

Then fill in:
1. Project name and description
2. Installation steps
3. Usage examples
4. API reference (if applicable)

## Documentation Types

### README.md

Essential sections:
- Title and description
- Installation
- Quick start
- Usage examples
- API reference (if applicable)
- Contributing
- License

Use template: `references/templates/README-template.md`

### API Documentation

Structure:
- Endpoint description
- Request format
- Response format
- Error codes
- Examples

Use template: `references/templates/API-doc-template.md`

### Code Comments

Follow style guide in `references/style-guide.md`:
- JSDoc for JavaScript
- Docstrings for Python
- Rustdoc for Rust

## Style Guide

See `references/style-guide.md` for:
- Tone and voice
- Formatting rules
- Terminology
- Code example standards

## Review Checklist

Before finalizing documentation:

- [ ] Clear and concise
- [ ] No typos or grammar errors
- [ ] Code examples work
- [ ] All links functional
- [ ] Proper heading hierarchy
- [ ] Consistent formatting

## Examples

Review well-documented projects in `references/examples/`.

## Assets

- `assets/diagram-template.png` - Template for architecture diagrams
```

### Example: API Documentation Helper

```markdown
---
name: api-docs-helper
description: This skill should be used when the user asks to "document an API", "create API documentation", "write endpoint docs", or needs help with REST API documentation
license: MIT
compatibility: opencode
---

# API Documentation Helper

Create comprehensive REST API documentation following OpenAPI standards.

## Endpoint Documentation Template

For each endpoint, document:

### 1. Overview

```markdown
## POST /api/v1/resource

Brief description of what this endpoint does.

**Authorization:** Required (Bearer token)
**Rate Limit:** 100 requests/minute
```

### 2. Request

```markdown
### Headers

| Header | Value | Required |
|--------|-------|----------|
| Content-Type | application/json | Yes |
| Authorization | Bearer {token} | Yes |

### Body

```json
{
  "field1": "string (required) - Description",
  "field2": "number (optional) - Description"
}
```
```

### 3. Response

```markdown
### Success (200 OK)

```json
{
  "id": "string",
  "created_at": "ISO 8601 datetime",
  "status": "active"
}
```

### Error Responses

- `400 Bad Request` - Invalid input
- `401 Unauthorized` - Missing/invalid token
- `404 Not Found` - Resource doesn't exist
```

### 4. Examples

Provide curl and client library examples.

## Standards

Follow conventions in `references/api-standards.md`:
- Use JSON for request/response bodies
- ISO 8601 for dates
- snake_case for field names
- Include pagination metadata for lists

## Tools

Validate documentation:
- `scripts/validate-openapi.sh` - Check OpenAPI spec
- `scripts/check-examples.sh` - Verify code examples work
```

---

## Testing Your Skill

After creating a skill from these templates, follow this testing workflow:

### Step 1: Create Test Cases

Generate test cases for your skill:

```bash
~/.config/opencode/skills/skill-builder/scripts/create-tests.sh ~/.config/opencode/skills/your-skill
```

This creates `evals/evals.json` with 3 template test cases:
1. **Common Case** - Typical usage scenario
2. **Edge Case** - Tricky or unusual situation  
3. **Varied Phrasing** - Same intent, different words

### Step 2: Customize Test Prompts

Edit `evals/evals.json` and replace placeholder text with realistic test prompts:

**Good test prompt:**
```
Convert the CSV file at ./data/sales.csv to JSON and save it as ./output/sales.json. 
The CSV has headers: date, product, quantity, price. Make sure dates are in ISO 8601 format.
```

**Bad test prompt:**
```
Convert CSV to JSON
```

See `eval-templates.md` for copy-paste templates for different skill types.

### Step 3: Run Tests

Execute the test workflow:

```bash
~/.config/opencode/skills/skill-builder/scripts/run-tests.sh ~/.config/opencode/skills/your-skill
```

This will:
- Display each test prompt
- Guide you through manual testing in opencode
- Record your evaluations (pass/fail/skip)
- Save results to `evals/test-results.json`

### Step 4: Grade Results

Use the grading checklist for systematic evaluation:

```bash
~/.config/opencode/skills/skill-builder/scripts/grade-output.sh ~/.config/opencode/skills/your-skill
```

This evaluates:
- Correctness
- Completeness
- Format
- Triggering
- Efficiency

And generates `evals/grading-report.json` with structured feedback.

### Step 5: Iterate

Based on test results, improve your skill:

1. Review issues in grading report
2. Update SKILL.md with fixes
3. Re-run tests
4. Repeat until satisfied

See `grading-guide.md` for detailed evaluation criteria and decision frameworks.

### Testing by Skill Type

**Simple Skills:**
- May not need formal test cases
- Test manually with 2-3 realistic prompts
- Verify outputs are helpful and accurate

**Tool Integration Skills:**
- Must test all commands work when copied
- Verify edge cases (errors, conflicts)
- Test with different tool versions if possible

**Workflow Skills:**
- Test complete end-to-end flow
- Verify each step produces correct result
- Test decision points and branches
- Check error recovery paths

**Code Generation Skills:**
- Verify generated code is syntactically valid
- Test that code actually runs
- Check edge cases (empty input, large data)
- Validate error handling

### When to Stop Testing

Stop iterating when:
- All critical test cases pass
- User is satisfied with quality
- Common scenarios work reliably
- No longer making meaningful improvements

Remember: A skill that works well for 90% of cases is sufficient. Perfection is the enemy of good.

---

## Tips for All Templates

1. **Replace placeholders immediately** - Search for `TRIGGER_PHRASE`, `TOOL_NAME`, etc.

2. **Write description first** - Include 3-5 specific trigger phrases in quotes

3. **Keep examples working** - Test all code examples before finalizing

4. **Validate early and often** - Run validation after every significant change

5. **Progressive disclosure** - Move details to references/ as the skill grows

6. **Be specific** - Generic skills don't trigger well. Make descriptions concrete.

7. **Test triggers** - After creating, try phrases from your description to verify activation

## Validation Checklist for New Skills

Before considering a skill complete:

- [ ] SKILL.md created with proper frontmatter
- [ ] `name` matches directory name
- [ ] `description` is 20-1024 characters with trigger phrases
- [ ] No second-person writing in body
- [ ] All scripts are executable
- [ ] Referenced files exist and are mentioned in SKILL.md
- [ ] Validation passes: `validate-skill.sh /path/to/skill`
- [ ] Test cases created in `evals/evals.json`
- [ ] Tests pass or issues documented
- [ ] Tested with actual trigger phrases