# ADR-0006 — Agent skills are advisory; this repository's documentation is binding (/docs/maintain/adr/ADR-0006-agent-skills-are-advisory)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `AGENTS.md` §12

## Context [#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 [#decision]

1. **Use skills**: invoke any skill that fits, and name it. Process skills come before
   implementation skills.
2. **Precedence**: `AGENTS.md` and `content/docs/maintain/` are binding; skills are advisory; default behaviour
   comes last.
3. **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.
4. **Skills stop at the gate**: a workflow that ends in "implement" ends here at
   `Status: Proposed`.
5. **Report what was dropped**: when a rule cuts a skill short, say which skill, which step,
   and which rule.

## Options considered [#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 [#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 [#content-invariants]

None directly.

## Security considerations [#security-considerations]

Prevents skills from making security or privacy decisions, adding integrations or publishing on
the owner's behalf.

## Implementation notes [#implementation-notes]

- [x] `AGENTS.md` §12 holds the precedence and the "no skill authorises" table.
- Tests: not applicable (process only).

## Docs to update on implementation [#docs-to-update-on-implementation]

- [x] `content/docs/maintain/adr/index.mdx` — status.