Architectural Proposals

How to write comprehensive architectural proposals that drive alignment before code is written

45 stars 11 forksWriting & Content

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add Azure-Samples/agent-skills-dotnet-demo --skill architectural-proposals
Manual install
git clone --depth 1 https://github.com/Azure-Samples/agent-skills-dotnet-demo.git /tmp/agent-skills-dotnet-demo
mkdir -p ~/.claude/skills
cp -r /tmp/agent-skills-dotnet-demo/.squad/templates/skills/architectural-proposals ~/.claude/skills/architectural-proposals

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

## Context

Proposals create alignment before code is written. Cheaper to change a doc than refactor code. Use this pattern when:
- Architecture shifts invalidate existing assumptions
- Product direction changes require new foundation
- Multiple waves/milestones will be affected by a decision
- External dependencies (Copilot CLI, SDK APIs) change

## Patterns

### Proposal Structure (docs/proposals/)

**Required sections:**
1. **Problem Statement** — Why current state is broken (specific, measurable evidence)
2. **Proposed Architecture** — Solution with technical specifics (not hand-waving)
3. **What Changes** — Impact on existing work (waves, milestones, modules)
4. **What Stays the Same** — Preserve existing functionality (no regression)
5. **Key Decisions Needed** — Explicit choices with recommendations
6. **Risks and Mitigations** — Likelihood + impact + mitigation strategy
7. **Scope** — What's in v1, what's deferred (timeline clarity)

**Optional sections:**
- Implementation Plan (high-level milestones)
- Success Criteria (measurable outcomes)
- Open Questions (unresolved items)
- Appendix (prior art, alternatives considered)

### Tone Ceiling Enforcement

**Always:**
- Cite specific evidence (user reports, performance data, failure modes)
- Justify recommendations with technical rationale
- Acknowledge trade-offs (no perfect solutions)
- Be specific about APIs, libraries, file paths

**Never:**
- Hype ("revolutionary", "game-changing")
Read the full skill on GitHub

Details

Skill name
architectural-proposals
Path
.squad/templates/skills/architectural-proposals/SKILL.md
License
MIT
Repo updated
10 April 2026

FAQ

What does the Architectural Proposals skill do?

How to write comprehensive architectural proposals that drive alignment before code is written

How do I install the Architectural Proposals skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add Azure-Samples/agent-skills-dotnet-demo --skill architectural-proposals. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Architectural Proposals popular?

It lives in Azure-Samples/agent-skills-dotnet-demo, which has 45 GitHub stars and 11 forks.

Related skills

Browse the most popular Claude skills, all writing & content skills, or write your own with the skills generator.