# Generate Clear Software Architecture Documents

Architecture decisions often remain scattered across requirements, discussions, and diagrams. This skill organizes them into consistent Markdown documents for implementation and review.

## Install

```bash
npx skillstore add zl2023github/arch-doc-generation
```

## Metadata

- Status: approved
- Slug: zl2023github-arch-doc-generation
- Skillstore revision: r2
- Version status: missing
- Tree hash: 6a1e15086f8c85df18b179d60a0a34cb45b2e0fce06ffd38e29b8870cddb2cc4
- Author: zl2023github
- GitHub username: zl2023github
- License: MIT
- Repository: https://github.com/zl2023github/software-engineer-skills/tree/main/software-architecture/arch-doc-generation
- Ref: 88a8e9a07f4c54ab105c1c41b6267c287146b07b
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: external\_commands
- Quality score: 74
- Public page: https://skillstore.pages.dev/skills/zl2023github-arch-doc-generation
- Manifest: https://skillstore.pages.dev/api/skills/zl2023github-arch-doc-generation/manifest

## Capabilities

- Creates architecture design documents with background, principles, modules, data, security, deployment, and nonfunctional requirements.
- Structures technical proposals with technology choices, system flows, interfaces, implementation stages, and risk assessments.
- Produces API design documents covering protocols, authentication, versioning, endpoints, examples, and error codes.
- Documents deployment topology, availability, disaster recovery, monitoring, and alerting considerations.
- Formats outputs in Markdown with headings, tables, placeholders, and architecture decision records.

## Use Cases

- Prepare a system design review: Convert project requirements and constraints into a structured architecture document for stakeholder review.
- Define a service API: Document endpoint conventions, authentication, resources, request behavior, responses, and error handling.
- Plan a production deployment: Describe topology, availability, recovery, observability, security controls, and operational risks before release.

## Prompt Templates

### Create a basic architecture outline

```
Create a Markdown architecture outline for {{system_name}}. Include background, scope, key modules, data storage, deployment, security, and open questions.
```

### Draft an API design document

```
Write an API design document for {{service_name}}. Cover protocol, authentication, versioning, resources, endpoint behavior, pagination, errors, and example interactions.
```

### Develop a technical proposal

```
Develop a technical proposal for {{initiative}} using these requirements: {{requirements}}. Compare options, explain decisions, map core flows, identify risks, and propose delivery stages.
```

### Produce a complete architecture specification

```
Produce a review-ready architecture specification for {{system_name}} using {{context}}. Include C4 descriptions, module contracts, data flows, deployment, security, reliability targets, tradeoffs, ADRs, and unresolved decisions.
```

## Limitations

- It does not validate the proposed architecture against a running system or source code.
- It does not create PDF files without a separate PDF generation skill.
- It requires accurate requirements, constraints, and decisions to produce specific documentation.
- It provides document structure but does not replace security, reliability, or compliance review.

## Best Practices

- Provide business goals, scope, constraints, expected scale, and existing technology before requesting a document.
- Separate confirmed decisions from assumptions, alternatives, and unresolved questions.
- Review generated security, reliability, and operational claims with responsible specialists.

## Anti Patterns

- Do not present placeholders or inferred details as approved architecture decisions.
- Do not request a complete design without supplying system boundaries and measurable requirements.
- Do not treat generated diagrams or examples as proof that an implementation meets its targets.

## Security Audit

- Audited at: 2026-07-24T02:08:27.731\+00:00
- Summary: All nine static findings are false positives. Eight findings identify Markdown fences or inline code, while the entropy heuristic reflects readable Chinese documentation and structured templates. No executable commands, obfuscated content, prompt injection, or other semantic security issues were found.

## Stats

- Views: 0
- Downloads: 3
- Favorites: 0
- Popularity score: 0