architecture-decision-record
Skill1 starsChanged 4 months agoMITView on GitHub
Explicit-invocation Skill to create or update an ADR from a real architectural problem, evidence, alternatives, tradeoffs, and an explicit decision state while respecting repository conventions. Requires authorized ADR scope; do not fabricate consensus, plan implementation, or modify business code. 仅显式调用:根据真实架构问题、证据、候选方案、权衡和明确决策状态创建或更新 ADR,并遵循仓库约定。必须获得 ADR 范围授权;不虚构共识、不生成实施计划,也不修改业务代码。
We split this skill into the rules it gives an agent
5 rules. 0 are common, 3 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 10 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Default to standard; explicit invocation is required.
- Distinctive: line 17
Create or update one ADR when the user explicitly authorizes architecture-document edits.
- Distinctive: line 21
Search for an existing ADR directory, index, numbering scheme, status vocabulary, template, and supersession rules before writing.
- Very specific: line 22
Never present a proposal as accepted consensus.
- Distinctive: line 23
Use official standards only when allowed and necessary, recording source and access date.
“Common” is measured: kept by at least 6 in 10 of the 10 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.
Files
English
Execution Contract
Default to standard; explicit invocation is required.
Complete one primary task by default. Continue an authorized end-to-end workflow within each Skill's permissions; Router remains recommendation-only. Pause for new material decisions or scope, not authorization already given.
For a human-only blocker, give location, action, success signal and resume step; never request secret values or assume completion.
Validate according to actual risk; security, production, migrations, releases and other high-risk work use audit. Read references/execution-modes.en.md only when mode selection is unclear.
Architecture Decision Record
Create or update one ADR when the user explicitly authorizes architecture-document edits. Do not modify business code.
Boundary
- Route requirements to
requirements-to-spec, implementation sequencing tosafe-change-plan, and technical risk reviews to the relevant specialized skill. - Search for an existing ADR directory, index, numbering scheme, status vocabulary, template, and supersession rules before writing.
- Never present a proposal as accepted consensus. Use
Proposedwhen approval evidence is absent. - Use official standards only when allowed and necessary, recording source and access date; mark unavailable evidence unverified.
Workflow
- Identify the real problem, scope, stakeholders, constraints, decision drivers, evidence, and review deadline.
- Find related ADRs and determine whether to create, amend, supersede, or leave unchanged.
- Compare viable alternatives, including status quo, with benefits, costs, risks, reversibility, compatibility, operational impact, and evidence.
- Record status, date, context, drivers, options, decision, rationale, positive/negative consequences, risks, validation, and review conditions.
- Preserve repository naming, location, numbering, links, language, and template. If none exists, use
assets/adr-template.md. - Modify only the ADR or architecture index explicitly in scope. Report assumptions, unresolved questions, confidence, and implementation handoff without executing it.
Output Contract
- Target ADR path and action
- Evidence and related decisions
- Status, date, context, and decision drivers
- Options and tradeoffs
- Decision and rationale, or Proposed recommendation
- Consequences, risks, confidence, validation, and review conditions
- Unknowns and implementation handoff
简体中文
执行契约
默认使用 standard;仅允许用户显式调用。
默认完成一个主任务。用户已授权完整流程时,在各 Skill 权限内连续完成;Router 仍只推荐。新重大决策或超出授权时暂停,不重复索取已有授权。
必须由用户完成的阻塞步骤:给出操作位置、具体动作、成功标志、恢复步骤;不要求粘贴秘密值,不代替用户确认完成。
按实际风险选择验证;安全、生产、迁移、发布等高风险工作使用 audit。模式不明确时才读取 references/execution-modes.zh-CN.md。
架构决策记录
仅在用户明确授权架构文档修改时创建或更新一个 ADR,不修改业务代码。
职责边界
- 需求交给
requirements-to-spec,实施顺序交给safe-change-plan,技术风险交给相应专项 Skill。 - 写入前搜索现有 ADR 目录、索引、编号、状态词、模板和替代规则。
- 不得把提案写成已接受共识;没有批准证据时使用
Proposed。 - 仅在允许且必要时使用官方标准,记录来源和访问日期;不可访问时标为未验证。
工作流程
- 识别真实问题、范围、利益相关者、约束、决策驱动、证据和复审时间。
- 查找相关 ADR,判断创建、修订、替代或保持不变。
- 比较可行候选及维持现状,覆盖收益、成本、风险、可逆性、兼容性、运维影响和证据。
- 记录状态、日期、背景、驱动、方案、决策、理由、正负后果、风险、验证和复审条件。
- 保留仓库命名、目录、编号、链接、语言和模板;不存在时使用
assets/adr-template.md。 - 只修改范围内 ADR 或架构索引,报告假设、未决问题、置信度和实施转交,不执行实施。
输出契约
- 目标 ADR 路径与动作
- 证据与相关决策
- 状态、日期、背景与决策驱动
- 候选方案与权衡
- 决策与理由,或 Proposed 建议
- 后果、风险、置信度、验证与复审条件
- 未知项与实施转交
Other versions13 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 13
- Amazon-Quick/Amazon-Quick-official-catalog★ 50same name
- PL-Coding-GmbH/Skills★ 14same name
- jimyag/dotfiles★ 11same name
- z-Zihan/Evir★ 11same name
- Future-CX/AI-Architecture-Toolkit★ 8same name
- kesslernity/awesome-copilot-agent-skills★ 8same name
- fattain-naime/engineering-docs★ 6same name
- affectionatec/agentic-engineering★ 5same name
- FullFran/Agent-skills-POC★ 1same name
- kesslernity/awesome-mistral-vibe-skills★ 1same name
3 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository40 other files it gives its agents.
- api-contract-reviewSkill
- architecture-deepening-analysisSkill
- bug-root-cause-analysisSkill
- change-impact-analysisSkill
- ci-failure-diagnosisSkill
- configuration-auditSkill
- content-consistency-checkSkill
- database-migration-reviewSkill
- dead-code-verificationSkill
- decision-prototypeSkill
- dependency-upgrade-analysisSkill
- documentation-syncSkill
- document-reviewSkill
- excel-data-quality-check-basicSkill
- feature-implementationSkill
- meeting-notes-to-actionsSkill
- pdf-review-basicSkill
- pdf-reviewSkill
- performance-regression-analysisSkill
- presentation-outlineSkill
- project-health-checkSkill
- release-readiness-checkSkill
- repo-doctor-routerSkill
- repo-onboardingSkill
- report-writerSkill
- requirements-clarificationSkill
- requirements-to-specSkill
- research-briefSkill
- safe-change-planSkill
- safe-code-reviewSkill
- safe-fix-implementationSkill
- safe-test-implementationSkill
- security-focused-reviewSkill
- session-handoffSkill
- skill-authoringSkill
- skill-quality-auditSkill
- spec-to-work-itemsSkill
- spreadsheet-data-cleaningSkill
- test-gap-analysisSkill
- word-document-review-basicSkill
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
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.

