Architectural Proposals
How to write comprehensive architectural proposals that drive alignment before code is written
Install
npx skills add Azure-Samples/agent-skills-dotnet-demo --skill architectural-proposalsgit 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-proposalsPersonal 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")Details
- Skill name
architectural-proposals- Repository
- Azure-Samples/agent-skills-dotnet-demo
- 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
Agent Collaboration
45Azure-Samples/agent-skills-dotnet-demo
Standard collaboration patterns for all squad agents — worktree awareness, decisions, cross-agent communication
Agent Conduct
45Azure-Samples/agent-skills-dotnet-demo
Shared hard rules enforced across all squad agents
CI Validation Gates
45Azure-Samples/agent-skills-dotnet-demo
Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22
Docs Standards
45Azure-Samples/agent-skills-dotnet-demo
Microsoft Style Guide + Squad-specific documentation patterns
Writing Plans
43obra/clank
Create detailed implementation plans with bite-sized tasks for engineers with zero codebase context
Edit Guides Surveys
48amplitude/mcp-marketplace
Creates, edits, translates, and archives Amplitude Guides and Surveys through `run_amp`, including step content blocks, buttons, survey questions, and translations. Use before changing a guide's or survey's copy, steps, questions, buttons, targeting, settings, or translations.
Browse the most popular Claude skills, all writing & content skills, or write your own with the skills generator.