CivilTekk OpenCode & Claude Skills

A personal software-development skills collection — the agents, skills, and pipeline tooling I use daily — shared so you can take a single skill or adopt the whole stack.

• 84 ready-to-load skills + 34 specialist subagents, natively targeting OpenCode v2
• Same skills install to other harnesses: Claude Code, Kimi Code, Kilo Code, and the cross-tool ~/.agents/ standard (Agent Skills open format)
• A robust application-development pipeline: ticket → PLAN → gated execution → review → merged PR, driven by a handful of slash commands

v2.0.0 upgrade? See MIGRATION.md for breaking changes (stale agent cleanup, zip backup format, new --rollback / --no-zip-backup flags) and rollback instructions.

Daily-driver commands

These three commands carry most of my day-to-day flow. Slash commands ship with a full deploy — a single-skill npx add install gives you the skills (invoked by natural language), not the command bindings.

The first two compose: /create-ticket makes the ticket, /run-worktree-pipeline #NNN takes it to a merged PR.

One execution flavor — inline by default: /run-plan and /run-worktree-pipeline execute fully in-session — zero subagents end to end (plan review — architecture via the architecture-review-skill decision tree —, execution via plan-execution-inline-skill, code review via code-review-inline-skill, and the PR route via the civiltekk-pr-workflow-skill create route all run in-session; the only deployed agent definitions still loaded as checklists are the Step 7 uiux reviewer and the requirements relay). Subagent orchestration (plan-execution-skill --gate workers) is an explicit opt-in on OpenCode — request it and, if its deps are missing, the run proceeds inline with a note. Plan-mode sessions get read-only /worktree-pipeline-preview — the same pipeline walked in preview mode (no worktree, no commits, no pushes, no PRs, no file writes); real execution stays pinned to Build via the command above.

Installation

Five ways in, pick by appetite. All commands below work from any clone of this repo.

1. Take one skill (or agent) — the shadcn model

No clone needed; npx copies the skill directory into your config. See issue #304.

npx github:darellchua2/civiltekk-opencode-claude-skills add code-principles-skill   # one skill
npx github:darellchua2/civiltekk-opencode-claude-skills add tdd-subagent             # agent + its required skills
npx github:darellchua2/civiltekk-opencode-claude-skills                              # bare = interactive TUI catalog
npx github:darellchua2/civiltekk-opencode-claude-skills remove code-principles-skill

Versioning & rollback — add installs from the latest release tag by default, never an untagged moving tree. Every installed skill dir carries a .skill-source.json provenance stamp (source, ref, version, installedAt, files), and list installed shows what you have vs. the latest release:

npx github:darellchua2/civiltekk-opencode-claude-skills add                  # latest vX.Y.Z release
npx github:darellchua2/civiltekk-opencode-claude-skills#v12.18.0 add         # pinned — rollback = older tag
npx github:darellchua2/civiltekk-opencode-claude-skills --ref dev add       # unreleased dev tree
npx github:darellchua2/civiltekk-opencode-claude-skills list installed              # installed vs latest + update marker

Upgrade = re-run add (idempotent overwrite); downgrade = same with an older #vX.Y.Z. Installs carry an exact ref even when the fetched release’s own installer predates stamping — the current installer post-stamps provenance after the tagged install. (--source . installs from a local checkout for maintainers; in any git checkout of this repo add always installs that working tree — the latest-tag routing applies to npx installs, which have no .git.)

Other harnesses — skills follow the Agent Skills open standard; --target controls the destination:

--project installs into ./.opencode/ (agents, opencode.json, manifests — full-service config generation) with skills going to ./.agents/skills/ (Agent Skills standard dir natively discovered by OpenCode and pi) instead of user scope. --no-deps skips declared skill prerequisites.

The catalog is also consumable via the ecosystem CLI: npx skills add darellchua2/civiltekk-opencode-claude-skills (skills only — project default, -g for global; no dependency resolution or agent installs). This installer mirrors its ergonomics: -g, -y, -p, rm, list, and --target auto all work; two divergences are deliberate — user scope is the default (not project), and installs are per-target copies (not symlinks) because targets apply model/permission translations.

2. Full deploy — the whole stack

Copies config + agents + skills to ~/.config/opencode/ and installs four PATH commands (civiltekk-setup to re-run the deploy from anywhere, civiltekk-init for project-scoped installs; opencode-setup/opencode-init remain as compat symlinks for existing scripts).

civiltekk-setup                    # interactive — menu: 0 guided TUI wizard, or multi-pick: one base (1-3) + add-ons (5, 6), e.g. 2,6 or 3,5,6
civiltekk-setup --quick --yes      # non-interactive: config + skills, skip dependency checks
civiltekk-setup --from-plan plan.json   # execute a wizard-emitted install plan headlessly
# Windows: powershell -ExecutionPolicy Bypass -File .\deploy\setup.ps1 -Quick -Yes
# Windows cmd: deploy\setup.cmd -Quick -Yes   (forwards to setup.ps1)
# No clone? npx -p github:darellchua2/civiltekk-opencode-claude-skills civiltekk-setup --quick --yes

The guided TUI wizard (menu option 0, or deploy/tui.mjs install-wizard) walks mode → provider → MCP packs → skill profile with an OpenCode-style review screen showing the exact actions before anything runs (including each pack’s runtime install command); it emits an install-plan.json that --from-plan executes — the wizard only collects decisions, setup.sh’s plan executor is the single execution owner. The classic multi-pick menu stays as the --no-tui fallback (#673): one base mode (1 quick / 2 skills-only / 3 full) plus any add-ons (5 PeonPing, 6 per-item picker) — 2,6 or 3,5,6; 4 (CLI update) runs standalone. The same combos are first-class flags: --skills-only --select, --quick --peonping. Pack installs need a working Python (python3/python/py — the Windows Store python3 alias stub is detected and skipped over); setup prints a runtime-context banner (OS, invocation route, node/python versions) before it acts.

Provider swap (Z.AI default): ./deploy/setup.sh --provider anthropic|openai|openrouter|zai — agent models are tier-based and provider-agnostic (details in the collapsed reference below). Full flag table: ./deploy/setup.sh --help, or the collapsed reference at the end.

Multi-agent detection (#573): the deploy also probes which coding agents are installed (opencode, pi, codex, claude, kimi, kilo) and prints a found/missing table. With pi or codex present and a Z.AI key captured, it seeds a zai provider into ~/.pi/agent/models.json (apiKey via $ZAI_API_KEY interpolation — key never stored) and ~/.codex/config.toml (env_key; opt-in via codex --profile zai), then restarts the opencode background service so {env:} MCP substitution picks up the key — the fix for “the bashrc export never reached the MCP servers”.

3. Per-project subset — presets

Not every project needs 34 agents + 84 skills. civiltekk-init installs a curated preset into ./.opencode/ (clean-slate isolation; additive over a global deploy — it warns):

civiltekk-init --list categories                              # introspect (JSON)
civiltekk-init --expand review                                # preview the resolved set
civiltekk-init --project . --preset review --yes              # install
npx github:darellchua2/civiltekk-opencode-claude-skills --project . --preset review --yes   # no prior deploy needed

Directory structure

civiltekk-opencode-claude-skills/
├── skills/                      # 84 skill directories (source of truth)
├── agents/                      # 34 subagent .md files (source of truth)
├── plugins/                     # Local OpenCode plugins (vibeguard, ponytail, learnings, auto-continue, question-repair, location-keepalive, laya-guard)
│   └── vibeguard.config.json    # Secret-masking regex patterns
├── deploy/                      # User-space deployment (setup.sh = bins: civiltekk-setup (+opencode-setup compat); opencode.json = config source of truth)
├── installer/                   # npx installer (init.mjs = bin: opencode-skill; registry, tiers, presets)
├── tests/                       # bats test suite (guards counts, isolation, portability)
├── PLANS/                       # Execution plans per ticket (git-committed history)
├── LEARNINGS/                   # Knowledge-persistence skeleton (auto-provisioned in target projects)
├── CHANGELOG.md                 # Release history (semantic-release generated)
├── CONTRIBUTING.md              # Contribution guide (skill/agent authoring)
├── MIGRATION.md                 # v1.x → v2.0 migration guide
└── THIRD_PARTY_LICENSES.md      # Vendored-skill attributions (MIT/Apache-2.0)

skills/ and agents/ are the single source of truth — edit there, then redeploy. Never edit deployed ~/.config/opencode/ copies. Every skill directory is fully self-contained (the npx add copy model — enforced by tests/test_skill_isolation.bats).

Support & reporting issues

Both issue forms enforce a search-first attestation and structured fields — a complete report gets fixed faster:

• 🐞 Bug report — unexpected behavior or a broken feature
• 🚀 Feature request — new capability or enhancement

Blank issues are disabled; pick a template. Include your environment (OS, Node, opencode version, install method) for bugs.

Want to contribute a skill or agent? See CONTRIBUTING.md.

Prerequisites

• Node.js v20+ and npm (setup scripts can install Node for you; nvm recommended). The --select picker dashboard wants node ≥ 26.4 — below it the picker falls back to linear prompts; every other flow runs on 20+.
• An API key for your provider (Z.AI default; Anthropic/OpenAI/OpenRouter via --provider)
• GitHub CLI (gh) — recommended for ticket/PR flows (gh auth login)
• ripgrep (rg) — recommended, faster search; falls back to grep

---

Deep reference

Everything below is detail you rarely need at first install — expanded on demand.

Full setup reference

License

Apache-2.0 — see LICENSE. Vendored skills carry their own attributions in THIRD_PARTY_LICENSES.md.