OpenCode Agent Skills Plugin

Skills are discovered from multiple locations in a specific priority order. The first skill found with a given name wins (no duplication or shadowing), allowing project-level skills to override user-level skills.

Discovery Priority Order:

1. .opencode/skills/ (project)
2. .claude/skills/ (project, Claude compatibility)
3. ~/.config/opencode/skills/ (user)
4. ~/.claude/skills/ (user, Claude compatibility)
5. ~/.claude/plugins/cache/ (cached Claude plugins)
6. ~/.claude/plugins/marketplaces/ (installed Claude plugins)

Synthetic Message Injection

When use_skill is called, content is injected using two flags:

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

This ensures skills remain in the persistent context even during session compaction.

Compaction Resilience

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

If you have the Superpowers workflow installed, you can enable Superpowers mode to receive the strict Superpowers prompt. The plugin automatically detects the using-superpowers skill.

Enable it by setting the OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE environment variable to true.

# Run once
OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE=true opencode

# Or export in your shell profile
export OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE=true

Each skill must be a directory containing a SKILL.md file with YAML frontmatter. The structure should follow the Anthropic Agent Skills Spec.

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

# My Skill

Instructions for the AI agent...

To customize or contribute to the plugin, clone the repository and symlink the source to your OpenCode plugin directory.

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

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

Add the plugin to your OpenCode configuration file located at ~/.config/opencode/opencode.json.

Note: OpenCode now has native support for agent skills. Only install this plugin if you require its specific features like automatic semantic skill matching, synthetic context injection, or Superpowers integration.

To pin a specific version for stability, use the @version syntax. Unpinned plugins are fetched from npm on every startup, while pinned versions are cached.

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

Or to pin a version:

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

When the plugin detects that new skills are relevant to a user's request (via embedding matching), it injects a hidden <skill-evaluation-required> block into the session context. This block guides the agent through a three-step internal process:

1. EVALUATE: Determine if the matched skills genuinely help with the request.
2. DECIDE: Choose which specific skills are actually needed.
3. ACTIVATE: Call use_skill("name") for each chosen skill.

Note for developers: This evaluation block is synthetic and invisible to the end-user. The agent is instructed not to announce its decision, but to simply activate the skills or proceed with the request.

The system discovers skills from multiple locations following a specific hierarchy. OpenCode skills take precedence over Claude skills at each level (project vs. user).

Discovery Order (First match wins):

1. .opencode/skills/ (Project - OpenCode)
2. .claude/skills/ (Project - Claude)
3. ~/.config/opencode/skills/ (User - OpenCode)
4. ~/.claude/skills/ (User - Claude)
5. ~/.claude/plugins/cache/ (Cached plugin skills)
6. ~/.claude/plugins/marketplaces/ (Installed plugins)

Skill Resolution: Skills can be resolved by their simple name (e.g., my-skill) or via a namespace prefix (e.g., project:my-skill or user:my-skill). The namespace prefix matches either the SkillLabel or the namespace defined in the skill's metadata.

If you are working in a restricted network environment, you can use the HF_ENDPOINT environment variable to point the underlying @huggingface/transformers library to a mirror instead of huggingface.co. Call applyHfEndpoint() to apply this configuration to the transformers remote host.

import { applyHfEndpoint } from "./embeddings";

// Ensure the environment variable is applied before loading models
applyHfEndpoint();

To enable the automatic injection of the using-superpowers skill content (which includes tool mappings and skill namespace priority instructions), set the OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE environment variable to true.

When enabled, the maybeInjectSuperpowersBootstrap function will attempt to inject a specialized system prompt into the session, provided that a skill named using-superpowers is discovered in the local skills directory.

export OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE=true

If Hugging Face downloads are blocked or slow on your network, you can point Transformers.js to a compatible mirror using the HF_ENDPOINT environment variable.

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

The plugin exposes the following 4 tools to OpenCode: