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

Inspection

opc-skills status                     # counts of active vs parked
opc-skills list {active|parked|all}   # skill folder names
opc-skills categories                 # verb-prefix counts (performing, detecting, ...)
opc-skills domains                    # frontmatter `domain:` distribution
opc-skills subdomains                 # frontmatter `subdomain:` distribution
opc-skills tags                       # frontmatter `tags:` distribution

Single-skill operations

opc-skills enable  <folder>           # copy parked → active
opc-skills disable <folder>           # remove from active (parked preserved)
opc-skills disable-all [-y|--yes]     # disable every active skill

Bulk by axis

opc-skills enable-category   <prefix>      # fzf multi-pick within a verb-prefix
opc-skills disable-category  <prefix>
opc-skills enable-domain     <domain>      # bulk by frontmatter domain (eg. cybersecurity)
opc-skills disable-domain    <domain>
opc-skills enable-subdomain  <subdomain>   # bulk by subdomain (eg. malware-analysis)
opc-skills disable-subdomain <subdomain>
opc-skills enable-tag  [--all] <tag>...    # bulk by tags (default: any; --all: intersection)
opc-skills disable-tag [--all] <tag>...

Interactive / search

opc-skills pick                       # fzf: category → multi-select → enable
opc-skills disable-pick               # fzf: ACTIVE category → multi-select → disable
opc-skills search [query]             # fzf fuzzy over name+description
opc-skills disable-search [query]     # fzf over ACTIVE only
opc-skills reindex                    # rebuild INDEX.json / INDEX.md

fzf is required for the interactive commands; jq for the bulk-by-axis commands; python3 (with optional PyYAML) for reindex.

INDEX schema

reindex parses each SKILL.md frontmatter and emits records with: folder, name, description, domain, subdomain, tags[], status. enable / disable perform an incremental status update on INDEX.json so enable-domain / disable-tag etc. stay accurate without a full reindex.

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).