agentleFS
Sign inStart free
AsiaOstrichAsiaOstrich/EngramGraph/.agents/skills/adr-assistant/SKILL.md

adr

Skill4 starsChanged 29 days agoMITView on GitHub

[UDS] Create, manage, and track Architecture Decision Records (ADR). Use when: architecture decisions, technology choices, design trade-offs, pattern selection. Not for: decisions that do not change architecture — record them in the spec or commit; ideas not yet formed enough to decide — use /brainstorm. Keywords: ADR, architecture decision, decision record, trade-off.

90 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use fdr, product-spec and 4 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • thiagofgfSkill

    fdr

    Use when creating, changing, reviewing, retiring, auditing, or backfilling implemented user-visible feature behavior, permissions, feature-specific rationale, tradeoffs, or relationships to architectural decisions.

    Also in 3 projects that use this

  • vndeeSkill

    product-spec

    Use when starting a new feature, product, or project — before any architecture or code, to define what to build and why

    Also in 3 projects that use this

  • OpenAISkill

    threat-model

    Use when Codex is already in the threat-modeling phase of a security scan, the user explicitly invokes $threat-model, or the user explicitly asks to create, update, or persist a repository threat model. Do not use as the primary trigger for full PR, commit, branch, patch, or repository scans.

    Also in 6 projects that use this

  • montymiSkill

    tech-spec

    Parse and review Technical Specification documents for completeness, consistency, and implementation readiness

    Also in 3 projects that use this

  • petestewartSkill

    test-review

    Review unit tests for quality, coverage, consistency, and adherence to existing codebase patterns. Use when the user says "/test-review", "review my tests", "check my test coverage", "are my tests good", or needs feedback on test quality and patterns.

    Also in 3 projects that use this

  • MicrosoftSkill

    jira

    Jira issue workflows for search, issue updates, transitions, comments, field discovery, and interactive credential setup via the Jira REST API. Use when you need to configure Jira access, search with JQL, inspect an issue, create or update work items, move an issue between statuses, post comments, or discover required fields for issue creation.

    Also in 5 projects that use this

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 4 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 75 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create, manage, and track Architecture Decision Records.

    line 17
  2. Distinctive:

    Rule of thumb: If someone might ask "why?" in 6 months, write an ADR.

    line 81
  3. Distinctive:

    Before accepting an ADR:

    line 149
  4. Very specific:

    After /adr completes, the AI assistant should suggest:

    line 161
  5. Very specific:

    When the user invokes /adr, the AI assistant MUST:

    line 177
  6. Very specific:

    When the user invokes /adr list:

    line 185
  7. Distinctive:

    Read the existing ADR

    line 191
  8. Very specific:

    Update old ADR status to Superseded by ADR-NNN

    line 193
  9. Very specific:

    Add Supersedes ADR-NNN to new ADR

    line 194

“Common” is measured: kept by at least 6 in 10 of the 75 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ADR Assistant | 架構決策記錄助手

Language: English | 繁體中文

Create, manage, and track Architecture Decision Records. Capture the context, options, and rationale behind significant technical decisions.

建立、管理和追蹤架構決策記錄。捕捉重大技術決策的背景、選項和理由。

Workflow | 工作流程

CAPTURE ──► ANALYZE ──► DECIDE ──► RECORD ──► LINK
  捕捉背景    分析選項    做出決策    記錄 ADR    建立連結

Phase 1: CAPTURE | 捕捉背景

Identify the context and constraints driving the decision.

識別驅動決策的背景與限制條件。

StepAction步驟
1Identify the problem or opportunity識別問題或機會
2List constraints (time, budget, team skills)列出限制條件
3Define decision drivers定義決策驅動因素

Phase 2: ANALYZE | 分析選項

Explore at least 2 options with pros and cons.

至少探索 2 個選項，列出優缺點。

StepAction步驟
1Brainstorm candidate options腦力激盪候選方案
2Evaluate each against decision drivers根據決策驅動因素評估
3Document pros/cons for each記錄各方案優缺點

Phase 3: DECIDE | 做出決策

Select the best option and articulate the rationale.

選擇最佳方案並闡述理由。

Phase 4: RECORD | 記錄 ADR

Generate the ADR file following the standard template.

依照標準模板產生 ADR 檔案。

Phase 5: LINK | 建立連結

Cross-reference with related artifacts (SPECs, PRs, code).

與相關工件（規格、PR、程式碼）建立交叉引用。

Quick Reference | 快速參考

When to Write an ADR | 何時撰寫 ADR

Write ADRSkip ADR
Framework/library choiceRoutine dependency update
API contract or data formatBug fix within existing architecture
Deployment strategy changeCode style decision
Establishing new patternsTrivial implementation choice

Rule of thumb: If someone might ask "why?" in 6 months, write an ADR.

經驗法則：如果 6 個月後有人可能會問「為什麼？」，就寫一份 ADR。

Status Lifecycle | 狀態生命週期

Proposed ──► Accepted ──► Deprecated
                │
                └──► Superseded by ADR-NNN
StatusDescription說明
ProposedUnder discussion討論中
AcceptedActive, should be followed已接受，應遵循
DeprecatedNo longer relevant不再適用
SupersededReplaced by newer ADR已被新 ADR 取代

ADR Template Summary | 模板摘要

# ADR-NNN: [Title]

- Status: [Proposed | Accepted | Deprecated | Superseded]
- Date: YYYY-MM-DD
- Deciders: [people]
- Technical Story: [SPEC-ID or Issue]

## Context
## Decision Drivers
## Considered Options
## Decision Outcome
### Consequences (Good / Bad / Neutral)
## Links

Storage | 存放位置

docs/adr/
├── ADR-001-short-description.md
├── ADR-002-short-description.md
└── README.md    # Index (optional)

Commands | 指令

CommandAction說明
/adrInteractive ADR creation wizard互動式建立 ADR
/adr createCreate a new ADR建立新 ADR
/adr listList all ADRs with status列出所有 ADR 及狀態
/adr search [keyword]Search ADRs by keyword依關鍵字搜尋 ADR
/adr supersede [ADR-NNN]Supersede an existing ADR取代現有 ADR
/adr reviewReview ADRs for staleness審查過期的 ADR

Integration with Other Skills | 與其他技能的整合

SkillIntegration整合方式
/sddReference ADRs in Technical Design; suggest creating ADR for major decisions在技術設計中引用 ADR
/code-reviewReference ADRs as design rationale during code review程式碼審查時引用 ADR
/commitInclude ADR-NNN in commit footer for traceability提交時在 footer 加入 ADR 編號
/brainstormFeed brainstorm output into ADR option analysis腦力激盪結果作為 ADR 選項分析輸入

Quality Checklist | 品質檢查清單

Before accepting an ADR:

CheckCriteria標準
☐ ContextClearly explains the problem清楚說明問題
☐ OptionsAt least 2 options considered至少考慮 2 個選項
☐ DriversDecision drivers explicitly listed決策驅動因素明確列出
☐ ConsequencesBoth good and bad outcomes包含正面與負面結果
☐ LinksRelated artifacts referenced相關工件已引用

Next Steps Guidance | 下一步引導

After /adr completes, the AI assistant should suggest:

ADR created. Suggested next steps:

  • Execute /sdd to create a spec if the decision requires implementation
  • Execute /commit to commit the ADR file
  • Update related SPECs to reference this ADR
  • Share with team for review if status is Proposed

ADR 已建立。建議下一步：

  • 執行 /sdd 建立規格（若決策需要實作）
  • 執行 /commit 提交 ADR 檔案
  • 更新相關規格以引用此 ADR
  • 若狀態為 Proposed，分享給團隊審查

AI Agent Behavior | AI 代理行為

When the user invokes /adr, the AI assistant MUST:

  1. Check existing ADRs — Search docs/adr/ to determine next ADR number
  2. Guide interactively — Ask about context, drivers, and options step by step
  3. Generate the file — Write ADR to docs/adr/ADR-NNN-title.md
  4. Suggest links — Identify related SPECs or ADRs to cross-reference
  5. Offer next steps — Show the Next Steps Guidance above

When the user invokes /adr list:

  1. Scan docs/adr/ directory
  2. Parse status from each ADR file
  3. Display as a table: Number, Title, Status, Date

When the user invokes /adr supersede [ADR-NNN]:

  1. Read the existing ADR
  2. Guide creation of a new ADR
  3. Update old ADR status to Superseded by ADR-NNN
  4. Add Supersedes ADR-NNN to new ADR

Reference | 參考

  • Core Standard: adr-standards.md
  • Detailed Guide: guide.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free