Index of every page on this site: llms.txt
All skills
github avatar

/create-architectural-decision-record

@f10fdb8 official
by githubgithub/awesome-copilot41k stars
5,399
Run it yourself

Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation.

Use this Skill: https://skilld.dev/gh/github/awesome-copilot/create-architectural-decision-record

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈33 tokens for metadata: the name and description. ≈725 when used: this file.

Description uses 1.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈134 characters, or 1.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Create Architectural Decision Record

Create an ADR document for ${input:DecisionTitle} using structured formatting optimized for AI consumption and human readability.

Inputs

  • Context: ${input:Context}
  • Decision: ${input:Decision}
  • Alternatives: ${input:Alternatives}
  • Stakeholders: ${input:Stakeholders}

Input Validation

If any of the required inputs are not provided or cannot be determined from the conversation history, ask the user to provide the missing information before proceeding with ADR generation.

Requirements

  • Use precise, unambiguous language
  • Follow standardized ADR format with front matter
  • Include both positive and negative consequences
  • Document alternatives with rejection rationale
  • Structure for machine parsing and human reference
  • Use coded bullet points (3-4 letter codes + 3-digit numbers) for multi-item sections

The ADR must be saved in the /docs/adr/ directory using the naming convention: adr-NNNN-[title-slug].md, where NNNN is the next sequential 4-digit number (e.g., adr-0001-database-selection.md).

Required Documentation Structure

The documentation file must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following:

---
title: "ADR-NNNN: [Decision Title]"
status: "Proposed"
date: "YYYY-MM-DD"
authors: "[Stakeholder Names/Roles]"
tags: ["architecture", "decision"]
supersedes: ""
superseded_by: ""
---

# ADR-NNNN: [Decision Title]

## Status

**Proposed** | Accepted | Rejected | Superseded | Deprecated

## Context

[Problem statement, technical constraints, business requirements, and environmental factors requiring this decision.]

## Decision

[Chosen solution with clear rationale for selection.]

## Consequences

### Positive

- **POS-001**: [Beneficial outcomes and advantages]
- **POS-002**: [Performance, maintainability, scalability improvements]
- **POS-003**: [Alignment with architectural principles]

### Negative

- **NEG-001**: [Trade-offs, limitations, drawbacks]
- **NEG-002**: [Technical debt or complexity introduced]
- **NEG-003**: [Risks and future challenges]

## Alternatives Considered

### [Alternative 1 Name]

- **ALT-001**: **Description**: [Brief technical description]
- **ALT-002**: **Rejection Reason**: [Why this option was not selected]

### [Alternative 2 Name]

- **ALT-003**: **Description**: [Brief technical description]
- **ALT-004**: **Rejection Reason**: [Why this option was not selected]

## Implementation Notes

- **IMP-001**: [Key implementation considerations]
- **IMP-002**: [Migration or rollout strategy if applicable]
- **IMP-003**: [Monitoring and success criteria]

## References

- **REF-001**: [Related ADRs]
- **REF-002**: [External documentation]
- **REF-003**: [Standards or frameworks referenced]

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides a template for generating Architectural Decision Records (ADR) based on user-provided input and saves them to a local documentation directory. It is safe for its intended purpose, although like any skill processing external text to create files, it has a minor surface for indirect prompt injection where malicious input could attempt to influence the document formatting or contents.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

  • ZeroLeaks7mo

    1 finding · Score: 69/100

Signed by skilld at f10fdb8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 9 months ago
  • Documentation
  • adr
  • architecture
  • decision-records
  • structured-format
  • decision-making
  • markdown
  • ai-optimization

README badge

README badge for github/awesome-copilot/create-architectural-decision-record

Generates an Architectural Decision Record (ADR) document with structured sections for context, decision rationale, consequences, and alternatives considered. The skill creates markdown files in `/docs/adr/` with coded bullet points and front matter, formatted for both AI parsing and human reference.

Generated from the current SKILL.md.

What format does this skill use for ADRs?
The skill generates ADRs with YAML front matter and markdown body, using coded bullet points (3-4 letter codes + 3-digit numbers) in sections like Consequences, Alternatives, and Implementation Notes for machine parsing.
Where does the skill save the generated ADR?
ADRs are saved in the `/docs/adr/` directory using the naming convention `adr-NNNN-[title-slug].md`, where NNNN is a sequential 4-digit number.
What inputs are required before the skill generates an ADR?
The skill requires Decision Title, Context, Decision, Alternatives, and Stakeholders. If any are missing, it will ask you to provide them before proceeding.
Does this skill validate the ADR structure?
The skill ensures all sections are filled out appropriately and enforces the standard template structure with Status, Context, Decision, Consequences, Alternatives Considered, Implementation Notes, and References sections.

Generated from the current SKILL.md. These answers refresh after source changes.