New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Architecture Decision Record

by yonatangross in yonatangross/orchestkit

ADR templates in the Nygard format with context, decision, consequences, and alternatives.

MITAuto-check passedDevelopment

Install Architecture Decision Record

skills CLI
$ npx skills add yonatangross/orchestkit --skill architecture-decision-record -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install yonatangross/orchestkit architecture-decision-record --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/yonatangross/orchestkit.git skills-src && mkdir -p .claude/skills && cp -r skills-src/src/skills/architecture-decision-record .claude/skills/architecture-decision-record && rm -rf skills-src

Use ~/.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/

Facts

Skill name
architecture-decision-record
GitHub stars
292
Token cost
~2k tokens
SKILL.md length
873 words
Files
17 (incl. scripts, references, assets)
Skills in repo
108
Repo updated
First seen
Licence
MIT

At a glance

ADR templates in the Nygard format with context, decision, consequences, and alternatives.

  • Works in 12 steps: Title → Status → Context → …
  • Recording an architectural decision
  • SKILL.md covers Overview, Why ADRs Matter, ADR Format (Nygard Template) and ADR Lifecycle, plus 7 more sections
  • Runs Python scripts from its folder

What it does

Architecture Decision Record is an agent skill from yonatangross/orchestkit. ADR templates in the Nygard format with context, decision, consequences, and alternatives. Use when writing ADRs, recording an architectural decision, or evaluating options.

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 22 other files, including scripts, reference files and assets (for example `assets/adr-template.md`, `checklists/adr-review-checklist.md` and `examples/adr-0001-adopt-microservices.md`). Compatibility notes: Claude Code 2.1.277+.

It sits in Development, covering Architecture decision records. The repository describes itself as: The Complete AI Development Toolkit for Claude Code. 106 skills, 36 agents, 171 hooks. Install ork for stable (v9.x), or ork-alpha for the v10 line, which ships daily. The licence is MIT.

When your agent uses it

  • Recording an architectural decision
  • Evaluating options

Example prompts

  • “/architecture-decision-record”

Requirements

  • Python 3
  • Node.js
  • Compatibility (from SKILL.md): Claude Code 2.1.277+.
  • Pre-approved tools (allowed-tools): Read, Glob, Grep, WebFetch, WebSearch

Workflow steps

12 steps, taken from the step headings in SKILL.md.

  1. Title
  2. Status
  3. Context
  4. Decision
  5. Consequences
  6. Alternatives Considered
  7. References (Optional)
  8. Keep ADRs Immutable
  9. Write in Present Tense
  10. Focus on 'Why', Not 'How'
  11. Review ADRs as Team
  12. Number Sequentially

What it can do on your machine

Read from SKILL.md and the folder at commit e4ff8d9. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Glob
    • Grep
    • WebFetch
    • WebSearch

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 3 files in scripts/ (Python, from the files we listed), which the agent can run.

    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.

  • Compatibility

    Claude Code 2.1.277+.

    From compatibility in the SKILL.md frontmatter.

Context cost

Architecture Decision Record loads about 2k tokens when it runs, and up to ~12k if it reads all its reference files. Until then it costs about 51 tokens; SKILL.md has 873 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~51
When it runs · the whole SKILL.md, loaded when a task matches
~2k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~12k

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); the scripts in this folder are not scanned.

SKILL.md

The full file from yonatangross/orchestkit at commit e4ff8d9, republished under its MIT licence (© yonatangross). 873 words, ~2,032 tokens.

Download SKILL.mdSave it as .claude/skills/architecture-decision-record/SKILL.md (or your agent's skills folder). This skill also uses 16 other files; get the full folder from GitHub.
name
architecture-decision-record
description
ADR templates in the Nygard format with context, decision, consequences, and alternatives. Use when writing ADRs, recording an architectural decision, or evaluating options.
allowed-tools
Read, Glob, Grep, WebFetch, WebSearch
compatibility
Claude Code 2.1.277+.
license
MIT
user-invocable
false
metadata.owner-agent
backend-system-architect
metadata.category
document-asset-creation
metadata.version
2.0.0
metadata.author
OrchestKit
metadata.complexity
medium
metadata.tags
architecture, documentation, decision-making, backend

Architecture Decision Records

Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions along with their context and consequences. This skill provides templates, examples, and best practices for creating and maintaining ADRs in your projects.

Overview

  • Making significant technology choices (databases, frameworks, cloud providers)
  • Designing system architecture or major components
  • Establishing patterns or conventions for the team
  • Evaluating trade-offs between multiple approaches
  • Documenting decisions that will impact future development

Why ADRs Matter

ADRs serve as architectural memory for your team:

  • Context Preservation: Capture why decisions were made, not just what was decided
  • Onboarding: Help new team members understand architectural rationale
  • Prevent Revisiting: Avoid endless debates about settled decisions
  • Track Evolution: See how architecture evolved over time
  • Accountability: Clear ownership and decision timeline

ADR Format (Nygard Template)

Each ADR should follow this structure:

1. Title

Format: ADR-####: [Decision Title] Example: ADR-0001: Adopt Microservices Architecture

2. Status

Current state of the decision:

  • Proposed: Under consideration
  • Accepted: Decision approved and being implemented
  • Superseded: Replaced by a later decision (reference ADR number)
  • Deprecated: No longer recommended but not yet replaced
  • Rejected: Considered but not adopted (document why)
3. Context

What to include:

  • Problem statement or opportunity
  • Business/technical constraints
  • Stakeholder requirements
  • Current state of the system
  • Forces at play (conflicting concerns)
4. Decision

What to include:

  • The choice being made
  • Key principles or patterns to follow
  • What will change as a result
  • Who is responsible for implementation

Be specific and actionable:

  • ✅ "We will adopt microservices architecture using Node.js with Express"
  • ❌ "We will consider using microservices"
5. Consequences

What to include:

  • Positive outcomes (benefits)
  • Negative outcomes (costs, risks, trade-offs)
  • Neutral outcomes (things that change but aren't clearly better/worse)
6. Alternatives Considered

Document at least 2 alternatives:

For each alternative, explain:

  • What it was
  • Why it was considered
  • Why it was not chosen
7. References (Optional)

Links to relevant resources:

  • Meeting notes or discussion threads
  • Related ADRs
  • External research or articles
  • Proof of concept implementations

ADR Lifecycle

Proposed → Accepted → [Implemented] → (Eventually) Superseded/Deprecated
          ↓
      Rejected

Best Practices

1. Keep ADRs Immutable

Once accepted, don't edit ADRs. Create new ADRs that supersede old ones.

  • ✅ Create ADR-0015 that supersedes ADR-0003
  • ❌ Update ADR-0003 with new decisions
2. Write in Present Tense

ADRs are historical records written as if the decision is being made now.

  • ✅ "We will adopt microservices"
  • ❌ "We adopted microservices"
3. Focus on 'Why', Not 'How'

ADRs capture decisions, not implementation details.

  • ✅ "We chose PostgreSQL for relational consistency"
  • ❌ "Configure PostgreSQL with these specific settings..."
4. Review ADRs as Team

Get input from relevant stakeholders before accepting.

  • Architects: Technical viability
  • Developers: Implementation feasibility
  • Product: Business alignment
  • DevOps: Operational concerns
5. Number Sequentially

Use 4-digit zero-padded numbers: ADR-0001, ADR-0002, etc. Maintain a single sequence even with multiple projects.

6. Store in Git

Keep ADRs in version control alongside code:

  • Location: /docs/adr/ or /architecture/decisions/
  • Format: Markdown for easy reading
  • Branch: Same branch as implementation

Quick Start Checklist

  • Run /create-adr [number] [title] to generate ADR with auto-filled context
  • ADR number, date, and author are auto-populated
  • Review and fill in decision details
  • Set Status to "Proposed" and review with team
Show full SKILL.md (367 more words)Show less
Option 2: Use Static Template
  • Copy ADR template from assets/adr-template.md
  • Assign next sequential number (check existing ADRs)
  • Fill in Context: problem, constraints, requirements
  • Document Decision: what, why, how, who
  • List Consequences: positive, negative, neutral
  • Describe at least 2 Alternatives: what, pros/cons, why not chosen
  • Add References: discussions, research, related ADRs
  • Set Status to "Proposed"
  • Review with team
  • Update Status to "Accepted" after approval
  • Link ADR in implementation PR
  • Update Status to "Implemented" after deployment

Available Scripts

  • scripts/create-adr.md - Dynamic ADR generator with auto-filled context

    • Auto-fills: ADR number, date, author, total ADRs count
    • Usage: /create-adr [number] [title]
    • Uses $ARGUMENTS and !command for dynamic context

  • assets/adr-template.md - Static template for manual use

Rules Quick Reference

RuleImpactWhat It Covers
interrogation-scalabilityHIGHScale questions, data volume, growth projections
interrogation-reliabilityHIGHData patterns, UX impact, coherence validation
interrogation-securityHIGHAccess control, tenant isolation, attack surface

Common Pitfalls to Avoid

❌ Too Technical: "We'll use Kubernetes with these 50 YAML configs..." ✅ Right Level: "We'll use Kubernetes for container orchestration because..."

❌ Too Vague: "We'll use a better database" ✅ Specific: "We'll use PostgreSQL 15+ for transactional data because..."

❌ No Alternatives: Only documenting the chosen solution ✅ Comparative: Document why alternatives weren't chosen

❌ Missing Consequences: Only listing benefits ✅ Balanced: Honest about costs and trade-offs

❌ No Context: "We decided to use Redis" ✅ Contextual: "Given our 1M+ concurrent users and sub-50ms latency requirement..."

  • ork:api-design: Use when designing APIs referenced in ADRs
  • ork:database-patterns: Use when ADR involves database choices
  • security-checklist: Consult when ADR has security implications

Skill Version: 2.0.0 Last Updated: 2026-01-08 Maintained by: OrchestKit

Capability Details

adr-creation

Keywords: adr, architecture decision, decision record, document decision Solves:

  • How do I document an architectural decision?
  • Create an ADR
  • Architecture decision template
adr-best-practices

Keywords: when to write adr, adr lifecycle, adr workflow, adr process, adr review, quantify impact Solves:

  • When should I write an ADR?
  • How do I manage ADR lifecycle?
  • What's the ADR review process?
  • How to quantify decision impact?
  • ADR anti-patterns to avoid
  • Link related ADRs
tradeoff-analysis

Keywords: tradeoff, pros cons, alternatives, comparison, evaluate options Solves:

  • How do I analyze tradeoffs?
  • Compare architectural options
  • Document alternatives considered
consequences

Keywords: consequence, impact, risk, benefit, outcome Solves:

  • What are the consequences of this decision?
  • Document decision impact
  • Risk and benefit analysis

© yonatangross, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 16 other files (scripts, references, assets) in src/skills/architecture-decision-record of yonatangross/orchestkit.

  • SKILL.md
  • assets/adr-template.md
  • checklists/adr-review-checklist.md
  • examples/adr-0001-adopt-microservices.md
  • examples/adr-0002-choose-postgresql.md
  • examples/adr-0003-api-versioning-strategy.md
  • references/adr-best-practices.md
  • rules/_sections.md
  • rules/_template.md
  • rules/interrogation-reliability.md
  • rules/interrogation-scalability.md
  • rules/interrogation-security.md
  • scripts/adr-frontmatter.yaml
  • scripts/adr-manager.py
  • scripts/create-adr.md
  • … and 2 more

Open the folder on GitHubat commit e4ff8d9

Compare with similar skills

Architecture Decision Record 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.

Architecture Decision Record compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Architecture Decision Record this skillyonatangross/orchestkit292—~2kAutomated safety check: PassMIT
PR Design DocOpenHands/OpenHands90k—~2.4kAutomated safety check: PassMIT
Cto AdvisorIbrahim-3d/orchestrator-supaconductor3814 repos~2.4kAutomated safety check: PassMIT
Architecture DecisionDonchitos/Claude-Code-Game-Studios26k—~1.7kAutomated safety check: PassMIT
Improve Codebase Architectureywwynm/EverythingDone14415 repos~1.3kAutomated safety check: PassGPL-3.0
Domain Modelingbrim-borium/spotify_sdk1665 repos~806Automated safety check: PassApache-2.0

Similar skills

  • 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…

    90k GitHub stars~2.4k tokensUpdated today
    DevelopmentAuto-check passed

  • Cto Advisor

    Ibrahim-3d/orchestrator-supaconductor

    Technical leadership guidance for engineering teams, architecture decisions, and technology strategy.

    381 GitHub starsUsed in 4 repos~2.4k tokens
    DevelopmentAuto-check passed

  • Architecture Decision

    Donchitos/Claude-Code-Game-Studios

    Create an ADR documenting a technical decision: context, alternatives considered, consequences.

    26k GitHub stars~1.7k tokensUpdated 2 days ago
    DevelopmentAuto-check passed

  • 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/.

    144 GitHub starsUsed in 15 repos~1.3k tokens
    DevelopmentAuto-check passed

  • Domain Modeling

    brim-borium/spotify_sdk

    Build and sharpen a project's domain model. An agent skill from brim-borium/spotify_sdk.

    166 GitHub starsUsed in 5 repos~806 tokens
    DevelopmentAuto-check passed

  • Design Doc Mermaid

    SpillwaveSolutions/design-doc-mermaid

    Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code.

    176 GitHub starsUsed in 1 repo~5.6k tokens
    DevelopmentAuto-check passed

More from yonatangross/orchestkit

All 108 skills in this repo

  • API Design

    yonatangross/orchestkit

    API contract design for REST and GraphQL, covering resource shape, URL and header versioning with deprecation windows, RFC 9457 Problem Details error handling, and OpenAPI specs.

    292 GitHub stars~2.9k tokensUpdated today
    Auto-check passed

  • Audit Full

    yonatangross/orchestkit

    Single-pass codebase analysis leveraging a 1M-token context window for comprehensive security scanning, architecture review, and dependency auditing.

    292 GitHub stars~3.5k tokensUpdated today
    Auto-check: notes

  • Code Review Playbook

    yonatangross/orchestkit

    Structured review processes, conventional comments, language-specific checklists, and feedback templates.

    292 GitHub stars~2.2k tokensUpdated today
    Auto-check passed

  • Create PR

    yonatangross/orchestkit

    Creates GitHub pull requests with pre-flight validation, conventional title formatting, and structured summary generation.

    292 GitHub stars~4.5k tokensUpdated today
    Auto-check: notes

  • Explore

    yonatangross/orchestkit

    Multi-angle codebase exploration spawning 3-5 parallel agents for code structure, data flow, architecture patterns, and health assessment.

    292 GitHub stars~3.9k tokensUpdated today
    Auto-check: notes

  • Python Backend

    yonatangross/orchestkit

    Production Python async patterns including asyncio TaskGroup, FastAPI dependency injection and middleware, SQLAlchemy 2.0 async sessions, and database connection pool tuning.

    292 GitHub stars~2.8k tokensUpdated today
    Auto-check: notes

Categories

Questions about Architecture Decision Record

What does Architecture Decision Record do?

ADR templates in the Nygard format with context, decision, consequences, and alternatives. Architecture Decision Record is an agent skill from yonatangross/orchestkit. ADR templates in the Nygard format with context, decision, consequences, and alternatives.

When should I use Architecture Decision Record?

Architecture Decision Record fits situations like: recording an architectural decision; evaluating options.

How do I install Architecture Decision Record in Claude Code?

Run `npx skills add yonatangross/orchestkit --skill architecture-decision-record -a claude-code`. Or copy the skill folder (src/skills/architecture-decision-record in yonatangross/orchestkit) into .claude/skills/architecture-decision-record in your project. Claude Code loads it when a task matches its description.

How do I install Architecture Decision Record in Codex?

Run `npx skills add yonatangross/orchestkit --skill architecture-decision-record -a codex`. Or copy the skill folder (src/skills/architecture-decision-record in yonatangross/orchestkit) into .agents/skills/architecture-decision-record in your project. Codex loads it when a task matches its description.

Can I use Architecture Decision Record 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 yonatangross/orchestkit --skill architecture-decision-record -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-record, .gemini/skills/architecture-decision-record, .github/skills/architecture-decision-record and .opencode/skills/architecture-decision-record in your project.

What does Architecture Decision Record need to run?

Going by SKILL.md and its folder, Architecture Decision Record needs Python for the scripts in its folder. Our summary lists: Python 3; Node.js. Its frontmatter pre-approves these tools: Read, Glob, Grep, WebFetch, WebSearch. Compatibility (from SKILL.md): Claude Code 2.1.277+..

Does Architecture Decision Record 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 Record 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. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Architecture Decision Record use?

Architecture Decision Record is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Architecture Decision Record use?

About 2k tokens (SKILL.md is roughly 8.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 9.6k tokens, read only when the agent opens those files.

What are the alternatives to Architecture Decision Record?

Skills that share tags, products or a category with Architecture Decision Record: PR Design Doc (OpenHands/OpenHands, 90k stars), Cto Advisor (Ibrahim-3d/orchestrator-supaconductor, 381 stars), Architecture Decision (Donchitos/Claude-Code-Game-Studios, 26k stars) and Improve Codebase Architecture (ywwynm/EverythingDone, 144 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Architecture Decision Record?

yonatangross (a GitHub user) maintains it in yonatangross/orchestkit, which has 292 GitHub stars. The repository holds 108 skills in this directory. The repository was last updated on October 10, 2026.

Source: yonatangross/orchestkit on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.