PR Design Doc
OpenHands/OpenHands
For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link a visibility-appropriate preview in the PR description, so maintainers grasp the…
Capture architectural decisions as numbered ADR markdown files in docs/adr/ with context, alternatives considered, consequences, and an index README.
Install Architecture Decision Records
$ npx skills add affaan-m/ECC --skill architecture-decision-records -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install affaan-m/ECC architecture-decision-records --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/affaan-m/ECC.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/architecture-decision-records .claude/skills/architecture-decision-records && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "architecture-decision-records" agent skill from https://github.com/affaan-m/ECC/tree/main/skills/architecture-decision-records into .claude/skills/architecture-decision-records/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-decision-records", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/affaan-m/ECC/tree/main/skills/architecture-decision-recordsType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add affaan-m/ECC --skill architecture-decision-records -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install affaan-m/ECC architecture-decision-records --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/affaan-m/ECC.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/architecture-decision-records .agents/skills/architecture-decision-records && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "architecture-decision-records" agent skill from https://github.com/affaan-m/ECC/tree/main/skills/architecture-decision-records into .agents/skills/architecture-decision-records/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-decision-records", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add affaan-m/ECC --skill architecture-decision-records -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install affaan-m/ECC architecture-decision-records --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/affaan-m/ECC.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/architecture-decision-records .cursor/skills/architecture-decision-records && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "architecture-decision-records" agent skill from https://github.com/affaan-m/ECC/tree/main/skills/architecture-decision-records into .cursor/skills/architecture-decision-records/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-decision-records", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/affaan-m/ECC.git --path skills/architecture-decision-records--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add affaan-m/ECC --skill architecture-decision-records -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install affaan-m/ECC architecture-decision-records --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/affaan-m/ECC.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/architecture-decision-records .gemini/skills/architecture-decision-records && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "architecture-decision-records" agent skill from https://github.com/affaan-m/ECC/tree/main/skills/architecture-decision-records into .gemini/skills/architecture-decision-records/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-decision-records", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install affaan-m/ECC architecture-decision-recordsInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add affaan-m/ECC --skill architecture-decision-records -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/affaan-m/ECC.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/architecture-decision-records .github/skills/architecture-decision-records && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "architecture-decision-records" agent skill from https://github.com/affaan-m/ECC/tree/main/skills/architecture-decision-records into .github/skills/architecture-decision-records/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-decision-records", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add affaan-m/ECC --skill architecture-decision-records -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install affaan-m/ECC architecture-decision-records --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/affaan-m/ECC.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/architecture-decision-records .opencode/skills/architecture-decision-records && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "architecture-decision-records" agent skill from https://github.com/affaan-m/ECC/tree/main/skills/architecture-decision-records into .opencode/skills/architecture-decision-records/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-decision-records", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
architecture-decision-records- GitHub stars
- 277k
- Used in
- 4 other repos
- Token cost
- ~1.8k tokens
- SKILL.md length
- 685 words
- Files
- 1
- Skills in repo
- 683
- Repo updated
- First seen
- Licence
- MIT
At a glance
Capture architectural decisions as numbered ADR markdown files in docs/adr/ with context, alternatives considered, consequences, and an index README.
- Works in 8 steps: Initialize (first time only) — if… → Identify the decision — extract the core… → Gather context — what problem prompted… → …
- The user says record this decision
- SKILL.md covers When to Activate, ADR Format, Workflow and Decision Detection Signals, plus 4 more sections
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
Architecture Decision Records is an agent skill from affaan-m/ECC. Capture architectural decisions as numbered ADR markdown files in docs/adr/ with context, alternatives considered, consequences, and an index README. Use when the user says 'record this decision' or 'ADR this', chooses between frameworks or databases, discusses trade-offs, or asks why the codebase is shaped this way.
Its SKILL.md is about 1.8k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Development, covering Architecture decision records. The repository describes itself as: The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond. The licence is MIT.
When your agent uses it
- The user says record this decision
- Chooses between frameworks
- Discusses trade-offs
- Asks why the codebase is shaped this way
Example prompts
- “record this decision”
- “ADR this”
- “/architecture-decision-records”
Workflow steps
8 steps, taken from the first numbered list in SKILL.md.
- Initialize (first time only) — if docs/adr/ does not exist, ask the user for confirmation before creating the directory, a README.md…
- Identify the decision — extract the core architectural choice being made
- Gather context — what problem prompted this? What constraints exist?
- Document alternatives — what other options were considered? Why were they rejected?
- State consequences — what are the trade-offs? What becomes easier/harder?
- Assign a number — scan existing ADRs in docs/adr/ and increment
- Confirm and write — present the draft ADR to the user for review. Only write to docs/adr/NNNN-decision-title.md after explicit approval…
- Update the index — append to docs/adr/README.md
What it can do on your machine
Read from SKILL.md and the folder at commit 2d515e4. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Architecture Decision Records loads about 1.8k tokens when it runs. Until then it costs about 87 tokens; SKILL.md has 685 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from affaan-m/ECC at commit 2d515e4, republished under its MIT licence (© affaan-m). 685 words, ~1,774 tokens.
Download SKILL.mdSave it as
.claude/skills/architecture-decision-records/SKILL.md (or your agent's skills folder).- name
- architecture-decision-records
- description
- Capture architectural decisions as numbered ADR markdown files in docs/adr/ with context, alternatives considered, consequences, and an index README. Use when the user says 'record this decision' or 'ADR this', chooses between frameworks or databases, discusses trade-offs, or asks why the codebase is shaped this way.
- metadata.origin
- ECC
Architecture Decision Records
Capture architectural decisions as they happen during coding sessions. Instead of decisions living only in Slack threads, PR comments, or someone's memory, this skill produces structured ADR documents that live alongside the code.
When to Activate
- User explicitly says "let's record this decision" or "ADR this"
- User chooses between significant alternatives (framework, library, pattern, database, API design)
- User says "we decided to..." or "the reason we're doing X instead of Y is..."
- User asks "why did we choose X?" (read existing ADRs)
- During planning phases when architectural trade-offs are discussed
ADR Format
Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development:
# ADR-NNNN: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]
## Context
What is the issue that we're seeing that is motivating this decision or change?
[2-5 sentences describing the situation, constraints, and forces at play]
## Decision
What is the change that we're proposing and/or doing?
[1-3 sentences stating the decision clearly]
## Alternatives Considered
### Alternative 1: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]
### Alternative 2: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]
## Consequences
What becomes easier or more difficult to do because of this change?
### Positive
- [benefit 1]
- [benefit 2]
### Negative
- [trade-off 1]
- [trade-off 2]
### Risks
- [risk and mitigation]Workflow
Capturing a New ADR
When a decision moment is detected:
- Initialize (first time only) — if
docs/adr/does not exist, ask the user for confirmation before creating the directory, aREADME.mdseeded with the index table header (see ADR Index Format below), and a blanktemplate.mdfor manual use. Do not create files without explicit consent. - Identify the decision — extract the core architectural choice being made
- Gather context — what problem prompted this? What constraints exist?
- Document alternatives — what other options were considered? Why were they rejected?
- State consequences — what are the trade-offs? What becomes easier/harder?
- Assign a number — scan existing ADRs in
docs/adr/and increment - Confirm and write — present the draft ADR to the user for review. Only write to
docs/adr/NNNN-decision-title.mdafter explicit approval. If the user declines, discard the draft without writing any files. - Update the index — append to
docs/adr/README.md
Reading Existing ADRs
When a user asks "why did we choose X?":
- Check if
docs/adr/exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?" - If it exists, scan
docs/adr/README.mdindex for relevant entries - Read matching ADR files and present the Context and Decision sections
- If no match is found, respond: "No ADR found for that decision. Would you like to record one now?"
ADR Directory Structure
docs/
└── adr/
├── README.md ← index of all ADRs
├── 0001-use-nextjs.md
├── 0002-postgres-over-mongo.md
├── 0003-rest-over-graphql.md
└── template.md ← blank template for manual useADR Index Format
# Architecture Decision Records
| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 |Decision Detection Signals
Watch for these patterns in conversation that indicate an architectural decision:
Explicit signals
- "Let's go with X"
- "We should use X instead of Y"
- "The trade-off is worth it because..."
- "Record this as an ADR"
Implicit signals (suggest recording an ADR — do not auto-create without user confirmation)
- Comparing two frameworks or libraries and reaching a conclusion
- Making a database schema design choice with stated rationale
- Choosing between architectural patterns (monolith vs microservices, REST vs GraphQL)
- Deciding on authentication/authorization strategy
- Selecting deployment infrastructure after evaluating alternatives
Show full SKILL.md (258 more words)Show less
What Makes a Good ADR
Do
- Be specific — "Use Prisma ORM" not "use an ORM"
- Record the why — the rationale matters more than the what
- Include rejected alternatives — future developers need to know what was considered
- State consequences honestly — every decision has trade-offs
- Keep it short — an ADR should be readable in 2 minutes
- Use present tense — "We use X" not "We will use X"
Don't
- Record trivial decisions — variable naming or formatting choices don't need ADRs
- Write essays — if the context section exceeds 10 lines, it's too long
- Omit alternatives — "we just picked it" is not a valid rationale
- Backfill without marking it — if recording a past decision, note the original date
- Let ADRs go stale — superseded decisions should reference their replacement
ADR Lifecycle
proposed → accepted → [deprecated | superseded by ADR-NNNN]- proposed: decision is under discussion, not yet committed
- accepted: decision is in effect and being followed
- deprecated: decision is no longer relevant (e.g., feature removed)
- superseded: a newer ADR replaces this one (always link the replacement)
Categories of Decisions Worth Recording
| Category | Examples |
|---|---|
| Technology choices | Framework, language, database, cloud provider |
| Architecture patterns | Monolith vs microservices, event-driven, CQRS |
| API design | REST vs GraphQL, versioning strategy, auth mechanism |
| Data modeling | Schema design, normalization decisions, caching strategy |
| Infrastructure | Deployment model, CI/CD pipeline, monitoring stack |
| Security | Auth strategy, encryption approach, secret management |
| Testing | Test framework, coverage targets, E2E vs integration balance |
| Process | Branching strategy, review process, release cadence |
Integration with Other Skills
- Planner agent: when the planner proposes architecture changes, suggest creating an ADR
- Code reviewer agent: flag PRs that introduce architectural changes without a corresponding ADR
© affaan-m, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in skills/architecture-decision-records of affaan-m/ECC.
Open the folder on GitHubat commit 2d515e4
Used in 4 other repositories
We found 10 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 4 other GitHub owners. This page covers the copy in affaan-m/ECC, which our catalogue first saw on October 7, 2026.
- loulanyue/awesome-claude-notesskills/architecture-decision-recordsdocs/tr/skills/architecture-decision-records+4 more
- hashgraph-online/awesome-codex-pluginsplugins/Colin4k1024/tsp/skills/architecture-decision-records
- Sidiora-Labs/centra-llm-agentsprotocol/skills/architecture-decision-records
- templetongroup/radiantskills/architecture-decision-records
Compare with similar skills
Architecture Decision Records next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Architecture Decision Records this skillaffaan-m/ECC | 277k | 4 repos | ~1.8k | Automated safety check: Pass | MIT | |
| PR Design DocOpenHands/OpenHands | 91k | — | ~2.4k | Automated safety check: Pass | MIT | |
| Cto AdvisorIbrahim-3d/orchestrator-supaconductor | 381 | 4 repos | ~2.4k | Automated safety check: Pass | MIT | |
| Domain Modelingbrim-borium/spotify_sdk | 166 | 7 repos | ~806 | Automated safety check: Pass | Apache-2.0 | |
| Architecture DecisionDonchitos/Claude-Code-Game-Studios | 26k | — | ~1.7k | Automated safety check: Pass | MIT | |
| Improve Codebase Architectureywwynm/EverythingDone | 144 | 15 repos | ~1.3k | Automated safety check: Pass | GPL-3.0 |
Similar skills
Cto Advisor
Ibrahim-3d/orchestrator-supaconductor
Technical leadership guidance for engineering teams, architecture decisions, and technology strategy.
Domain Modeling
brim-borium/spotify_sdk
Build and sharpen a project's domain model. An agent skill from brim-borium/spotify_sdk.
Architecture Decision
Donchitos/Claude-Code-Game-Studios
Create an ADR documenting a technical decision: context, alternatives considered, consequences.
Improve Codebase Architecture
ywwynm/EverythingDone
Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/.
Design Doc Mermaid
SpillwaveSolutions/design-doc-mermaid
Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code.
More from affaan-m/ECC
All 682 skills in this repoSkill Stocktake
affaan-m/ECC
Audits your installed Claude skills and commands for quality, with a quick mode for recently changed skills and a full mode that evaluates all of them through subagents.
VideoDB Video Search and Editing
affaan-m/ECC
Ingests, indexes, searches, edits and monitors video, audio and live streams through the VideoDB Python SDK, returning stream links, clips and timestamps.
Docs Governance
affaan-m/ECC
Route broad documentation-governance requests to existing ECC skills and run an opt-in, read-only audit of mapped documentation roles, links, ADR indexes, and evidence references.
Rules Distillation
affaan-m/ECC
Scans installed skills for principles that recur across them and proposes rule-file changes: append, revise, add a section, create a file or leave as covered.
Master Agreement Generator
affaan-m/ECC
Builds DRAFT counterparty agreements from one markdown template and a small JSON spec per party, with clauses picked by the party's role.
Frontend Design Direction
affaan-m/ECC
Set an ECC-specific frontend design direction for production UI work.
Related
Categories
Questions about Architecture Decision Records
What does Architecture Decision Records do?
Capture architectural decisions as numbered ADR markdown files in docs/adr/ with context, alternatives considered, consequences, and an index README. Architecture Decision Records is an agent skill from affaan-m/ECC. Capture architectural decisions as numbered ADR markdown files in docs/adr/ with context, alternatives considered, consequences, and an index README.
When should I use Architecture Decision Records?
Architecture Decision Records fits situations like: the user says record this decision; chooses between frameworks; discusses trade-offs; asks why the codebase is shaped this way.
How do I install Architecture Decision Records in Claude Code?
Run `npx skills add affaan-m/ECC --skill architecture-decision-records -a claude-code`. Or copy the skill folder (skills/architecture-decision-records in affaan-m/ECC) into .claude/skills/architecture-decision-records in your project. Claude Code loads it when a task matches its description.
How do I install Architecture Decision Records in Codex?
Run `npx skills add affaan-m/ECC --skill architecture-decision-records -a codex`. Or copy the skill folder (skills/architecture-decision-records in affaan-m/ECC) into .agents/skills/architecture-decision-records in your project. Codex loads it when a task matches its description.
Can I use Architecture Decision Records in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add affaan-m/ECC --skill architecture-decision-records -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/architecture-decision-records, .gemini/skills/architecture-decision-records, .github/skills/architecture-decision-records and .opencode/skills/architecture-decision-records in your project.
What does Architecture Decision Records need to run?
SKILL.md names no scripts, command-line tools or credentials: Architecture Decision Records is instructions for the agent only.
Does Architecture Decision Records access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Architecture Decision Records safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Architecture Decision Records use?
Architecture Decision Records is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Architecture Decision Records use?
About 1.8k tokens (SKILL.md is roughly 7.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Architecture Decision Records?
Skills that share tags, products or a category with Architecture Decision Records: PR Design Doc (OpenHands/OpenHands, 91k stars), Cto Advisor (Ibrahim-3d/orchestrator-supaconductor, 381 stars), Domain Modeling (brim-borium/spotify_sdk, 166 stars) and Architecture Decision (Donchitos/Claude-Code-Game-Studios, 26k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Architecture Decision Records?
affaan-m (a GitHub user) maintains it in affaan-m/ECC, which has 276,673 GitHub stars. The repository holds 683 skills in this directory. The repository was last updated on October 11, 2026.
Source: affaan-m/ECC on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.