How to use the Epic Architecture Planner agent skill (breakdown-epic-arch)

What the skill makes the agent do

An agent skill is a folder containing a SKILL.md file. The file holds instructions that the agent loads when a request matches them. This skill, from the github/awesome-copilot repository, is a prompt for creating a high-level technical architecture for an epic based on its PRD. It is released under the MIT licence.

The agent works from the PRD you provide and produces a Markdown Epic Architecture Specification. The source describes the document as covering an overview of the technical approach, a Mermaid system architecture diagram, high-level features and technical enablers, the technology stack, a technical value rating (such as High, Medium or Low) with a justification, and a t-shirt size estimate (such as S, M, L or XL).

• Epic Architecture Overview: a brief summary of the technical approach.
• System Architecture Diagram: a Mermaid diagram organised into user, application, service, data and infrastructure layers.
• High-Level Features & Technical Enablers: what to build and what supporting services or infrastructure it needs.
• Technology Stack: the key technologies, frameworks and libraries.
• Technical Value and T-Shirt Size Estimate: a rating with reasoning, and a rough size.

Know the stack the skill assumes

The skill hard-codes a specific stack into its instructions. It refers to domain-driven architecture, self-hosted and SaaS deployment, Docker containerisation for all services, a TypeScript/Next.js stack with the App Router, Turborepo monorepo patterns, tRPC for type-safe APIs, and Stack Auth for authentication. The diagram guidance also mentions PostgreSQL, Qdrant, Redis and n8n.

This matters because the output will be steered toward these components. If your team uses a different stack, the draft may suggest technologies you do not use. The skill also tells the agent not to write code in the output except pseudocode for technical situations, so expect a document rather than an implementation.

Install the breakdown-epic-arch skill

Download the ZIP file for the skill from this page and unzip it. The skill folder contains SKILL.md. Put the folder in one of these locations:

• Personal: unzip into ~/.claude/skills/ so it is available across your projects.
• Project: unzip into the .claude/skills/ folder of a specific project so it is shared with that repository.
• Claude apps: upload the skill under Settings → Capabilities → Skills.

Check what you need before you start

The skill needs two things: a Product Requirements Document for the epic, either pasted into the chat or provided as a file, and a SKILL.md-compatible agent runtime. The source does not reference any separate software, libraries or API keys.

The skill's file list contains only SKILL.md. It does not run scripts and does not use the network, so it only shapes the agent's instructions.

• A written PRD for the epic (pasted or as a file).
• An agent runtime that reads SKILL.md skills, such as the Claude apps or Claude Code.
• Ideally, a team that already uses TypeScript/Next.js, Turborepo, tRPC and Docker.

Trigger the skill with a natural request

You do not need a special command. Describe the task in plain language and attach or paste your PRD. Naming the output helps the agent match the skill. The output is intended to be saved as arch.md under a folder named for the epic, so you can mention that path if you want the file laid out that way.

Review the draft section by section rather than accepting it whole. Ask the agent to revise any part that assumes components your team does not run.

• "Using the breakdown-epic-arch skill, create the architecture spec for this epic PRD: [paste PRD]."
• "Here is our PRD for the billing epic. Produce the high-level architecture, including the Mermaid diagram and a t-shirt size."
• "Draft the epic architecture for the PRD in this file and rate its technical value with a short justification."

Example: what a good result looks like

A useful output has all six sections in order, a diagram with labelled layers and both synchronous request paths and asynchronous flows where relevant, and a feature list that matches your PRD. Check that each enabler is justified by a feature. Check that the technology choices match your real stack, and remove any that do not.

Treat the t-shirt size and technical value as conversation starters. The skill gives no verified basis for them, so compare them with your own estimates.

• Confirm every feature in the spec traces back to a requirement in the PRD.
• Replace assumed technologies with the ones your team actually uses.
• Share the draft with colleagues and record decisions separately.

Tips for better results

The quality of the output depends mostly on the PRD. A clear, complete PRD gives the agent more to work with than a short summary. Keep the epic to one PRD at a time so the diagram stays readable.

• Give the full PRD, not a summary, so features and enablers are grounded in it.
• Say which parts of the stack are fixed and which are open to change.
• Ask for a revised version after colleagues review it, rather than editing a single long reply.