How do I install the Mcaf Adr Writing skill?

Run npx skillmds add majiayu000/mcaf-adr-writing in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Mcaf Adr Writing safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Mcaf Adr Writing?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Mcaf Adr Writing free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Mcaf Adr Writing?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Mcaf Adr Writing by majiayu000 — Agent Skill

Name: Mcaf Adr Writing
Rating: 4.2 (5 reviews)
Author: majiayu000

Mcaf Adr Writing

Create or update an ADR (Architecture Decision Record) under `docs/ADR/` using `docs/templates/ADR-Template.md`: context, decision, alternatives, consequences, rollout, and verification. Use when changing architecture, boundaries, dependencies, data model, or cross-cutting patterns; ensure it is self-contained, has a Mermaid diagram, and defines testable invariants.

majiayu000 8b69bb8 2 files · 3.3 KB Updated Sep 9, 2026 567 repo stars

File contents

MCAF: ADR Writing

Outputs

docs/ADR/ADR-XXXX-<short-title>.md (create or update)
Update docs/Architecture/Overview.md when boundaries/interactions change

Decision Quality (anti-guesswork checklist)

Before writing, make the ADR executable (no placeholders, no hand-waving):

Decision: one sentence. If you can’t write it, you don’t have a decision yet.
Scope: what changes / what does not + which module(s) are affected (match docs/Architecture/Overview.md names).
No invented reality: every component you mention exists in the repo today, or is explicitly part of this change (named + where it will live).
Invariants: write as MUST / MUST NOT statements and say how we prove each (test or static analysis).
Verification: use exact commands from AGENTS.md and link scenarios → test IDs.
Stakeholders: Product / Dev / DevOps / QA — what each role must know to execute safely.

Workflow

Confirm the decision scope:
- what changes (and what does not)
- what module(s) are affected
- follow AGENTS.md scoping rules: Architecture map → linked ADR/Feature → entry points (do not scan everything)
Start from docs/templates/ADR-Template.md.
- keep the ADR’s ## Implementation plan (step-by-step) updated while executing
Write the ADR as a decision record:
- Context: constraints + why this is needed now
- Decision: a short, direct statement
- Diagram (mandatory): include at least one Mermaid diagram for the decision (boundaries/modules/interactions)
- Alternatives: 1–3 realistic options with pros/cons
- Consequences: trade-offs, risks, mitigations
Make it executable for the team:
- follow AGENTS.md Task Delivery rules (analysis → plan → execute → verify)
- include the invariants that must be proven by tests
- include verification commands copied from AGENTS.md
- include rollout/rollback and “how we know it’s safe”
Make impacts explicit:
- code/modules affected
- data/config changes (including migration/rollback)
- backwards compatibility strategy
Add verification that proves the decision:
- which tests must exist/change
- which suites must stay green
If the decision changes boundaries, update docs/Architecture/Overview.md (diagram, modules table, dependency rules).

Guardrails

ADRs are self-contained: no hidden context, no “as discussed”.
ADRs justify why; feature docs describe what the system does.
If you can’t state the decision in 1–2 sentences, the ADR is not ready.

---name: mcaf-adr-writingdescription: Create or update an ADR (Architecture Decision Record) under `docs/ADR/` using `docs/templates/ADR-Template.md`: context, decision, alternatives, consequences, rollout, and verification. Use when changing architecture, boundaries, dependencies, data model, or cross-cutting patterns; ensure it is self-contained, has a Mermaid diagram, and defines testable invariants.--- # MCAF: ADR Writing ## Outputs - `docs/ADR/ADR-XXXX-<short-title>.md` (create or update) - Update `docs/Architecture/Overview.md` when boundaries/interactions change ## Decision Quality (anti-guesswork checklist) Before writing, make the ADR executable (no placeholders, no hand-waving): - **Decision**: one sentence. If you can’t write it, you don’t have a decision yet. - **Scope**: what changes / what does not + which module(s) are affected (match `docs/Architecture/Overview.md` names). - **No invented reality**: every component you mention exists in the repo today, or is explicitly part of this change (named + where it will live). - **Invariants**: write as **MUST / MUST NOT** statements and say how we prove each (test or static analysis). - **Verification**: use exact commands from `AGENTS.md` and link scenarios → test IDs. - **Stakeholders**: Product / Dev / DevOps / QA — what each role must know to execute safely. ## Workflow 1. Confirm the decision scope: - what changes (and what does not) - what module(s) are affected - follow `AGENTS.md` scoping rules: Architecture map → linked ADR/Feature → entry points (do not scan everything) 2. Start from `docs/templates/ADR-Template.md`. - keep the ADR’s `## Implementation plan (step-by-step)` updated while executing 3. Write the ADR as a decision record: - **Context**: constraints + why this is needed now - **Decision**: a short, direct statement - **Diagram** (mandatory): include at least one Mermaid diagram for the decision (boundaries/modules/interactions) - **Alternatives**: 1–3 realistic options with pros/cons - **Consequences**: trade-offs, risks, mitigations 4. Make it executable for the team: - follow `AGENTS.md` Task Delivery rules (analysis → plan → execute → verify) - include the invariants that must be proven by tests - include verification commands copied from `AGENTS.md` - include rollout/rollback and “how we know it’s safe” 5. Make impacts explicit: - code/modules affected - data/config changes (including migration/rollback) - backwards compatibility strategy 6. Add verification that proves the decision: - which tests must exist/change - which suites must stay green 7. If the decision changes boundaries, update `docs/Architecture/Overview.md` (diagram, modules table, dependency rules). ## Guardrails - ADRs are self-contained: no hidden context, no “as discussed”. - ADRs justify *why*; feature docs describe *what the system does*. - If you can’t state the decision in 1–2 sentences, the ADR is not ready.

Frequently asked questions