arch-design

Shape architecture, API, and service boundaries through phased analysis of requirements and trade-offs.

88|6|Updated Mar 25, 2026
One-click install
npx skills add https://github.com/heliohq/ship --skill arch-design-heliohq
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: arch-design
Source: https://github.com/heliohq/ship/tree/main/skills/arch-design
Command: npx skills add https://github.com/heliohq/ship --skill arch-design-heliohq

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you reason through architecture decisions before implementation, so system plans are grounded in requirements, constraints, and trade-offs instead of assumptions.

Core Features & Use Cases

  • Requirements analysis: Clarifies functional needs, non-functional goals, and constraints before proposing a solution.
  • System-level design: Breaks down components, data flow, APIs, storage choices, scaling, and failure handling.
  • Trade-off thinking: Compares alternatives and records why one approach wins, what it gives up, and what must be revisited later.
  • Use cases: Architecture reviews, ADR preparation, API planning, service boundary definition, and design docs for new or changing systems.

Quick Start

Ask the AI to analyze your architecture problem, work through the design phases, and hand off the final design to write-docs.

Frequently Asked Questions about arch-design

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

FAQPage Schema
How do I design system architecture and define service boundaries before implementation?

Design system architecture by performing a phased analysis of functional needs, non-functional constraints, component interactions, and data flow. This approach defines clear service boundaries and API plans by working through requirements and trade-offs before any code is written.

What is the best way to prepare an Architecture Decision Record with trade-off analysis?

The best way to prepare an Architecture Decision Record (ADR) is to compare architectural alternatives, explicitly recording why one approach wins and what constraints it gives up. This trade-off thinking ensures system plans are grounded in documented requirements rather than assumptions.

How do I plan APIs and component interactions for a scalable system?

Plan APIs and component interactions by analyzing system-level design elements like data flow, storage choices, and scaling requirements. This phased process clarifies how components communicate and handle failures, ensuring the API design supports complex system scalability.

Does this approach to system design work for reviewing existing architecture changes?

Yes, this system design approach works for architecture reviews and adapting changing systems. It applies to API planning and service boundary definition by re-evaluating non-functional goals, constraints, and failure handling against the new requirements.

Why do I need to analyze non-functional requirements before writing architecture docs?

You need to analyze non-functional requirements before writing architecture docs because they define the constraints and scaling capabilities of the system. Reasoning through these goals early ensures that component interactions and storage choices can handle expected loads and failures.

What's the best way to document assumptions and failure handling in system design?

Document assumptions and failure handling by working through a phased analysis of component interactions and system-level design. This process explicitly records what must be revisited later, ensuring architecture documents capture the full context of data flow and trade-offs.