opencode-agent-skills-md

Table of Contents

• Description
• Features
• Installation
• Usage
• How it Works
• Examples
• Maintainer release flow
• Contributing
• License

Description

opencode-agent-skills-md is an OpenCode plugin that provides reusable agent skills. It discovers skills from project and user locations, loads skill content into the context window, and uses semantic ranking with fuzzy fallback to suggest relevant skills.

Features

• Standardized Skill Discovery: Finds skills from project and user locations, supporting both OpenCode and Claude skill directory layouts.
• Context Injection: Loads SKILL.md content directly into the context window as synthetic, non-reply messages.
• Semantic Ranking with Fuzzy Fallback: Uses keyword scoring as the primary signal with bag-of-words embeddings for semantic ranking, falling back to Levenshtein-based fuzzy matching when needed.
• Compaction Resilient: Re-injects the list of loaded skills after session compaction events to ensure they remain available in long-running sessions.
• Script Execution: Recursively finds and executes scripts (files with the executable bit set) within skill directories.
• Superpowers Mode: Optional integration to automatically bootstrap the using-superpowers workflow.
• Preference Layer: Hooks for annotating native tool definitions and system prompts with skill policy information.

Installation

From npm

npm install -g opencode-agent-skills-md

Then add the plugin to ~/.config/opencode/opencode.json:

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

To pin a specific version:

{
  "plugin": ["[email protected]"]
}

Restart OpenCode after updating the config.

Manual configuration

If you prefer not to install globally, add the plugin entry manually to ~/.config/opencode/opencode.json:

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

Restart OpenCode after updating the config.

Local development

git clone https://github.com/MetalbolicX/opencode-agent-skills-md
cd opencode-agent-skills-md
pnpm install
pnpm run typecheck
pnpm test

The plugin entrypoint is src/plugin.ts. To use the development build with OpenCode, run the included install script, which writes a tiny re-export shim into .opencode/plugins/skills.js:

pnpm run install-local

This is equivalent to:

mkdir -p .opencode/plugins
echo 'export { SkillsPlugin } from "./src/plugin.ts";' > .opencode/plugins/skills.js

You can verify the shim is in place with:

pnpm run status

Usage

Skill Discovery Order

The plugin discovers skills from these locations, in priority order (first match wins, preventing duplicates):

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/ (Claude plugin cache)
6. ~/.claude/plugins/marketplaces/ (Claude marketplace, via installed_plugins.json)

The first four are scanned in order; roots 5 and 6 are appended after the OpenCode/Claude skill roots, contributing additional skills but still respecting the first-match-wins rule.

Tools

Once loaded, use the tools directly from OpenCode:

| Tool | Description | |------|-------------| | skill | Load a skill's SKILL.md into context. | | read_skill_file | Read a file from a skill directory (e.g., references/rules.md). | | run_skill_script | Execute a script from a skill directory. The script must be executable (chmod +x). | | get_available_skills | List available skills, optionally filtered by an ad-hoc query string. |

Use as a CLI in any agent

oaskills exposes the same skill-access operations as a standalone CLI, usable from any agent harness that can invoke bash. Install once with npx (no global install required) or via npm install -g opencode-agent-skills-md. After install, oaskills is in your PATH.

Five skill-access commands (plugin management commands omitted):

| Command | Description | |---------|-------------| | oaskills list [--query <q>] [--keywords <k>] | List available skills, optionally filtered by query or keyword tags. | | oaskills show <skill> | Show a skill's SKILL.md content. | | oaskills read [--allow-script] <skill> <filename> | Read a file from a skill directory. Pass --allow-script to read an executable script (default: refused, redirects to run). | | oaskills run [--yes] <skill> <script> [args...] | Execute an executable script in a skill directory. --yes auto-approves risky-script prompts. | | oaskills search <query> | Free-text search across skill names, descriptions, and triggers. |

Flags:

• --allow-script (read only): Bypasses the executable-script guard so you can inspect script source.
• --yes (run only): Skips the interactive risk-gate approval for scripts that contain network-egress or privilege-escalation patterns.
• --directory <d>: Sets the working directory for skill discovery (defaults to cwd).
• --timeout <ms> (run only): Script timeout in milliseconds (default: 30000).

Any-agent compatibility:

Works under Claude Code, Codex, Pi Agent, Cursor, and any harness that can invoke bash subprocesses. The CLI uses the same shared core (src/skill-ops/) as the OpenCode plugin — behavior is identical across both surfaces.

Example usage from any agent:

# List skills matching "git"
oaskills list --query git

# Read a skill file
oaskills read my-skill references/rules.md

# Run a skill script (auto-approve safe scripts, prompt for risky ones)
oaskills run my-skill scripts/build.sh -- --dry-run

# Run with --yes to skip risk prompts
oaskills run --yes my-skill scripts/deploy.sh

Superpowers Integration

If you have the Superpowers skill installed, you can automatically inject its bootstrap prompt on session start:

export OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE=true
opencode

How it Works

1. Session Initialization: On the first message, a complete list of discovered skills is injected into the context via <available-skills>.
2. Semantic Evaluation: For subsequent messages, user text is semantically ranked against skill names, descriptions, and triggers. The top 5 most relevant skills trigger a hidden <skill-evaluation-required> block prompting the agent to invoke skill if appropriate.
3. Synthetic Injection: Tool outputs are injected using synthetic: true and noReply: true, meaning they do not count as user messages and remain quietly in the context window.
4. Script Safety: File reads (read_skill_file) strictly prevent path traversal outside the skill's root directory. Scripts (run_skill_script) skip common heavy directories like node_modules and .git and only execute files with the executable bit set.

Examples

Load a skill into context:

skill("brainstorming")

Read a supporting file from a skill:

read_skill_file("brainstorming", "references/transformation-rules.md")

Run a script from a skill directory:

run_skill_script("my-skill", "scripts/build.sh", ["--dry-run"])

List matching skills:

get_available_skills({ query: "refactor" })

Maintainer release flow

1. Ensure Node.js >=20 is active
2. pnpm install
3. pnpm run typecheck
4. pnpm test
5. npm pack --dry-run (from the package directory to inspect contents)
6. npm publish --access public (from the package directory, not the workspace root)
7. git tag v1.4.0 && git push origin v1.4.0 (only after publish succeeds)

Contributing

Contributions are welcome. The codebase uses TypeScript.

Please run the following before opening a pull request:

pnpm run typecheck
pnpm test

License

MIT. See the LICENSE file for details.