SkillFoxx

Architecture Copilot skill

An architecture coach skill: questions lead to ADRs, a diagram and a plan, and a repository is audited from its code

  • 90 ★ on the repository
  • Last commit
Skill

Minimal access

Why this level

  • The skill only leads a dialog and reads project files for analysis, changing nothing and making no network calls
All reasons and checks

study8677/architecture-copilotAuthor:study8677

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add skills/architecture-copilot

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Minimal accessThe tool runs nothing and makes no network calls.

  • The skill only leads a dialog and reads project files for analysis, changing nothing and making no network calls

This is third-party code. Review the repository files before installing.

What it does

The skill does not write code right away; it asks questions. It takes a new project through eight stages: a one-line framing, business and scope (what the version does not do), six questions on scale, read/write ratio, consistency, growth, failure cost and constraints, a back-of-envelope QPS and storage estimate, quality trade-offs, key decision forks and a counter-challenge. The output is an ASCII architecture diagram, a data model, ADR decision records, bottlenecks, an evolution path from MVP and an honest risk list. For an existing repository it gathers evidence first: entry points, core modules, data and migrations, deployment and CI, tests and the main data flow. Then comes an observed, inferred, unknown table with files and commands and the top three improvements with the highest leverage, each with verification, rollback and an ADR. The skill installs into `~/.claude/skills/` for Claude Code, as the `.cursor/rules/architecture-copilot.mdc` rule for Cursor and into `~/.codex/skills/` for Codex. Knowledge comes from the awesome-architecture repository.

Who it is for. Developers and tech leads starting a new system or taking over someone else's repository who want to think through the architecture before writing code.

Good fit when

  • A new product starts and you want to reach a diagram, data model and ADRs through a conversation
  • You are preparing for a system design interview and practice answers with load questions
  • You inherited an unfamiliar repository and need the three most useful changes with verification and rollback
  • The team wants architecture constraints as `AGENTS.md` and checks for agents

Not a fit when

  • You need finished module code: the skill asks first and does not hand out a solution
  • The question is narrow and local, such as fixing one function: a multi-stage interview is overkill
  • You expect a single right answer: the skill shows trade-offs and asks you to choose

Example request

I want to build a multi-user to-do app for small teams. Help me think through the architecture with questions

Limitations

  • The main README and skill text are in Chinese, with an English `README_en.md`, and the agent answers in the user's language.
  • Without reading real code, conclusions about an existing repository would be guesses, so the skill requires reading files and commands.
  • The number of system templates in the knowledge base depends on the awesome-architecture repository and may change.
  • The skill only leads the conversation and the analysis; the user makes architecture decisions.

How to disable. Delete `~/.claude/skills/architecture-copilot` or `~/.codex/skills/architecture-copilot`, or the `.cursor/rules/architecture-copilot.mdc` file from the project.

FAQ

How do I install Architecture Copilot?

For Claude Code copy the skill folder into `~/.claude/skills/`, for Codex into `~/.codex/skills/`, and for Cursor put the rules file into `.cursor/rules/`. The exact steps are in `INSTALL.md`.

What stages does the conversation have?

Eight stages from zero to seven: opening, business and scope, six questions, load estimate, qualities, key decisions, convergence and counter-challenge.

What does the skill do with an existing repository?

It reads entry points, modules, data, CI and tests, then returns an evidence table with files and the top three improvements with verification and rollback. It does not stop at summarizing the README.

Where does the skill get its knowledge?

From the companion awesome-architecture repository: a system design course and system templates. For each template `references/` holds key decisions, anti-patterns and evolution signals.

How do I check the skill quality?

Run `python3 scripts/check_quality.py`: it checks metadata, parity across Claude Code, Cursor and Codex and the evaluation cases in the `evals` folder.

Discussion

No questions or reviews yet.

Skills

lencx skills

lencx-skills

Two skills for Claude Code and Codex: keel works through architecture questions, coding-protocol keeps code edits inside the task

SkillMinimal access197

14 skills that find the gaps in a task before the code: interviews, plans, assumption tests and proof that a bug fix works

SkillMinimal access372

A skills library for Claude Code, Cursor and Codex: team code review, TDD, stacked PRs and repository readiness scoring

PluginExtended access71

Review skill with two viewpoints: the Right Brain checks architecture, the Left Brain checks contracts, memory lives in a file

SkillExtended access154

A skill that interviews you and writes requirements.md, design.md and tasks.md so Claude Code and Cursor work from one plan

SkillExtended access158

A skill that draws an interactive isometric map of a repository: buildings sized by real code, flows traced along real calls.

SkillExtended access386

README in short

The README explains why an architecture coach is needed, shows a sample dialog about a to-do app with a choice between OT and CRDT and a table of eight stages. A separate section covers reviewing an existing repository. Installation for three tools, the link to awesome-architecture and quality checks follow.

README badge

Original SKILL.md

---
name: architecture-copilot
description: >-
  引导式「架构共创」教练。当用户面对一个新项目 / 新系统、想在动手写代码前把架构想清楚时使用,
  也适用于系统设计面试练习、技术方案讨论、架构评审、现有方案读图,以及从真实代码和配置还原
  现有仓库架构、定位高杠杆改进。新系统以提问共创;现有仓库必须先取证、后判断。它不直接给方案,
  而是通过分阶段深度提问(一句话定位 → 业务范围 → 灵魂六问 → 信封背面估算 →
  质量属性取舍 → 关键决策追问 → 收敛产出 → 反挑战)引导用户收敛出:
  架构全景图、数据模型、ADR 决策记录、规模化瓶颈、演进路线、风险清单,
  并可把关键约束沉淀成 AGENTS.md / 适应度函数 / eval 门禁。方法论与案例知识源自
  awesome-architecture 的系统设计教程与数十个系统模板(具体数量以上游为准);
  本 skill 的 references/ 里为每个模板沉淀了「关键决策 / 反模式 / 演进信号」按需加载。
  触发词:设计架构、系统设计、技术方案、架构评审、架构体检、了解当前项目、读图、
  "我想做一个…该怎么设计"、system design、architecture review。
---

# Architecture Copilot · 架构副驾

> 你是一位资深的**架构教练**,不是代码生成器。
> 用户带着一个「想做的东西」或「已有方案」来,你的任务**不是直接甩出架构图**,
> 而是通过结构化深度提问,引导用户把约束、取舍、失败模式和演进路线想清楚。
> 本规范的方法论与案例来自 **[awesome-architecture](https://github.com/study8677/awesome-architecture)**。

---

## 何时使用 / 何时不要使用

**使用本 skill**:
- 用户要设计新系统、新产品、新模块,或做 system design 练习。
- 用户要讨论技术方案、架构选型、架构评审、现有架构图 / 文档的优缺点。
- 用户要了解当前代码仓库、还原真实架构、寻找高杠杆改进或判断技术债优先级。
- 用户说「我想做一个 X,该怎么设计」「帮我把架构想清楚」「这个方案会死在哪」。

**不要自动进入架构副驾模式**:
- 用户明确要写代码、修 bug、补测试、查 API、改 UI、跑命令,且没有架构讨论意图。
- 用户只问某个实现细节。可以短答,必要时只提醒「这是架构相关取舍」,不要强行走完整八阶段。
- 用户要求直接产出方案时,先说明「信息不足会影响判断」,但可以给**最小可用方案 + 明确假设**;不要无限追问。

**模板深度从哪来**:
- 优先读**本地 `references/`**:阶段 5 匹配到模板后,按映射表最后一列去读对应类别文件(每个模板有「关键决策 / 反模式 / 演进信号」三节)。这是离线可靠的深度来源。
- 需要完整 14 节模板(架构图 / 组件职责 / 数据流 / 数据模型 / 安全 / 参考原型)或端到端案例时,指引用户去上游 [awesome-architecture/templates](https://github.com/study8677/awesome-architecture/tree/main/templates) 的 `templates/<slug>/`——上游是唯一权威、始终最新。references 只有三节摘要、**没有现成架构图**;不要拿摘要拼凑或编造某个上游模板的图 / 数据模型充数。阶段 6 的 ASCII 图应根据**用户自己的约束现场共创**,而非复述模板里的图。
- 若 references 和网络都不可用,用下方映射表的必问决策 + 通用决策继续,不阻塞。
- 模板只是起点,不是答案。始终用用户的约束覆盖模板默认值。
- 审视现有代码仓库时,先读 `references/repository-review.md`;需要稳定产物时再使用 `assets/` 模板。

Report a problem