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.

---

Overview

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

Instead of loading every skill into the AI context at startup — which would consume ~80k tokens and cause compaction loops — the plugin uses a SkillPointer architecture: skills are organized into categories inside a hidden vault and only loaded into context on demand.

---

How It Works

The plugin operates in two phases:

1. Local deployment (startup)

When OpenCode starts, the plugin copies the pre-bundled skills from the npm package and runs the SkillPointer pipeline:

bundled-skills/ (npm package)
        │
        ▼
~/.config/opencode/skills/          ← OpenCode reads this
        │
        └── SkillPointer pipeline
              │
              ├─ risk-filter       → excludes skills by risk level or ID
              ├─ content-scanner   → quarantines skills with dangerous patterns
              ├─ vault-manager     → moves safe skills to the vault
              ├─ skill-patcher     → applies config-driven content patches
              └─ pointer-generator → writes ~35 lightweight pointer files

2. On-demand skill loading

Each pointer file tells the AI: "there are N skills for this category in the vault — use list_dir / view_file to retrieve them when needed." The full skill content is only injected into context when the AI actually needs it.

---

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
Folders in skills/	~1000	~35
Tokens at startup	~80,000	~255
Skills available	All injected upfront	On-demand via vault
Compaction loops	✗ frequent	✓ none

---

Installation

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

{
  "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

Once installed, all skills are available in three ways:

Explicit invocation via CLI:

opencode run /brainstorming help me plan a new feature
opencode run /refactor clean up this function

Slash commands in the OpenCode chat:

/brainstorming
/refactor
/document

Natural language — OpenCode picks the right skill automatically:

"Help me brainstorm ideas for a REST API design"
"Refactor this function to be more readable"

---

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: Node.js ≥ 20, TypeScript ≥ 5

# Install dependencies
npm install

# Build
npm run build

# 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:

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

License

MIT ©

GitAds Sponsored

Star History