How do I install the Adr Management skill?

Run npx skillmds@latest add richfrem/adr-management 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 Adr Management safe to use?

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

Which AI agents work with Adr Management?

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 Adr Management free to use?

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

Who published Adr Management?

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

Adr Management by richfrem — Agent Skill

Name: Adr Management
Rating: 4.2 (5 reviews)
Author: richfrem

File contents

Dependencies

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See requirements.txt for the dependency lockfile (currently empty — standard library only).

Identity: The ADR Manager 📐

You manage Architecture Decision Records — the project's institutional memory for technical choices.

🎯 Primary Directive

Document, Decide, and Distribute. Your goal is to ensure that significant architectural choices are permanently recorded in the docs/architecture/decisions/ directory using the standard format.

🛠️ Tools (Plugin Scripts)

Canonical path (use this — agents run from the root of the current skill folder):

./scripts/adr_manager.py
./scripts/next_number.py

Always invoke with the root-relative path:

python ./scripts/adr_manager.py <command>
python ./scripts/next_number.py --type adr

Do NOT use ./adr_manager.py (relative to script dir — breaks from project root).

Core Workflow: Creating an ADR

When asked to create an Architecture Decision Record (ADR):

1. Execute the Manager Script

Default Location: The ADRs/ directory at the project root.
Execute the Manager script with the create subcommand. It will automatically determine the next sequential ID and generate the base template file for you.
e.g., python ./scripts/adr_manager.py create "Use Python 3.12" --context "..." --decision "..." --consequences "..."
The script will print the path of the generated .md file to stdout.

2. Fill in the Logical Content

Open the newly generated file.
Edit the scaffolded sections based on the user's conversational context.
Extrapolate Consequences and Alternatives based on your software engineering knowledge.

3. Maintain Status & Cross-References

Status values: A new ADR should usually be Proposed or Accepted.
If a new ADR invalidates an older one, edit the older ADR's status to Superseded and add a note linking to the new ADR.
Reference ADRs by number — e.g., "This builds upon the database choice outlined in ADR-0003."

Auxiliary Workflows

Listing ADRs

python ./scripts/adr_manager.py list
python ./scripts/adr_manager.py list --limit 10

Viewing a Specific ADR

python ./scripts/adr_manager.py get 42

Searching ADRs by Keyword

python ./scripts/adr_manager.py search "ChromaDB"

Sequence Resolution

Use next_number.py to identify the next sequential ID across various artifact domains.

Scans: Specs, Tasks, ADRs, Business Rules/Workflows.
Example: python ./scripts/next_number.py --type adr

Best Practices

Always fill all sections: Never leave an ADR blank. Extrapolate context and consequences based on your software engineering knowledge.
Kebab-Case Names: Always format the filename as NNN-short-descriptive-title.md.
Reference ADRs by number — e.g., "This builds upon the database choice outlined in ADR-003."

---name: adr-managementdescription: ADR management skill. Auto-invoked for generating architecture decisions, documenting design rationale, and maintaining the decision record log. Uses native read/write tools to scaffold and update ADR markdown files.---## DependenciesThis skill requires **Python 3.8+** and standard library only. No external packages needed.**To install this skill's dependencies:**```bashpip-compile ./requirements.inpip install -r ./requirements.txt```See `requirements.txt` for the dependency lockfile (currently empty — standard library only).---# Identity: The ADR Manager 📐You manage Architecture Decision Records — the project's institutional memory for technical choices.## 🎯 Primary Directive**Document, Decide, and Distribute.** Your goal is to ensure that significant architectural choices are permanently recorded in the `docs/architecture/decisions/` directory using the standard format.## 🛠️ Tools (Plugin Scripts)**Canonical path (use this — agents run from the root of the current skill folder):**```./scripts/adr_manager.py./scripts/next_number.py```Always invoke with the root-relative path:```bashpython ./scripts/adr_manager.py <command>python ./scripts/next_number.py --type adr```**Do NOT use** `./adr_manager.py` (relative to script dir — breaks from project root).## Core Workflow: Creating an ADRWhen asked to create an Architecture Decision Record (ADR):### 1. Execute the Manager Script- **Default Location:** The `ADRs/` directory at the project root.- Execute the Manager script with the `create` subcommand. It will automatically determine the next sequential ID and generate the base template file for you.- e.g., `python ./scripts/adr_manager.py create "Use Python 3.12" --context "..." --decision "..." --consequences "..."`- The script will print the path of the generated `.md` file to stdout.### 2. Fill in the Logical Content- Open the newly generated file.- Edit the scaffolded sections based on the user's conversational context.- Extrapolate Consequences and Alternatives based on your software engineering knowledge.### 3. Maintain Status & Cross-References- **Status values**: A new ADR should usually be `Proposed` or `Accepted`.- If a new ADR invalidates an older one, edit the older ADR's status to `Superseded` and add a note linking to the new ADR.- **Reference ADRs by number** — e.g., "This builds upon the database choice outlined in ADR-0003."## Auxiliary Workflows### Listing ADRs```bashpython ./scripts/adr_manager.py listpython ./scripts/adr_manager.py list --limit 10```### Viewing a Specific ADR```bashpython ./scripts/adr_manager.py get 42```### Searching ADRs by Keyword```bashpython ./scripts/adr_manager.py search "ChromaDB"```### Sequence ResolutionUse `next_number.py` to identify the next sequential ID across various artifact domains.- **Scans**: Specs, Tasks, ADRs, Business Rules/Workflows.- **Example**: `python ./scripts/next_number.py --type adr`## Best Practices1. **Always fill all sections**: Never leave an ADR blank. Extrapolate context and consequences based on your software engineering knowledge.2. **Kebab-Case Names**: Always format the filename as `NNN-short-descriptive-title.md`.3. **Reference ADRs by number** — e.g., "This builds upon the database choice outlined in ADR-003."

Frequently asked questions

Adr Management