git:20260422.f716430 to git:20260812.7c6fef6

19 added, 133 removed. Audit A to A.

- # Agent Instructions — Editing Skills

- ## Two kinds of skills

- **Integration skills** document how to use a specific external tool or API — non-obvious flags, auth gotchas, silent failure modes. They may (and should) name the tool, show CLI commands, and reference binary names directly. They declare `provides` in metadata.

- **Workflow skills** describe how to carry out a process. They are tool-agnostic by design: they declare `requires` in metadata and reference only capability names in their body — never tool names, binary names, CLI flags, or other skill names.

- **CLI providers** — when a tool has comprehensive `--help`, map the capability to `cli://<binary>` in `capabilities.yaml` instead of writing a wrapper skill. Only write an integration skill when there are genuine gotchas that help text won't surface.

- **When using any CLI capability, read `--help` first.** Run `<binary> --help` and `<binary> <subcommand> --help` before issuing commands. Integration skills document only what help text won't tell you — silent failures, wrong-output traps, and non-obvious cross-command dependencies. Everything else is in `--help`.

- **For short gotchas (1-3 sentences), use the `notes` field in `capabilities.yaml` instead of a skill file.** The manifest supports an extended map form:

- ```yaml

- # flat form — no gotchas

- issues: cli://linear

- # extended form — with notes

- calendar:

- provider: cli://ical

- notes: "Timestamps in JSON output are UTC — always convert to local before displaying."

- ```

- Use a skill file when the guidance needs examples, command references, or spans more than a few sentences. Use `notes` for single silent-failure facts.

- ## The mechanism: `requires` + manifest

- The manifest (`~/.agents/capabilities.yaml`) is the registry. It maps capability names to providers — a skill name, `cli://<binary>`, or `mcp://<server>`.

- Workflow skills declare what they need:

- ```yaml

- metadata:

- requires:

- - code-review

- - issues

- - ci

- ```

- `requires` is a YAML list of capability names — **no colons, no defaults**.

- `provides` is optional author metadata for discoverability. The manifest is authoritative, not skill frontmatter.

- ## Capability naming

- Capability names must be **provider-agnostic** — they name the domain, not the tool.

- | Good (domain) | Bad (tool-specific) |

- |---|---|

- | `code-review` | `pull-requests`, `github-prs` |

- | `issues` | `linear-issues`, `jira` |

- | `calendar` | `ical`, `gcal` |

- | `chat` | `slack` |

- | `ci` | `github-actions` |

- If the name would only make sense with one specific tool, it's wrong.

- ## Coupling violations

- A **coupling violation** is any reference in a workflow skill body (or its included sub-files) to:

- - A CLI binary name: `gh`, `git`, `linear`, `sqlite3`, `opencode`, `jq`, `curl`, etc.

- - A specific skill name: `` `load the slack skill` ``, `` `the architecture skill` ``

- - An MCP tool name: `context7`, `webfetch` (when used as a named tool, not a concept)

- - A platform-specific term as a noun: "pull request", "PR" (use "merge request" or "code review request")

- **These are always violations in workflow skill bodies**, regardless of how reasonable they seem in context.

- **These are never violations** in integration skill bodies or their sub-files — that's exactly where tool-specific content belongs.

- ### Examples

- | Violation | Fix |

- |---|---|

- | `` `gh pr view`, `gh pr diff` `` | `use your \`code-review\` capability` |

- | `gh api graphql -f query='...'` | `use your \`code-review\` capability` |

- | `load the \`plan\` skill` | `use your \`plan\` capability` |

- | `the \`architecture\` skill Section 2` | `the \`architecture\` capability Section 2` |

- | `via \`gq\`` | remove — capability reference is sufficient |

- | `` `gh repo view --json visibility` `` | `use your \`code-review\` capability` |

- | `context7` (in workflow body) | `your documentation lookup capability` |

- | "PR", "pull request" (in workflow body) | "merge request" or "code review request" |

- ## Adding a skill

- 1. Determine: integration or workflow?

- 2. If workflow:

- - Add `requires` listing the capabilities it needs

- - In the body, reference only capability names — never tools, binaries, or other skills

- - Name capabilities after domains, not tools

- - Add a manifest entry in `dot_agents/capabilities.yaml` if the capability isn't already mapped

- 3. If integration:

- - Add `provides` listing the capability name(s) this skill implements

- - Tool-specific content is expected and correct here

- 4. Run `agentskills validate` on the skill directory

- ## Editing an existing skill

- **Before adding any content to a workflow skill**, scan the section you're editing for existing violations and fix them. Do not add new content that would introduce a violation.

- After editing, re-read the full body of the skill and ask: "If this skill were used with a different tool provider, would this line still make sense?" If not, it's a violation.

- ## Sub-files

- Sub-files (`.md` files referenced from a SKILL.md) inherit the type of their parent skill. A sub-file of a workflow skill is also a workflow skill and must follow the same rules. A sub-file of an integration skill may contain tool-specific content.

- ## Skill shape — lessons from the orchestrator failure

- A previous "process" skill declared ten required capabilities and an eight-phase workflow. Measured across 69 sessions: TDD compliance fell from 34% to 9%, and architecture capability loading fell from 26% to 7%, **when the orchestrator was loaded vs. not**. The orchestrator actively suppressed the capabilities it wrapped.

+ # Editing skills

- The rules below are the generalized lessons — follow them when creating or editing any skill.

+ ## Is it even a skill?

- ### One skill = one trigger = one moment of action

+ A skill fires at a **specific, named moment**. Guidance that applies to every session of some kind belongs in an always-loaded instructions file instead — if you catch yourself writing "this should fire on every code change", it isn't a skill.

- A skill should fire at a specific, concrete moment. If you find yourself writing "Phase 1… Phase 2… Phase 3…" or "After step N, also do X," you are building an orchestrator. Split instead.

+ "This orchestrates several other skills" → you're building a phase graph; split it.

- Signs a skill is becoming an orchestrator:

- - A single skill covers multiple distinct moments in a workflow (e.g., "plan" that also governs commit-time behavior)

- - `provides` lists more than one capability whose triggers fire at different times

- - Step N of the skill says "do this other thing from a different capability"

+ ## What earns a line

- Split rule: **split by when the skill fires, not by what topic it covers.** Two skills that both cover "git stuff" but fire at different moments (commit-time vs. push-time) are correctly separate. One skill that covers "commit and format conventions" is correctly one skill because both fire at commit-time.

+ **Would a strong model behave worse without this line?** If no, cut it.

- ### Agents read long phase graphs as menus

+ Keep: exact CLI invocations and flags, file paths, auth setup, silent failure modes, wrong-output traps, numeric caps, org conventions, hard-won gotchas. Cut: anything `<binary> --help` says, generic engineering advice, restated model knowledge, and rationale for a rule the reader already accepted.

- A long workflow skill is not read as imperatives — it is read as a list the agent skim-selects from. The action phases (implement, commit, push) get executed; the deliberative phases (plan, verify, capture) get skipped. This is why the process skill suppressed TDD — TDD was mentioned inside a phase list, not as a standing imperative.

+ Fragments over sentences. Tables and bullets over paragraphs. A bulleted list of 5-sentence paragraphs is not brevity.

- Corollary: short, standalone skills with concrete triggers outperform long skills with phase graphs, even when the long skill formally `requires` the same capabilities.

+ ## Shape

- ### Indirection beyond one hop is not followed

+ - **One skill, one trigger, one moment.** Split by *when* it fires, not what topic it covers. Commit-time and push-time are correctly separate; "commit and format conventions" is correctly one skill.

+ - **The description is the trigger** — the only thing seen before deciding to load. State the situation, not the topic.

+ - **Under ~80 lines.**

+ - **Imperative steps, not phase graphs.** A long workflow skill gets read as a menu to skim-select from: action phases get executed, deliberative ones get skipped. When a skill must cover several paths, use a decision tree (here's the question, here's where to go), not "Phase 1… Phase 2…".

+ - **Indirection beyond one hop is not followed** — measured at ~4% load for referenced sub-files. Keep the concrete action in the skill that fires. A program too long to inline belongs in `$PATH` as a script, not in a sub-file.

- Measured: sub-files referenced from a parent skill were loaded in 4% of sessions that loaded the parent. A skill body that says "read this other file and follow the instructions there" or "load your X capability and then load your Y capability" will lose ~90% of the intended behavior at each hop. Keep the concrete action in the skill that fires, not one hop away.

+ ## Public repo

- ### Skills that work share a shape

+ Never hard-code values configured per-workspace: template names, project names, team keys, channel names, account IDs, internal URLs. Teach the agent to *discover* them — show the query, command, or config file that surfaces each user's own. True public constants of a tool (documented endpoints, stable command names) are fine.

- Skills measured with high adoption (commit 57%, push similar) all have:

- - A clear, concrete trigger (a specific moment, not a general topic)

- - Imperative steps, not descriptive phases

- - <80 lines in the main body

- - No chained `requires` that the agent must load additional skills to satisfy the described behavior

+ For remote APIs, document request and response *shape* — endpoints, body structure, response field paths, gotchas. Not code that calls them.

- ### Measure before refactoring a skill

+ ## Before you commit

- If a skill feels wrong, query the session DB at `~/.local/share/opencode/opencode.db` for actual loading and capability-use patterns before redesigning. Designing skill ontologies in the abstract reproduces the orchestrator failure.

+ Run `agentskills validate` on the skill directory.