OpenAgentsControl/.opencode/context/openagents-repo/guides/adding-skill-basics.md

Guide: Adding an OpenCode Skill (Basics)

Prerequisites: Load plugins/context/capabilities/events_skills.md first
Purpose: Create an OpenCode skill directory and SKILL.md file

Note: This is for OpenCode skills (internal system). For Claude Code Skills, see creating-skills.md.

---

Overview

Adding an OpenCode skill involves:

1. Creating skill directory structure
2. Creating SKILL.md file
3. Creating router script (optional)
4. Creating CLI implementation (optional)
5. Registering in registry (optional)
6. Testing

Time: ~10-15 minutes

---

Step 1: Create Skill Directory

Choose Skill Name

• kebab-case: task-management, brand-guidelines
• Descriptive: Clear indication of what skill provides
• Short: Max 3-4 words

Create Structure

mkdir -p .opencode/skills/{skill-name}/scripts

Standard structure:

.opencode/skills/{skill-name}/
├── SKILL.md              # Required: Main skill documentation
├── router.sh             # Optional: CLI router script
└── scripts/
    └── skill-cli.ts      # Optional: CLI tool implementation

---

Step 2: Create SKILL.md

Frontmatter

---
name: {skill-name}
description: Brief description of what the skill provides
---

# Skill Name

**Purpose**: What this skill helps users do

## What I do

- Feature 1
- Feature 2
- Feature 3

## How to use me

### Basic Commands

bash npx ts-node .opencode/skills/{skill-name}/scripts/skill-cli.ts command1

### Command Reference

| Command | Description |
|---------|-------------|
| `command1` | What command1 does |
| `command2` | What command2 does |

Claude Code Skills (Optional)

For Claude Code Skills (.claude/skills/), add extra frontmatter:

• allowed-tools - Tool restrictions
• context + agent - Run in forked subagent
• hooks - Lifecycle events
• user-invocable - Hide from slash menu

See creating-skills.md for Claude Code Skills details.

---

Step 3: Create Router Script (Optional)

For CLI-based skills:

#!/bin/bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

if [ $# -eq 0 ]; then
    echo "Usage: bash router.sh <command> [options]"
    exit 1
fi

COMMAND="$1"
shift

case "$COMMAND" in
    help|--help|-h)
        echo "{Skill Name} - Description"
        echo "Commands: command1, command2, help"
        ;;
    command1|command2)
        npx ts-node "$SCRIPT_DIR/scripts/skill-cli.ts" "$COMMAND" "$@"
        ;;
    *)
        echo "Unknown command: $COMMAND"
        exit 1
        ;;
esac

chmod +x .opencode/skills/{skill-name}/router.sh

---

Next Steps

• CLI Implementation → adding-skill-implementation.md
• Complete Example → adding-skill-example.md
• Claude Code Skills → creating-skills.md

---

Related

• creating-skills.md - Claude Code Skills (different system)
• adding-skill-implementation.md - CLI and registry
• adding-skill-example.md - Task-management example
• plugins/context/capabilities/events_skills.md - Skills Plugin