Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/joshuadavidthomas--opencode-agent-skills/badge.svg)](/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

i

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)

  1. # opencode-agent-skills
  2. A dynamic skills plugin for OpenCode that provides tools for loading and using reusable AI agent skills.
  3. > [!NOTE]
  4. > 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.
  5. ## Features
  6. - **Dynamic skill discovery** - Automatically finds skills from project, user, and plugin directories
  7. - **Context injection** - Loads skill content directly into the conversation context
  8. - **Compaction resilient** - Skills survive context compaction in long sessions
  9. - **Claude Code compatible** - Works with existing Claude Code skills and plugins
  10. - **Optional Superpowers integration** - Drop-in support for the [Superpowers](https://github.com/obra/superpowers) workflow
  11. ## Requirements
  12. - [OpenCode](https://opencode.ai/) v1.0.110 or later
  13. ## Installation
  14. 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.
  15. Add to your OpenCode config (`~/.config/opencode/opencode.json`):
  16. ```json
  17. {
  18. "plugin": ["opencode-agent-skills"]
  19. }
  20. ```
  21. Restart OpenCode and you're ready to go.
  22. Optionally, pin to a specific version for stability:
  23. ```json
  24. {
  25. "plugin": ["opencode-agent-skills@0.7.0"]
  26. }
  27. ```
  28. OpenCode fetches unpinned plugins from npm on each startup; pinned versions are cached and require a manual version bump to update.
  29. ### Local Development
  30. If you want to customize or contribute:
  31. ```bash
  32. git clone https://github.com/joshuadavidthomas/opencode-agent-skills ~/.config/opencode/opencode-agent-skills
  33. mkdir -p ~/.config/opencode/plugin
  34. ln -sf ~/.config/opencode/opencode-agent-skills/src/plugin.ts ~/.config/opencode/plugin/skills.ts
  35. ```
  36. ## Usage
  37. This plugin provides 4 tools to OpenCode:
  38. | Tool | Description |
  39. |------|-------------|
  40. | `use_skill` | Load a skill's SKILL.md into context |
  41. | `read_skill_file` | Read supporting files from a skill directory |
  42. | `run_skill_script` | Execute scripts from a skill directory |
  43. | `get_available_skills` | Get available skills |
  44. ### Skill Discovery
  45. 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.
  46. 1. `.opencode/skills/` (project)
  47. 2. `.claude/skills/` (project, Claude compatibility)
  48. 3. `~/.config/opencode/skills/` (user)
  49. 4. `~/.claude/skills/` (user, Claude compatibility)
  50. 5. `~/.claude/plugins/cache/` (cached Claude plugins)
  51. 6. `~/.claude/plugins/marketplaces/` (installed Claude plugins)
  52. ### Writing Skills
  53. 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:
  54. ```markdown
  55. ---
  56. name: my-skill
  57. description: A brief description of what this skill does
  58. ---
  59. # My Skill
  60. Instructions for the AI agent...
  61. ```
  62. See the [Anthropic Agent Skills documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) for more details.
  63. ## Troubleshooting
  64. If Hugging Face downloads are blocked or slow from your network, point Transformers.js at a compatible mirror:
  65. ```bash
  66. HF_ENDPOINT=https://hf-mirror.com opencode
  67. ```
  68. ## Alternatives
  69. - OpenCode's built-in skills support - Native skill discovery and loading through the built-in `skill` tool
  70. - [superpowers](https://github.com/obra/superpowers) - A complete software development workflow built on composable skills
  71. - [skillz](https://github.com/intellectronica/skillz) - An MCP server that exposes skills as tools to any MCP client
  72. ## Contributing
  73. 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.
  74. Here's how to set up for development:
  75. ```bash
  76. git clone https://github.com/joshuadavidthomas/opencode-agent-skills
  77. cd opencode-agent-skills
  78. bun install
  79. ```
  80. Then symlink the plugin to your OpenCode config:
  81. ```bash
  82. mkdir -p ~/.config/opencode/plugin
  83. ln -sf "$(pwd)/src/plugin.ts" ~/.config/opencode/plugin/skills.ts
  84. ```
  85. ## How it works
  86. ### Synthetic Message Injection
  87. When you load a skill with `use_skill`, the content is injected into the conversation using OpenCode's SDK with two key flags:
  88. - `noReply: true` - The agent doesn't respond to the injection itself
  89. - `synthetic: true` - Marks the message as system-generated (hidden from UI, not counted as user input)
  90. This means skills become part of the persistent conversation context and remain available even as the session grows and OpenCode compacts older messages.
  91. ### Session Initialization
  92. 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.
  93. ### Automatic Skill Matching
  94. 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.
  95. This happens automatically - you don't need to remember skill names or explicitly request them.
  96. ### Superpowers Mode (optional)
  97. 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:
  98. - Installed as a Claude Code plugin (skills live under `.claude/plugins/…`)
  99. - Installed as the Superpowers OpenCode plugin (skills live under `.opencode/skills/…`)
  100. Once Superpowers is installed, enable superpowers mode via environment variable:
  101. ```bash
  102. OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE=true opencode
  103. ```
  104. Or export it in your shell profile for persistent use:
  105. ```bash
  106. export OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE=true
  107. ```
  108. The plugin will inject the full prompt when a session starts and a compact reminder after compaction.
  109. ### Compaction Resilience
  110. 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.
  111. ## License
  112. opencode-agent-skills is licensed under the MIT license. See the [`LICENSE`](LICENSE) file for more information.
  113. ---
  114. opencode-agent-skills is not built by, or affiliated with, the OpenCode team.
  115. OpenCode is ©2025 Anomaly.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.