git:20260917.8ba9a4d to git:20260917.57c416a

24 added, 16 removed. Audit A to A.

# AGENTS.md

- Collection of Markdown skills (`skills/<name>/SKILL.md`). Ship Markdown only — no package manager, build, or test suite. `.opencode/agents/` is optional OpenCode; it is not the skills install contract.

+ Collection of Markdown skills (`skills/<name>/SKILL.md`). Ship Markdown only: no package manager, build, or test suite. `.opencode/agents/` is optional OpenCode; it is not the skills install contract.

## Commands

- - Lint changed Markdown: `markdownlint -c .markdownlint.yaml <path>` (exit 0). Config: `.markdownlint.yaml`.

- - MD013 is off (`.markdownlint.yaml`, `.editorconfig` `[*.md]`). One-line prose, list items, and table cells. Break on a heading, new list item, blank line, or fence. If MD013 fires, fix the config.

+ - Lint one changed Markdown file: `markdownlint -c .markdownlint.yaml <path>` (exit 0)

- ## Permission boundaries

+ ## Conventions

- | Mode | Paths |

- | ---------------- | ----------------------------------------------------------------------------------------------------------------------- |

- | WRITE | `skills/**`, `docs/**`, `README.md`, `AGENTS.md`, `CHANGELOG.md`, `.editorconfig`, `.markdownlint.yaml`, `.opencode/**` |

- | NEVER | force-push, rewriting git history |

- | HUMAN_CHECKPOINT | publishing or removing a skill from the public registry; deleting a skill directory |

+ MD013 is off (`.markdownlint.yaml`, `.editorconfig` `[*.md]`). One-line prose, list items, and table cells. Break on a heading, new list item, blank line, or fence. If MD013 fires, fix the config.

+ ## Boundaries

+ | Mode | Paths |

+ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |

+ | WRITE | `skills/**`, `docs/**`, `README.md`, `AGENTS.md`, `CHANGELOG.md`, `global-rules.md`, `.editorconfig`, `.markdownlint.yaml`, `.opencode/**` |

+ | NEVER | force-push or rewrite git history (both rewrite shared history) |

+ | HUMAN_CHECKPOINT | publishing or removing a skill from the public registry; deleting a skill directory |

## Precedence

1. Explicit user instruction for this turn

2. This `AGENTS.md`

3. The `SKILL.md` / `references/` of the skill being edited

- 4. Generic Markdown style guides — keep MD013 off

+ 4. Generic Markdown style guides: keep MD013 off

## Changelog

- `CHANGELOG.md` is for consumers of a skill, an OpenCode agent, or `global-rules.md`. Record those changes under `[Unreleased]` (Keep a Changelog sections as needed). Skip `AGENTS.md` and other contributor-only repo policy.

+ `CHANGELOG.md` is for consumers of a skill, an OpenCode agent, or `global-rules.md`. Keep a Changelog sections as needed. Leave `[Unreleased]` until the user asks to cut a version. A new skill may set an initial `metadata.version`. Do not invent a changelog version to match a skill bump.

- Leave `[Unreleased]` in place until the user asks to cut a version. Leave `skills/<name>/SKILL.md` `metadata.version` unchanged while work sits in `[Unreleased]`. A new skill may set an initial `metadata.version`; bump it only on the next cut. The user may bump `metadata.version` before a changelog cut. When the user asks to cut a version, for each skill with entries in that release: compare the current `metadata.version` to that skill's frontmatter at the last dated `CHANGELOG.md` heading. If it is already newer, leave it. If it still matches the last-cut value, bump it once in the same change (one bump per skill per cut). Do not invent a changelog version to match a skill bump. No version arrow on Unreleased bullets.

+ | Change | `[Unreleased]` | `metadata.version` |

+ | ------------------------------------------------------------------- | -------------- | ------------------ |

+ | Skill, OpenCode agent, or `global-rules.md` | bullet | leave |

+ | `AGENTS.md` or other contributor-only policy | skip | leave |

+ | User asked to cut; skill still at last dated `CHANGELOG.md` heading | dated heading | bump once |

+ | User asked to cut; skill already newer | dated heading | leave |

CORRECT (skill edit): `[Unreleased]` gains a bullet; `metadata.version` in `SKILL.md` stays put.

WRONG: Unreleased bullet with `0.1.0 → 0.2.0`; frontmatter bumped in the same skill edit.

WRONG: Unreleased bullet for an `AGENTS.md` rewrite.

CORRECT (cut): skill still at last-cut `0.1.0` → bump once. Skill already at `0.2.0` (user bump) → leave `0.2.0`.

- ## Skills

+ ## Structure

- Each skill lives in `skills/<name>/` with `SKILL.md` (frontmatter `name` and `description`; `disable-model-invocation: true` only for user-invoked-only). Keep `SKILL.md` thin; depth goes in `references/` or `reference/`. Ship `agents/openai.yaml` for ChatGPT/Codex ([optional metadata](https://learn.chatgpt.com/docs/build-skills#optional-metadata)): `interface.display_name`, `interface.short_description` (25–64 characters), `policy.allow_implicit_invocation: false` when `disable-model-invocation: true`, otherwise `true`. Add MCP `dependencies` only when the skill needs a named server.

+ New skill: `skills/<name>/SKILL.md` (frontmatter `name` and `description`) plus `agents/openai.yaml`. Keep `SKILL.md` thin; depth goes in `references/` or `reference/`. Copy `skills/write-great-instructions/SKILL.md` and `skills/write-great-instructions/agents/openai.yaml`. User-invoked only: copy `skills/code-review-plus/SKILL.md` (`disable-model-invocation: true`) and `skills/code-review-plus/agents/openai.yaml` (`allow_implicit_invocation: false`). `interface.short_description` is 25–64 characters. ChatGPT picker fields: [optional metadata](https://learn.chatgpt.com/docs/build-skills#optional-metadata) when writing `agents/openai.yaml`. MCP `dependencies` only when the skill names a server.

- Add or remove a skill: update the table in `README.md` and the tree in `docs/structure.md` in the same change, plus `[Unreleased]`.

+ Add or remove a skill: `README.md` table and `docs/structure.md` tree in the same change, plus `[Unreleased]`.

Ambiguous skill behaviour or scope: stop and ask. Do not invent a second skill or a build toolchain.

## Done when

- 1. Each changed `.md` path: the Commands lint exits 0

+ 1. Each changed `.md` path: `markdownlint -c .markdownlint.yaml <path>` exits 0

2. Diff has no reflow-only edits; long instructional lines stay on one line

3. Skill add/remove: `README.md` table and `docs/structure.md` tree updated in the same change

4. Consumer-facing change (skill, OpenCode agent, `global-rules.md`): `[Unreleased]` records it; `metadata.version` unchanged unless this change is a version cut, and then only skills still at the last-cut value. `AGENTS.md`-only: no changelog bullet