| name | editing-skills |
| audience | swarm-plugin |
| description | Contract for adding, editing, moving, or removing skills in this repository (.claude/skills, .opencode/skills, .agents/skills, any SKILL.md): mirror classifications in src/config/skill-mirrors.ts, dual-tree byte-identical edits, bun run drift:check, bundling via BUNDLED_PROJECT_SKILLS, frontmatter conventions, and how to write trigger descriptions. Load before touching any SKILL.md file.
|
Editing Skills in opencode-swarm
Skills in this repo exist across parallel trees (.opencode/skills/,
.claude/skills/, .agents/skills/) governed by explicit mirror contracts.
Editing a SKILL.md without knowing its contract silently desynchronizes the
OpenCode and Claude Code surfaces. Classify first, then edit.
Step 1 — Classify the skill
Look the slug up in src/config/skill-mirrors.ts:
- MIRRORED_ARCHITECT_MODE_SKILLS (brainstorm, specify, clarify-spec,
swarm-resume, clarify, discover, consult, pre-phase-briefing, council, deep-dive,
deep-research, issue-ingest, plan, critic-gate, design-docs):
.opencode
and .claude copies must stay byte-identical.
Any edit is a dual-tree edit — apply the identical change to both files.
- ADAPTER (execute, phase-wrap, swarm-pr-review, swarm-pr-feedback,
swarm-pr-subscribe, swarm-ci-monitor):
.opencode is canonical; .claude
and .agents where present are thin shims that must keep the exact relative
reference ../../../.opencode/skills/<slug>/SKILL.md (drift-check verifies
the string). swarm-implement follows the same operational adapter pattern,
but is currently classified as an additional divergent contract because the
additional-contract registry does not yet model non-architect adapter shims.
- DIVERGENT: both trees exist, content intentionally differs — a
single-tree edit is fine.
codebase-review-swarm is in
DIVERGENT_ARCHITECT_MODE_SKILLS; engineering-conventions is a divergent
entry in ADDITIONAL_SKILL_MIRROR_CONTRACTS. swarm-implement and
writing-tests are classified divergent only because the additional-contract
model does not yet have an adapter kind; operationally, .opencode is
canonical and .claude delegates to it.
- OPENCODE-ONLY:
loop (OPENCODE_ONLY_ARCHITECT_MODE_SKILLS) and
running-tests (an opencode-only ADDITIONAL contract) — do not
create .claude mirrors (a .claude/skills/loop would shadow Claude
Code's built-in /loop).
- ADDITIONAL contracts:
commit-pr is divergent (#1692). The .claude
copy is the repo-INTERNAL publication protocol (CI's pr-standards workflow
declares it the source of truth); the .opencode copy is the PORTABLE,
project-agnostic version bundled into end-user projects, so the two trees
intentionally differ — do not sync them byte-for-byte. The discovery
shims in .agents/skills/commit-pr/ and .github/skills/commit-pr/ point
at the repo-internal .claude file as canonical.
- Adapter skills (issue-tracer):
.opencode/skills/<slug>/SKILL.md is the
canonical protocol; .claude/skills/<slug>/SKILL.md and .agents/skills/<slug>/SKILL.md
are thin shims that reference it via the relative path. See
src/config/skill-mirrors.ts for the kind: adapter contract.
- No skill-mirrors.ts entry (qa-sweep, research-first, swarm, unswarm,
tech-debt-ci-review, rust-crate-ci, orchestrating-subagents, durable-session-state,
editing-skills, …): the
.claude file is the source protocol and there is
no .opencode copy, no CI gate, and no npm shipment. But most are not
single-file: many have a Codex adapter shim in .agents/skills/<slug>/
that reads ".claude/skills/<slug>/SKILL.md is the source protocol"
(check ls .agents/skills/). Content edits to the .claude file are safe
— shims delegate — but renaming, moving, or removing one of these
skills silently orphans its .agents shim with zero drift-check coverage.
Update or remove the shim in the same change.
- Pre-flight for new skills (blocking): Before authoring any SKILL.md
content for a skill that should reach npm users, the slug MUST be registered
in all three places:
src/config/skill-mirrors.ts (classification),
src/config/bundled-skills.ts (BUNDLED_PROJECT_SKILLS), and
package.json#files. Creating content first and registering later is a
common source of drift-check failures and missing shipments.
Step 2 — Know what ships where
- Only canonical package sources under
.opencode/skills/ are published:
package.json#files lists the bundled source directories and
BUNDLED_PROJECT_SKILLS (src/config/bundled-skills.ts) drives a private
runtime sync to .swarm/bundled-skills/<slug>/ at plugin init. Never sync
into a target project's native skill roots.
.claude/skills/ is repo-internal — it configures Claude Code sessions in
this repository only.- A new skill that should reach npm users must be added to all three:
.opencode/skills/<slug>/, BUNDLED_PROJECT_SKILLS, and
package.json#files — the drift checker flags incomplete combinations.
- A new cross-tree pair (same slug in both trees) must be classified in
src/config/skill-mirrors.ts, or drift-check reports it "unclassified".
Step 3 — MODE skills are not triggered by descriptions
The mirrored architect skills carry descriptions like "Full execution
protocol for MODE: PLAN". These are loaded on demand by the architect stubs
in src/agents/architect.ts when a [MODE: …] signal fires — they are
not meant to match natural user language, and in a plain Claude Code
session (no swarm runtime tools) they are protocol documentation, not
executable workflows. Do not "fix" their descriptions to natural language,
and do not expect them to auto-trigger.
Step 4 — Frontmatter and description conventions
- Every tracked static skill declares
audience: swarm-plugin. Consumer repos
may instead use a domain tag such as ragappv3 and optionally add a runner
constraint (runner:opencode, runner:claude, or runner:codex). Keep
byte-identical mirrors' audience lines byte-identical. Runtime-generated
skills are intentionally allowed to omit the field (legacy match-all).
description is how Claude Code auto-selects skills: third person, the
core use case and concrete trigger keywords first, under ~1024 chars.
Vague descriptions ("helps with X") never trigger.disable-model-invocation: true for slash-command-style skills the model
must not self-invoke (swarm, unswarm, tech-debt-ci-review).- Supported optional fields used in this repo:
effort (low…max),
context: fork + agent: Explore|Plan|general-purpose|<custom> (runs the
skill body in an isolated subagent — the body then cannot rely on
conversation history or on spawning further subagents), allowed-tools
(space- or comma-separated), argument-hint.
- Keep SKILL.md under ~500 lines; move deep material into
references/
files linked one level from the SKILL.md (see issue-tracer for the
pattern).
Step 5 — Validate and publish
- If the edit changed content wording (not just whitespace/formatting), read
file:.swarm/bundled-skills/skill-edit-validation/SKILL.md and run its
content-assertion sweep to catch stale test assertions before proceeding.
bun run drift:check --enforce — CI runs the same enforcement mode; blocking
drift findings fail the job, while the full report is posted as a PR comment.- If you touched a byte-identical pair,
diff the two files to prove
identity.
- Skill-only diffs (no
src/, scripts/, or test changes) count as
docs/meta-only for PR gating — no release-notes fragment required. The
moment you also touch src/config/skill-mirrors.ts,
bundled-skills.ts, or package.json, a
docs/releases/pending/<slug>.md fragment becomes mandatory
(see commit-pr skill, Step 2).
- Skill edits are still "changed work" under the swarm-mode contract:
independent reviewer + critic gates apply before completion.
