architecture_skill

Overview

This skill guides high-level architecture documentation and system-structure analysis. It emphasizes interfaces, data flows, integration points, key design decisions, and failure modes while avoiding implementation details. Use it to create diagrams, API contracts, and concise architectural overviews for teams and stakeholders.

How this skill works

The skill inspects system boundaries, components, public interfaces, and major data flows to produce a concise architecture overview. It outputs component responsibilities, interface contracts, integration points, and identified failure surfaces, and recommends mermaid-style diagrams and API contract sketches. It intentionally omits low-level implementation specifics and algorithmic details.

When to use it

• Document a new system’s high-level design for onboarding or handoff
• Create component and sequence diagrams to communicate structure
• Analyze integration points and external system contracts
• Summarize key design decisions and tradeoffs for architecture reviews
• Identify likely failure modes and where to add resilience

Best practices

• Describe components by responsibility, not by internal code or functions
• Show data movement with diagrams (component and sequence) rather than step-by-step code
• Specify public APIs and data contracts crossing boundaries
• Call out error surfaces and recovery strategies explicitly
• Record rationale and tradeoffs for each major decision

Example use cases

• Produce an architecture overview for a microservices-based order processing system
• Define API contracts and data flow for a public-facing HTTP service
• Map integration with third-party auth, payments, and storage systems
• Draft a sequence diagram showing a client request through API → service → datastore
• List key reliability concerns and mitigation strategies before a production rollout