opencode-agent-skills
An OpenCode plugin that provides tools for using agent skills
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/joshuadavidthomas--opencode-agent-skills)HTML
<a href="/listings/joshuadavidthomas--opencode-agent-skills"><img src="/api/listings/joshuadavidthomas--opencode-agent-skills/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 180 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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](https://github.com/obra/superpowers) workflow
- ## Requirements
- - [OpenCode](https://opencode.ai/) 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`):
- ```json
- {
- "plugin": ["opencode-agent-skills"]
- }
- ```
- Restart OpenCode and you're ready to go.
- Optionally, pin to a specific version for stability:
- ```json
- {
- "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:
- ```bash
- 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.
- 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)
- ### Writing Skills
- Skills follow the [Anthropic Agent Skills Spec](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#skill-structure). Each skill is a directory containing a `SKILL.md` with YAML frontmatter:
- ```markdown
- ---
- 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) for more details.
- ## Troubleshooting
- If Hugging Face downloads are blocked or slow from your network, point Transformers.js at a compatible mirror:
- ```bash
- 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](https://github.com/obra/superpowers) - A complete software development workflow built on composable skills
- - [skillz](https://github.com/intellectronica/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:
- ```bash
- git clone https://github.com/joshuadavidthomas/opencode-agent-skills
- cd opencode-agent-skills
- bun install
- ```
- Then symlink the plugin to your OpenCode config:
- ```bash
- 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](https://github.com/obra/superpowers)). 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:
- ```bash
- OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE=true opencode
- ```
- Or export it in your shell profile for persistent use:
- ```bash
- 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`](LICENSE) file for more information.
- ---
- opencode-agent-skills is not built by, or affiliated with, the OpenCode team.
- OpenCode is ©2025 Anomaly.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.