opencode-agent-skills

opencode-agent-skills

A dynamic skills plugin for OpenCode that provides tools for loading and using reusable AI agent skills.

[!NOTE] OpenCode now includes first-party support for agent skills, including native skill discovery and a built-in skill tool. For most users, this plugin is no longer necessary. It remains available in maintenance mode for users who depend on its extra behavior, such as automatic semantic skill matching, synthetic context injection, compaction reinjection, Superpowers bootstrapping, and helper tools for reading skill files or running skill scripts.

Features

• Dynamic skill discovery - Automatically finds skills from project, user, and plugin directories
• Context injection - Loads skill content directly into the conversation context
• Compaction resilient - Skills survive context compaction in long sessions
• Claude Code compatible - Works with existing Claude Code skills and plugins
• Optional Superpowers integration - Drop-in support for the Superpowers workflow

Requirements

• OpenCode v1.0.110 or later

Installation

If you only need standard skill loading, prefer OpenCode's built-in skills support. Install this plugin only if you need one of its additional behaviors.

Add to your OpenCode config (~/.config/opencode/opencode.json):

{
  "plugin": ["opencode-agent-skills"]
}

Restart OpenCode and you're ready to go.

Optionally, pin to a specific version for stability:

{
  "plugin": ["opencode-agent-skills@0.7.0"]
}

OpenCode fetches unpinned plugins from npm on each startup; pinned versions are cached and require a manual version bump to update.

Local Development

If you want to customize or contribute:

git clone https://github.com/joshuadavidthomas/opencode-agent-skills ~/.config/opencode/opencode-agent-skills
mkdir -p ~/.config/opencode/plugin
ln -sf ~/.config/opencode/opencode-agent-skills/src/plugin.ts ~/.config/opencode/plugin/skills.ts

Usage

This plugin provides 4 tools to OpenCode:

Tool	Description
use_skill	Load a skill's SKILL.md into context
read_skill_file	Read supporting files from a skill directory
run_skill_script	Execute scripts from a skill directory
get_available_skills	Get available skills

Skill Discovery

Skills are discovered from multiple locations in priority order. The first skill found with a given name wins -- there is no duplication or shadowing. This allows project-level skills to override user-level skills of the same name.

• .opencode/skills/ (project)
• .claude/skills/ (project, Claude compatibility)
• ~/.config/opencode/skills/ (user)
• ~/.claude/skills/ (user, Claude compatibility)
• ~/.claude/plugins/cache/ (cached Claude plugins)
• ~/.claude/plugins/marketplaces/ (installed Claude plugins)

Writing Skills

Skills follow the Anthropic Agent Skills Spec. Each skill is a directory containing a SKILL.md with YAML frontmatter:

---
name: my-skill
description: A brief description of what this skill does
---

# My Skill

Instructions for the AI agent...

See the Anthropic Agent Skills documentation for more details.

Troubleshooting

If Hugging Face downloads are blocked or slow from your network, point Transformers.js at a compatible mirror:

HF_ENDPOINT=https://hf-mirror.com opencode

Alternatives

• OpenCode's built-in skills support - Native skill discovery and loading through the built-in skill tool
• superpowers - A complete software development workflow built on composable skills
• skillz - An MCP server that exposes skills as tools to any MCP client

Contributing

This project is in maintenance mode. Bug fixes and small, clean improvements are welcome, but new features should generally be weighed against OpenCode's native skills support first.

Here's how to set up for development:

git clone https://github.com/joshuadavidthomas/opencode-agent-skills
cd opencode-agent-skills
bun install

Then symlink the plugin to your OpenCode config:

mkdir -p ~/.config/opencode/plugin
ln -sf "$(pwd)/src/plugin.ts" ~/.config/opencode/plugin/skills.ts

How it works

Synthetic Message Injection

When you load a skill with use_skill, the content is injected into the conversation using OpenCode's SDK with two key flags:

• noReply: true - The agent doesn't respond to the injection itself
• synthetic: true - Marks the message as system-generated (hidden from UI, not counted as user input)

This means skills become part of the persistent conversation context and remain available even as the session grows and OpenCode compacts older messages.

Session Initialization

On session start, the plugin automatically injects a list of all discovered skills wrapped in <available-skills> tags. This allows the agent to know what skills are available without needing to call get_available_skills first.

Automatic Skill Matching

After the initial skills list is injected, the plugin monitors subsequent messages and uses semantic similarity to detect when a message relates to an available skill. When matches are found, it injects a prompt encouraging the agent to evaluate and load the relevant skills.

This happens automatically - you don't need to remember skill names or explicitly request them.

Superpowers Mode (optional)

To get the strict Superpowers prompt, install the real Superpowers project (follow their instructions). We automatically pick up the using-superpowers skill from either of its supported homes:

• Installed as a Claude Code plugin (skills live under .claude/plugins/…)
• Installed as the Superpowers OpenCode plugin (skills live under .opencode/skills/…)

Once Superpowers is installed, enable superpowers mode via environment variable:

OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE=true opencode

Or export it in your shell profile for persistent use:

export OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE=true

The plugin will inject the full prompt when a session starts and a compact reminder after compaction.

Compaction Resilience

The plugin listens for session.compacted events and re-injects the available skills list. This ensures the agent maintains access to skills throughout long sessions.

License

opencode-agent-skills is licensed under the MIT license. See the LICENSE file for more information.

opencode-agent-skills is not built by, or affiliated with, the OpenCode team.

OpenCode is ©2025 Anomaly.