create-adr

Generate standardized Architectural Decision Records with sequential numbering and kebab-case filenames.

74|11|Updated May 23, 2025

Search Tags:#documentation #decision record #technical debt #software architecture #ADR #architectural decision #pragmatic mode

Ready to run

npx skills add https://github.com/codenamev/ai-software-architect --skill create-adr

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: create-adr
Source: https://github.com/codenamev/ai-software-architect/tree/main/.claude/skills/create-adr
Command: npx skills add https://github.com/codenamev/ai-software-architect --skill create-adr

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Architectural decisions are often made and forgotten, leading to inconsistent patterns, technical debt, and difficulty onboarding new team members. This Skill standardizes and automates the creation of Architectural Decision Records (ADRs), ensuring critical choices are well-documented and easily discoverable.

Core Features & Use Cases

Automated ADR Generation: Creates new ADRs with a unique sequential number and a standardized template.
Pragmatic Mode Integration: Automatically includes a "Pragmatic Enforcer" analysis to challenge over-engineering if enabled.
Input Validation: Ensures safe and consistent naming for ADR files.
Use Case: Your team decides to switch from a monolithic database to a microservice-specific database approach. You use "Create ADR for microservice database strategy" to document the problem, alternatives, decision, and consequences for future reference.

Quick Start

Create ADR for PostgreSQL database choice

Frequently Asked Questions about create-adr

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

What is an Architectural Decision Record and why do I need one?▼

An Architectural Decision Record (ADR) is a document that captures a significant architectural choice, its context, alternatives considered, and consequences. ADRs prevent architectural decisions from being forgotten, reduce onboarding friction, and help teams avoid repeating past mistakes or inconsistent patterns.

How do I create and organize ADRs for my team?▼

Create ADRs with automated sequential numbering and standardized templates. The Skill generates numbered files in a centralized .architecture/decisions/adrs/ directory, ensuring consistent naming, safe file paths, and discoverable records that your entire team can reference.

Can I document technology choices and infrastructure decisions in ADRs?▼

Yes. ADRs apply to technology choices, architectural patterns, infrastructure decisions, and security approaches. Each record captures the problem context, alternatives you evaluated, the decision made, and its consequences for future reference.

What happens if I enable Pragmatic Mode when creating an ADR?▼

Pragmatic Mode automatically includes a Pragmatic Enforcer analysis that challenges over-engineering within your architectural decision. This helps your team balance pragmatism with architectural rigor during the decision-documentation process.

How does the Skill handle file naming and input validation for ADRs?▼

The Skill validates and sanitizes all inputs by removing path traversal and control characters, converting names to lowercase kebab-case, and assigning sequential ADR numbers by scanning your existing ADR directory. This ensures safe, consistent filenames and prevents naming conflicts.