Agent-Skills.md

Agent Skills: System Design

>-

UncategorizedID: s-hiraoku/synapse-a2a/system-design

Repository

s-hiraoku/synapse-a2a
s-hiraoku

Install this agent skill to your local

pnpm dlx add-skill https://github.com/s-hiraoku/synapse-a2a/tree/HEAD/.agents/skills/system-design

Skill Files

Browse the full folder contents for system-design.

Download Skill

Loading file tree…

.agents/skills/system-design/SKILL.md

Skill Metadata

Name
system-design
Description
>-

System Design

Guide architectural decisions and produce structured design artifacts.

When to Use

  • Designing a new system or major feature from scratch
  • Evaluating trade-offs between architectural approaches
  • Creating Architecture Decision Records (ADRs)
  • Reviewing existing architecture for scalability, reliability, or maintainability concerns
  • Decomposing a monolith or planning a migration

Workflow

Step 1: Clarify Requirements

Before designing, gather:

  1. Functional requirements - What must the system do?
  2. Non-functional requirements - Performance, availability, security, cost constraints
  3. Scope boundaries - What is explicitly out of scope?
  4. Existing constraints - Current tech stack, team skills, timeline

Ask the user to clarify any ambiguous requirements before proceeding.

Step 2: Identify Components

Break the system into components:

  • Data stores - What data exists? How is it accessed?
  • Services / modules - What are the logical units of work?
  • Interfaces - How do components communicate? (API, events, shared DB, files)
  • External dependencies - Third-party services, APIs, infrastructure

Step 3: Evaluate Alternatives

For each significant decision, document at least 2 options:

| Criterion | Option A | Option B | |-----------|----------|----------| | Complexity | ... | ... | | Scalability | ... | ... | | Operational cost | ... | ... | | Team familiarity | ... | ... |

Recommend one option with clear reasoning.

Step 4: Produce Design Artifact

Output a structured design document:

# Design: <Title>

## Context
[Problem statement and motivation]

## Requirements
- Functional: ...
- Non-functional: ...

## Architecture
[Component diagram or description]

## Key Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| ... | ... | ... |

## Data Model
[Schema or entity relationships]

## API Surface
[Key endpoints or interfaces]

## Risks & Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| ... | ... | ... |

## Open Questions
- ...

Step 5: Review Checklist

Before finalizing, verify:

  • [ ] Single responsibility per component
  • [ ] No circular dependencies between modules
  • [ ] Failure modes identified and handled
  • [ ] Data consistency model is explicit (strong vs eventual)
  • [ ] Security boundaries are defined
  • [ ] Observability points (logging, metrics, tracing) are planned

Principles

  1. Start simple - Add complexity only when requirements demand it
  2. Make trade-offs explicit - Every choice has a cost; document it
  3. Design for change - Interfaces should be stable; implementations should be replaceable
  4. Separate concerns - Data, logic, and presentation should not be entangled
  5. Fail gracefully - Design for partial failures, not just the happy path