opc-skills/README.md

opc-skills

Small shell utility for toggling opencode skills between a curated "active" set and a full "parked" catalog. Keeps ~/.config/opencode/skills/ small and intentional while preserving the full skill library offline.

This is deliberately a quick, standalone tool — it is not a general AI persona manager. For agent / skill / persona management across multiple AI platforms (Claude Code, opencode, Gemini, Paperclip, ...), see the personas repo.

Install

ln -s ~/Documents/opc-skills/bin/opc-skills ~/.local/bin/opc-skills

Ensure ~/.local/bin is on your PATH.

Layout it expects

~/Documents/opencode-skills-parked/   # full catalog — untracked data dir
  <skill-name>/SKILL.md
  INDEX.json
  INDEX.md
~/.config/opencode/skills/            # only currently-enabled skills
  <skill-name>/SKILL.md

Override via env:

• OPC_PARKED — parked catalog root (default ~/Documents/opencode-skills-parked)
• OPC_ACTIVE — active skills root (default ~/.config/opencode/skills)

Commands

opc-skills status                     # counts of active vs parked
opc-skills list {active|parked|all}   # skill folder names
opc-skills categories                 # prefix-based category counts
opc-skills enable <folder>            # copy parked → active
opc-skills disable <folder>           # remove from active (parked preserved)
opc-skills enable-category <prefix>   # fzf multi-pick within a prefix
opc-skills pick                       # fzf: category → multi-select → enable
opc-skills search [query]             # fzf fuzzy over name+description
opc-skills reindex                    # rebuild INDEX.json / INDEX.md

fzf is required for the interactive commands.

Shared reference files

Some skills reference sibling files via ../<name>.md (e.g. the 20 Feynman research skills use ../_platform-mapping.md for cross-platform tool mapping). opc-skills enable auto-syncs any such files from PARKED → ACTIVE so the relative references keep resolving.

Currently synced:

• _platform-mapping.md — Feynman-skills cross-platform subagent/scheduling/persistence mapping

If you add new shared-reference files at the PARKED root, extend sync_shared_refs() in bin/opc-skills.

Known interaction

The personas repo's build.py --install opencode currently wipes and repopulates ~/.config/opencode/skills/ as part of installation, which destroys the active set curated here. Use opc-skills after any personas install, or skip the skills half of build.py installs.

build.py --install opencode and build.py --install claude-skills both emit _platform-mapping.md at the skills-root alongside the 20 Feynman skills (deep-research, literature-review, paper-code-audit, peer-review, paper-writing, replication, source-comparison, summarize, alpha-research, eli5, autoresearch, docker, modal-compute, runpod-compute, session-log, session-search, jobs, watch, preview, contributing).