ADR-0006 — Agent skills are advisory; this repository's documentation is binding
Use agent skills freely, but this repository's working agreement and documents are binding, and no skill grants a permission they withhold.
- Status: Approved
- Date: 2026-10-31
- Deciders: @puncoz
- Approved by: @puncoz
- Approved on: 2026-11-01
- Supersedes: —
- Superseded by: —
- Design documents:
AGENTS.md§12
Context
Contributors have a library of installed skills (brainstorming, debugging, planning, TDD, technical writing, security review, UI design…). Used, they make work consistent. But they are written for generic projects, and several carry process opinions that contradict this repository: a brainstorming skill that writes specs to its own folder and commits them, a planning skill that proceeds straight to implementation, skills that add dependencies or deploy freely.
Decision
- Use skills: invoke any skill that fits, and name it. Process skills come before implementation skills.
- Precedence:
AGENTS.mdandcontent/docs/maintain/are binding; skills are advisory; default behaviour comes last. - No skill grants a permission this repository withholds: code before approval, commits,
new dependencies or tooling, a different docs layout, what-comments, security or privacy
decisions,
NEXT_PUBLIC_variables or integrations, publishing (a production build, a deploy, a search-index write), and framework claims from recall. - Skills stop at the gate: a workflow that ends in "implement" ends here at
Status: Proposed. - Report what was dropped: when a rule cuts a skill short, say which skill, which step, and which rule.
Options considered
| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Skills advisory, repo docs binding | Method from skills, authority from the repo | Agents must reconcile the two | Chosen |
| B — Skills binding | Simple | Skills would bypass the ADR gate and commit rule | Rejected |
| C — No skills | No conflicts | Loses consistent method | Rejected |
Consequences
Positive
- Consistent method without giving up the gate.
Negative / accepted trade-offs
- Some skill steps are routinely dropped (spec folders, commits) and must be reported.
Content invariants
None directly.
Security considerations
Prevents skills from making security or privacy decisions, adding integrations or publishing on the owner's behalf.
Implementation notes
-
AGENTS.md§12 holds the precedence and the "no skill authorises" table. - Tests: not applicable (process only).
Docs to update on implementation
-
content/docs/maintain/adr/index.mdx— status.
ADR-0005 — Security and privacy are a standing practice
Security and privacy are part of every change: each ADR has a security section, and the owner decides every security and privacy question.
ADR-0007 — Tests are part of every change
Every change ships tests for its happy path and its obvious failure paths, and a bug fix starts with a test that fails for the bug's reason.