opencode-skill/skills/skill-creator/SKILL.md

name, description

name	description
skill-creator	Create new OpenCode skills with proper structure, SKILL.md format, and script templates. Use this skill when you need to create a new OpenCode skill.

Skill Creator

Guide and tools for creating new OpenCode skills.

Quick Start

python3 scripts/create_skill.py <skill-name> "<description>"

SKILL.md Format (Required)

Every skill must have a SKILL.md file with YAML frontmatter:

---
name: skill-name
description: Brief description. Use when user wants to [specific action].
---

# Skill Name

Brief explanation of what this skill does.

## Commands

| Command | Args | Description |
|---------|------|-------------|
| `command1` | `<arg>` | What it does |

## Options

| Option | Default | Range | Description |
|--------|---------|-------|-------------|
| `--option` | 100 | 1-1000 | What it does |

## Examples

```bash
python3 scripts/script.py command "arg" --option 50

Output Format

• Success: Result: filename [id]
• Error: Error: message (to stderr)

Notes

• Required environment variables
• Important constraints

## Frontmatter Rules

| Field | Required | Rules |
|-------|----------|-------|
| `name` | Yes | 1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens |
| `description` | Yes | 1-1024 chars, specific enough for agent to choose correctly |
| `license` | No | e.g., MIT |
| `compatibility` | No | e.g., opencode |
| `metadata` | No | String-to-string map |

## Directory Structure

skills/ └── skill-name/ ├── SKILL.md # Required: skill definition └── scripts/ ├── main_script.py # Executable script ├── .env.example # Required: env var template └── requirements.txt # Optional: Python deps

## Script Best Practices

### 1. Load Environment Variables

```python
def load_env():
    env_path = Path(__file__).parent / ".env"
    if env_path.exists():
        for line in env_path.read_text().splitlines():
            line = line.strip()
            if line and not line.startswith("#") and "=" in line:
                k, v = line.split("=", 1)
                os.environ.setdefault(k.strip(), v.strip().strip("\"'"))

load_env()
API_TOKEN = os.environ.get("API_TOKEN")

2. Handle API Responses (Binary + JSON)

APIs may return raw binary or JSON with base64. Handle both:

response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()

content_type = response.headers.get("Content-Type", "")

if "image/" in content_type or "application/octet-stream" in content_type:
    # Raw binary response
    data = response.content
else:
    # JSON with base64
    result = response.json()
    if isinstance(result, list) and len(result) > 0:
        image_data = result[0].get("data", "")
        if image_data.startswith("data:"):
            data = base64.b64decode(image_data.split(",", 1)[1])
        else:
            data = base64.b64decode(image_data)

3. Send Base64 (Plain, Not Data URI)

Some APIs expect plain base64, not data URI:

import base64

with open(image_path, "rb") as f:
    image_bytes = f.read()

# Plain base64 (no data: prefix)
b64_string = base64.b64encode(image_bytes).decode("utf-8")

4. Output Format

Follow OpenCode conventions:

# Success with ID
print(f"Result: {filename} [{timestamp}]")

# Error to stderr
print(f"Error: {message}", file=sys.stderr)
sys.exit(1)

5. CLI Arguments

Use argparse for clean CLI:

parser = argparse.ArgumentParser(description="What this does")
parser.add_argument("required_arg", help="Description")
parser.add_argument("--optional", type=int, default=100, help="Description")
args = parser.parse_args()

.env.example Template

# API credentials
# Get your token from https://service.com/account
#
# WARNING: Never commit actual credentials!

API_TOKEN=your_api_token_here

Installation Paths

Type	Path
Global	~/.config/opencode/skills/<name>/SKILL.md
Project	./.opencode/skills/<name>/SKILL.md

Common Issues

Issue	Solution
400 Bad Request	Check payload format - may need flat JSON, not nested
Skill not found	Verify path is skills/<name>/SKILL.md (plural "skills")
API token not loaded	Check .env is in same directory as script
Binary response fails	Check Content-Type header, handle raw bytes

Checklist for New Skills

• SKILL.md with required frontmatter (name, description)
• scripts/ directory with main script
• scripts/.env.example with placeholder credentials
• scripts/requirements.txt if external deps needed
• Script handles both binary and JSON responses
• Output follows format: Result: name [id]
• Errors go to stderr with sys.exit(1)