Skills Collection

OpenCode Skills Collection

An OpenCode plugin that bundles and auto-syncs a universal collection of AI skills — delivered instantly, with zero network latency at startup.

---

Sponsor

---

Overview

OpenCode Skills Collection ships a pre-bundled snapshot of 2400+ universal skills for OpenCode.

Instead of registering every skill with OpenCode at startup — which would flood the model's available-skills list with thousands of entries — the plugin uses a SkillPointer architecture: skills are stored in a hidden vault organized by category, and only ~100 lightweight pointer skills are registered. At each model step OpenCode advertises the pointers (ID, name, description); the model loads a pointer via the skill tool, reads which vault skills match the task, then loads the chosen vault SKILL.md via read.

---

How It Works

The plugin operates in two phases:

1. Local deployment (startup)

When OpenCode starts, the plugin runs the SkillPointer pipeline synchronously before anything else. No hooks, tools, or commands are registered — the only side effect is files on disk:

bundled-skills/ (npm package) + skills_index.json
        │
        ▼ runSkillPointer()
        ├─ filterIndex       → drops skills matching excluded risk levels / IDs
        ├─ installSkillsToVault → copies kept skills into the vault by category,
        │                        removes vault entries no longer in the filtered index
        ├─ applySkillPatches → regex find/replace from skill-filter.jsonc on vault copies
        └─ generatePointers  → writes one <category>-category-pointer/SKILL.md per
                               category into the active skills dir, removes stale pointers
        │
        ├── ~/.config/opencode/skill-libraries/<category>/<skill>/SKILL.md  (vault, NOT registered)
        └── ~/.config/opencode/skills/<category>-category-pointer/SKILL.md  (registered by OpenCode)

Content scanning is NOT a runtime stage: dangerous skills are quarantined at CI time (sync-skills.yml) and never reach the npm package.

2. On-demand skill loading (at inference time)

1. OpenCode discovers pointer skills in ~/.config/opencode/skills/ and advertises ID + name + description to the model at each step (body stays out of context).
2. The model loads the matching pointer via the skill tool ({"id": "<category>-category-pointer"}); OpenCode injects the pointer body — the categorized skill list plus vault path.
3. The model reads the chosen vault file via read (skill-libraries/<category>/<skill>/SKILL.md) and follows it.

Vault skills are never registered with OpenCode directly, so they never appear in the advertised list.

---

Disk Layout

After the first startup, your ~/.config/opencode/ directory looks like this:

~/.config/opencode/
├── opencode.json
├── skill-filter.jsonc                ← optional: risk filter + patcher config
├── skills/                           ← pointer folders (active, read by OpenCode)
│   ├── backend-dev-category-pointer/
│   │   └── SKILL.md
│   └── ...
└── skill-libraries/                  ← vault with all raw skills
    ├── backend-dev/
    │   ├── laravel-expert/
    │   │   └── SKILL.md
    │   └── ...
    └── ...

---

Context Usage

	Without SkillPointer	With SkillPointer
Entries in skills/	~2450	~100 pointers
Skills advertised per step	~2450	~100
Full bodies in context	On explicit load	On explicit load
Vault skills loaded	n/a	Via read after pointer

---

Installation

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

{
  // OpenCode V2
  "plugins": [
    "opencode-skills-collection@latest"
  ]
}

For OpenCode V1 (>= 1.18.29), use the plugin key instead (older V1 releases expect a function entrypoint and cannot load this version):

{
  // OpenCode V1
  "plugin": [
    "opencode-skills-collection@latest"
  ]
}

That's it. OpenCode will automatically download the npm package on next startup via Bun — no manual npm install needed.

---

Usage

The plugin registers pointer skills, not commands. There is no /skill-name slash command and no opencode run /... syntax — slash commands live in commands/, this plugin only writes to skills/.

How a skill gets used (V2 runtime):

1. You describe the task in plain language (CLI opencode run "...", TUI chat, or session).
2. OpenCode advertises the ~100 pointer skills (ID + description) to the model.
3. The model loads the matching <category>-category-pointer via the skill tool, picks the vault skill from its list, reads skill-libraries/<category>/<skill>/SKILL.md via read, and follows it.

"Help me design a REST API"  →  model loads backend-dev-category-pointer  →  reads laravel-expert/SKILL.md

Skills without a description are never advertised; skills can opt out of the advertised list with metadata.opencode/autoinvoke: false but remain loadable by exact ID. The skill tool takes an exact, case-sensitive ID.

---

Skill Safety & Filtering

The plugin supports configurable risk-based filtering of skills. By default, all skills are loaded — filtering is opt-in.

Each skill in the index has a risk field with one of these levels:

Level	Description
none	No risk assessment
safe	Verified safe
critical	Contains sensitive operations
offensive	Contains offensive security tools (exploits, reverse shells, etc.)
unknown	Not yet classified

Configuration

Create a ~/.config/opencode/skill-filter.jsonc file:

{
  "excludedRiskLevels": ["offensive"],
  "excludedSkills": ["windows-privilege-escalation"]
}

• excludedRiskLevels: Array of risk levels to block entirely
• excludedSkills: Array of specific skill IDs to block

Blocked skills are excluded from both the vault and the generated pointers — they are never loaded into context.

Content Safety Scanner (CI)

Dangerous skills are automatically detected and removed at build time — before the npm package is published. The nightly sync workflow scans every SKILL.md for recursive loop patterns and strips matching skills from bundled-skills/ and skills_index.json, so they never reach end users.

Built-in patterns detect:

• Recursive skill invocation loops ("invoke skills before any response")
• Aggressive match thresholds ("even a 1% chance")
• Mandatory pre-response skill checks ("you must invoke the skill")

Skill Patcher

The plugin can modify skill content after installation via config-driven patches. This allows neutralizing problematic instructions without forking upstream skills.

Add patches in skill-filter.jsonc:

{
  "skillPatches": [
    {
      "skillId": "some-skill-name",
      "find": "regex-pattern-to-match",
      "replace": "replacement-text",
      "description": "Why this patch exists"
    }
  ]
}

Patches are applied in order, case-insensitive, and globally (all occurrences). Invalid regex patterns are skipped silently. Re-running the pipeline with the same patches is idempotent.

---

Development

Requirements: Bun ≥ 1.3

# Install dependencies
bun install

# Build
bun run build

# Test
bun test

# Output is in dist/

The plugin is written in TypeScript and compiled to ESNext with full type declarations. It targets ES2022 and uses ESM module resolution.

---

Contributing

Issues and pull requests are welcome at github.com/FrancoStino/opencode-skills-collection.

---

Beta Releases

Beta versions are published from the develop branch for testing before official releases.

Installing Beta Versions

To use the latest beta version, update your ~/.config/opencode/opencode.json:

{
  // OpenCode V2
  "plugins": [
    "opencode-skills-collection@beta"
  ]
}

For OpenCode V1 (>= 1.18.29):

{
  // OpenCode V1
  "plugin": [
    "opencode-skills-collection@beta"
  ]
}

License

MIT ©

Star History