- name
SKILL.md
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add GanyuanRan/Aegis --skill recording-architecture-decisions -a cursor -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add GanyuanRan/Aegis --skill recording-architecture-decisions -a claude-code -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add GanyuanRan/Aegis --skill recording-architecture-decisions -a codex -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add GanyuanRan/Aegis --skill recording-architecture-decisions -a grok -ySend the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
Install this skill: https://github.com/GanyuanRan/Aegis/tree/HEAD/skills/recording-architecture-decisionsFrom the publisher
Record durable architecture decisions without losing the current-state baseline closure. An ADR records why a decision was made; a baseline records what the architecture is after that decision.
This skill is a lazy, task-specific workflow. It does not replace
verification-before-completion, does not grant completion authority, and does
not make authoritative GateDecision or PolicySnapshot outputs.
Before deciding or writing, read the smallest relevant excerpts from:
docs/adr/ADR-CREATION-GATE.mddocs/current/AEGIS_ADR_AUTO_BACKFILL.mdFor Aegis repository changes, use this repository's docs/adr/ and
docs/current/ authority order. For target projects with their own ADR system,
respect that project owner instead of duplicating the same decision into
docs/aegis/adr/.
Use this skill when the user asks to:
Do not use it for simple wording edits, ordinary README cleanup, tests-only coverage improvements, low-risk single-file changes, or bug fixes that only restore the existing baseline.
docs/adr/, docs/aegis/adr/, existing
ADR, or lighter record.When the chosen owner surface is a target project's docs/aegis/adr/, use the
shared workspace helper instead of ad-hoc file creation:
create -> <aegis-workspace-helper> new-adr --root <target-project-root> ...amend -> <aegis-workspace-helper> amend-adr --root <target-project-root> --path docs/aegis/adr/ADR-####-<slug>.md ...supersede -> <aegis-workspace-helper> supersede-adr --root <target-project-root> --path docs/aegis/adr/ADR-####-<slug>.md ...After helper-backed writeback, run:
<aegis-workspace-helper> check --root <target-project-root>The helper owns file shape, ADR numbering, supersession markers, and
INDEX.md coverage only. It does not decide architecture truth, whether the
ADR gate passed, or whether baseline sync is semantically sufficient.
If the ADR gate or owner-surface decision says skip, do not create or amend
ADR files just because the helper exists. An ADR signal in a design/plan is a
note for later completion, not an ADR file. Create/amend/supersede an ADR only
for an executed durable decision; if an existing ADR already covers the
decision surface, amend it instead of creating a sibling.
If the ADR action is create, amend, or supersede, baseline sync must be checked.
Baseline sync is required when the decision changes or confirms any of:
If no baseline writeback is made, state why the existing baseline remains valid. Never leave baseline sync implicit after create, amend, or supersede.
Aegis Visibility:
- Why executed-decision filtering, ADR gate, owner surface, or baseline sync matters now:
Decision Candidate:
- Summary:
- Evidence source:
ADR Gate:
- Hard to reverse: yes | no | unknown
- Surprising without context: yes | no | unknown
- Real trade-off: yes | no | unknown
Retro / Memory Filter:
- Classification: executed durable decision | unexecuted idea | process note
- Memory action: record | skip | lighter record
- Reason:
ADR Action:
- create | amend | supersede | skip
- Reason:
Owner Surface:
- Target:
- Existing ADR / baseline checked:
Baseline Sync:
- Required: yes | no | unknown
- Target:
- Action: create snapshot | update baseline | cite unchanged | blocked
- Reason:
Boundary:
- Advisory method-pack signal only; not completion authority.
docs/adr/ and
docs/aegis/adr/ without an explicit mirror relationship.Use when the user asks to create, write, update, amend, supersede, or evaluate an ADR, architecture decision record, durable architecture decision, decision log, or baseline sync after architecture-ch
---name: recording-architecture-decisionsdescription: Use when the user asks to create, write, update, amend, supersede, or evaluate an ADR, architecture decision…---# skills/recording-architecture-decisions/SKILL.mdOverview
Use when the user asks to create, write, update, amend, supersede, or evaluate an ADR, architecture decision record, durable architecture decision, decision log, or baseline sync after architecture-changing work.
FAQ
Download skills/recording-architecture-decisions/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
The publisher keeps it at https://github.com/GanyuanRan/Aegis.
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.