Agent skill

To Design

by smallnest in smallnest/goal-workflow

Generate a design document (design proposal) from a PRD, in the style of Go's official design proposals — Abstract / Background / Design / Rationale / Compatibility / Implementation, heavy on the…

MITAuto-check passedProduct & Project Management

Install To Design

skills CLI
$ npx skills add smallnest/goal-workflow --skill to-design -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install smallnest/goal-workflow to-design --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/smallnest/goal-workflow.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/to-design .claude/skills/to-design && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
to-design
GitHub stars
291
Token cost
~2.2k tokens
SKILL.md length
733 words
Files
1
Skills in repo
20
Repo updated
First seen
Licence
MIT

At a glance

Generate a design document (design proposal) from a PRD, in the style of Go's official design proposals — Abstract / Background / Design / Rationale / Compatibility / Implementation, heavy on the…

  • Works in 6 steps: Locate Input → Analyze Context (Optional) → Surface the Decisions → …
  • Design proposal
  • SKILL.md covers When to Use, The Job, Step 1: Locate Input and Step 2: Analyze Context…, plus 10 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

To Design is an agent skill from smallnest/goal-workflow. Generate a design document (design proposal) from a PRD, in the style of Go's official design proposals — Abstract / Background / Design / Rationale / Compatibility / Implementation, heavy on the 'why' and tradeoffs. Triggers on: to-design, prd-to-design, prd转设计文档, 生成设计文档, 写设计文档, design doc, design proposal, 设计提案, 技术设计文档.

Its SKILL.md is about 2.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Product & Project Management, covering PRD writing, Proposals and quotes and Architecture decision records. The repository describes itself as: AI-driven development workflow with /prd, /goal, /review-it and /ship-it skills. The licence is MIT.

When your agent uses it

  • Design proposal
  • Tasks that involve PRD writing
  • Tasks that involve Proposals and quotes

Example prompts

  • “/to-design”

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Locate Input
  2. Analyze Context (Optional)
  3. Surface the Decisions
  4. Design Document Structure
  5. Review & Iteration
  6. Save

What it can do on your machine

Read from SKILL.md and the folder at commit b06ab3c. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

To Design loads about 2.2k tokens when it runs. Until then it costs about 83 tokens; SKILL.md has 733 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~83
When it runs · the whole SKILL.md, loaded when a task matches
~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from smallnest/goal-workflow at commit b06ab3c, republished under its MIT licence (© smallnest). 733 words, ~2,193 tokens.

Download SKILL.mdSave it as .claude/skills/to-design/SKILL.md (or your agent's skills folder).
name
to-design
description
Generate a design document (design proposal) from a PRD, in the style of Go's official design proposals — Abstract / Background / Design / Rationale / Compatibility / Implementation, heavy on the 'why' and tradeoffs. Triggers on: to-design, prd-to-design, prd转设计文档, 生成设计文档, 写设计文档, design doc, design proposal, 设计提案, 技术设计文档.
user-invocable
true

to-design — PRD to Design Document

Turn a PRD (or a rough idea) into a design document written in the style of Go's official design proposals: plain language, concrete examples, and—above all—an honest account of why this approach and not the alternatives.

This is not the same as prd-to-spec. A SPEC is an implementation contract (tables, endpoints, schemas) for an engineer to build against. A design document is a decision artifact: it argues for an approach, surfaces the tradeoffs, and lets a team agree on the same facts before anyone writes code. When the question is "how should we build this and why", produce a design doc; when the question is "give me the exact contract to implement", produce a SPEC.

设计哲学源自对 5 篇 Go 官方 proposal(泛型 / 错误包装 / loopvar / slog / try)的分析。核心信念:文档的价值不取决于方案是否通过,而取决于它是否让讨论建立在同一套事实和取舍之上。


When to Use

  • A PRD exists and you need to decide how to build it before committing to implementation
  • The approach has real tradeoffs and you want them documented and debated
  • The change is risky, breaking, or hard to reverse (a design doc forces the compatibility conversation early)
  • Multiple people need to agree on a direction before work fans out
  • You want a durable record of "why we chose X and rejected Y" — even if the proposal is later rejected

If the team just needs the concrete contract to code against, use /prd-to-spec instead (or run to-design first, then prd-to-spec).


The Job

  1. Locate input — find or receive the PRD (or idea)
  2. Analyze context (optional) — scan the codebase for existing patterns, constraints, and prior art
  3. Surface the decisions — identify the real design forks and ask clarifying questions (max 3-5)
  4. Generate the design doc — following the structure and writing style below
  5. Review — present for feedback, especially on the Rationale and Compatibility sections
  6. Save — write to the agreed location

Step 1: Locate Input

Provide the PRD (or idea) to design from:

A. File path (e.g., tasks/prd-priority-system.md)
B. GitHub Issue URL
C. Paste content directly
D. Just describe the idea — I'll design from the conversation

A design doc can start from a half-formed idea, not only a polished PRD. If the input is thin, lean harder on Step 3.


Step 2: Analyze Context (Optional)

Skip for greenfield. Otherwise scan to ground the design in reality:

  • Existing patterns the design should match (naming, error handling, module boundaries)
  • Prior art — has something similar been tried or rejected here before?
  • Constraints — compatibility promises, public APIs, data the design can't break
  • Real pain — find the actual buggy/awkward code the design fixes, so Background can quote it

The most persuasive Background sections quote real code from the user's own repo, not hypotheticals.


Step 3: Surface the Decisions

A design doc lives or dies on its Rationale. Before writing, find the real forks in the road — the points where a competent engineer could reasonably go two ways — and resolve them.

Ask only about genuine forks:

Design decisions to settle before I write the doc:

1. Where does this logic live?
   A. Extend the existing X
   B. New standalone component Y
   C. Let me recommend based on the codebase

2. Is this a breaking change for existing callers?
   A. Yes — needs a migration path
   B. No — purely additive
   C. Unsure — I'll analyze and flag it

3. What's the one promise this design must keep? (e.g. backward compatibility,
   latency budget, no new dependencies)

For every fork, also note the option you are NOT choosing — that becomes the Rationale.


Show full SKILL.md (268 more words)Show less

Step 4: Design Document Structure

This is the standard skeleton distilled from the 5 Go proposals. Keep section names; drop sections that genuinely don't apply (and say why if the omission is notable).

markdown
Title: <一句话说清"做什么" —— 标题就是结论,不是名词短语>
Author(s): <作者>
Last updated: <YYYY-MM-DD>
Discussion at <issue / PR / 文档链接>   # 让文档不孤立,永远附讨论入口
Status: Draft | Under review | Accepted | Rejected

## Abstract / 摘要

一段话讲完全文:做什么、大致怎么做、以及**最重要的那个承诺**(如"向后兼容""不引入新依赖")。
读者读完这一段就该知道全貌。把隐含的核心约束埋在这里。

## Background / 背景与动机

用**具体、可感的例子**说明"痛在哪",而不是抽象地说"现状不好"。
- 能贴一段真实的 bug 代码 / 别扭的调用,就贴。先让读者"疼"起来。
- 量化痛点(出现频率、踩坑次数、损失),不要用形容词堆砌。
- 一句话给问题定性。

## Design / Proposal / 设计

文档主体。遵循三条:
- **从简单到复杂,渐进式教学**:从最小例子起步,复杂场景留到读者有直觉之后。
- **声明 + 示例 + 边界**三件套:每个 API/接口先给声明,再给用法片段,再划清适用边界。
- **改造前 vs 改造后对照**:能并排展示收益的,就并排展示。
能用一段可运行代码说清的,绝不用一段文字描述。

## Rationale / 理由与取舍

> Rationale = "为什么是这个方案,而不是别的"的论证。这是区分好文档和平庸文档的关键章节。

- 解释关键决策的动机。
- **主动列出被放弃的备选方案 + 放弃原因**("我们没选 X,因为 Y")。这比单方面论证你选的方案更可信,也避免后人重复讨论。
- 回应可预见的质疑。

## Compatibility / 兼容性

凡涉及破坏性变更,必须正面回应。
- 是不是破坏性变更?**开门见山承认**。
- 代价是什么(性能、行为变化、迁移成本)?**诚实列出**,不藏着。
- 渐进迁移路径(按模块/按文件 opt-in、灰度、特性开关)。
- 有先例佐证更好("某系统做过类似变更,结果平淡无奇")。

## Implementation / Transition / 实现与过渡

- 如何落地、分几步、配套什么工具。
- **用数据和工具支撑"可落地"**:实测失败率、灰度结果、自动化迁移工具,比任何"我们认为风险可控"都管用。
- 兼容老版本的过渡方案(如独立发布的兼容库)。

## Appendix / 附录(可选)

把会打断主线的细节后置:完整 API、端到端示例、FAQ。
FAQ 专门回应高频质疑("为什么叫这个名字""为什么不用某语言的做法""和 X 有何不同")。

Writing Style (照搬 Go 文档的文风)

Structure is the skeleton; style is the muscle. Enforce these — they're what make the doc readable.

Voice / 主语
  • 决策用 "我们 / We" — 把设计说成一群人可负责的选择,不是客观真理。("We propose…", "我们决定移除…")
  • 行为用代码本身当主语 — "this code has a bug" / "这段代码会…",让注意力落在程序上。
  • 说理对读者用 "你 / you" — 像面对面解释。
  • 禁止无主语的被动腔 — 不写"据建议应当…""It is suggested that…"这类推卸责任的句式。
Sentences / 句子
  • 判断用短句,论证用长句。先用一个极短的句子拍板("这段代码有 bug。"),再用信息密集的长句铺开机制。
  • 长短交替制造节奏。不要通篇绕来绕去的长句。
Paragraphs / 段落
  • 一段只讲一件事,观点放段首(结论先行)。
  • 小标题写成一句完整的论点,而不是名词短语。
    • 写 老代码不受影响,编译结果与之前完全一致,而不是 兼容性。
    • 读者光看标题就能读完整条论证链。
Tone / 语气
  • 克制的诚实,甚至自嘲。承认代价、承认自己也踩过坑,比形容词更有说服力。
  • 强调要省着用。全文只在最关键处加粗/斜体一次,反而最醒目。

Step 5: Review & Iteration

Present the doc and steer feedback to the sections that matter most:

设计文档已生成。重点请看这几处:

- Rationale:被放弃的方案和理由是否站得住?有没有遗漏的备选项?
- Compatibility:破坏性和代价是否如实说清?迁移路径可行吗?
- Background:痛点是否用具体例子讲清,而不是形容词?
- 文风:标题是否是"结论"而非名词?有没有无主语的被动腔?

回复 OK 保存,或给出修改意见。

Step 6: Save

设计文档保存到哪里?

A. tasks/design-[feature-name].md(紧挨 PRD,推荐)
B. docs/design/[feature-name].md
C. 自定义路径:[指定]

Mapping: PRD → Design Doc

PRD 部分Design Doc 部分转化方式
Problem / 背景Background找到真实的痛点代码/场景,量化它
Goals / 目标Abstract + Background提炼成"最重要的承诺"埋进摘要
User Stories / 需求Design转成渐进式的设计示例
Technical ConsiderationsDesign + Rationale约束 → 设计决策 + 取舍论证
Non-GoalsRationale写成"我们没做 X,因为 Y"
Risks / 风险Compatibility + Implementation风险 → 兼容性代价 + 迁移/灰度方案
隐含的备选方案Rationale显式列出并解释为何不选

Quality Criteria

A good design doc should pass these checks:

  • 标题是一句"做什么"的结论,不是名词短语,且附了讨论链接
  • 摘要里埋了最重要的承诺/约束
  • Background 用了具体例子或真实代码讲痛点,而非形容词
  • Design 遵循"声明 + 示例 + 边界",并有渐进式教学
  • Rationale 主动列出了至少一个被放弃的方案及原因(最关键的检查项)
  • 凡破坏性变更,Compatibility 都正面承认并列出代价
  • Implementation 用数据/工具支撑"可落地",而非空喊"风险可控"
  • 文风:决策用"我们"、行为用代码、无无主语被动腔;长短句交替;小标题是论点句
  • 没有 "TBD / TODO"——要么解决,要么挪进 Open Questions

Edge Cases & Fallback

场景处理
PRD 含糊不全在 Step 3 多问,把缺失项写进 Open Questions / 假设
没有真实痛点代码可引用最小可信的示例代码代替,并注明是构造的
没有备选方案可写强迫思考"最朴素的做法是什么、为什么不够"——总有一个被否决的基线
不是破坏性变更Compatibility 一句话说明"纯增量、无破坏",不必硬凑
方案最终被否决照样写好——记录"这条路为什么走不通"本身就是高价值产物,Status 标 Rejected
特性太大拆成多篇 design doc(按边界),互相链接
用户只要实现契约提示改用 /prd-to-spec,或先 to-design 再 prd-to-spec

Anti-Patterns to Avoid

  • 别只论证你选的方案。 不写被放弃的备选项,文档就少了一半价值。
  • 别用形容词讲痛点。 "现状很糟"没有说服力;一段真实的 bug 代码才有。
  • 别藏代价。 性能变慢、行为变化、迁移成本——都明说,再给迁移路径。
  • 别把标题写成名词。 "兼容性" → "老代码不受影响,编译结果完全一致"。
  • 别用无主语的被动腔。 决策要有人负责,主语用"我们"。
  • 别写成 SPEC。 设计文档讲"为什么这么选"和"取舍",不是字段级的实现契约。
  • 别因为方案可能被否就敷衍。 文档质量与提案是否通过无关。

Relationship to Other Skills

/prd  →  /to-design  →  /prd-to-spec  →  /goal  →  /review-it  →  /ship-it
 │            │               │              │
 │ 需求(what) │ 决策与取舍     │ 实现契约(how) │ 编码
 │            │ (why/which)   │
  • /prd 产出 PRD(本 skill 的输入)
  • /to-design 产出设计文档:论证方案、暴露取舍、对齐认知(本 skill)
  • /prd-to-spec 产出实现级 SPEC:字段、接口、schema 契约
  • /code-to-spec 从既有代码逆向出 SPEC(互补:正向 vs 逆向)

写设计文档的终极目的不是"说服别人同意你",而是"让所有人在同一个事实和取舍基础上做决定"。

© smallnest, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/to-design of smallnest/goal-workflow.

Open the folder on GitHubat commit b06ab3c

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders. This page covers the copy in smallnest/goal-workflow, which our catalogue first saw on October 7, 2026.

Compare with similar skills

To Design next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

To Design compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
To Design this skillsmallnest/goal-workflow291—~2.2kAutomated safety check: PassMIT
Frame A Proposalinkeep/open-knowledge4.5k—~3.6kAutomated safety check: PassGPL-3.0
Schematicblader/schematic241—~2.2kAutomated safety check: PassMIT
Tdoctornado-doc/tdoc103—~18kAutomated safety check: NotesAGPL-3.0
Shep Workstreamsshep-ai/shep264—~2.5kAutomated safety check: PassMIT
Write Update Tidb Docspingcap/docs616—~2.3kAutomated safety check: PassCustom licence

Similar skills

  • Frame A Proposal

    inkeep/open-knowledge

    Frame a new design proposal (RFC-shape) under proposals/ — problem before solution, named beneficiary and observable change, real alternatives, honest drawbacks, and a live open-questions backlog.

    4.5k GitHub stars~3.6k tokensUpdated today
    Sales & SupportAuto-check passed
  • Schematic

    blader/schematic

    Reverse engineer a detailed product and technical specification document from a git branch's implementation.

    241 GitHub stars~2.2k tokensUpdated 7 mo ago
    Product & Project ManagementAuto-check passed
  • Tdoc

    tornado-doc/tdoc

    Use tdoc by default to create, edit, publish, or share any document, even when tdoc is not mentioned.

    103 GitHub stars~18k tokensUpdated today
    Product & Project ManagementAuto-check: notes
  • Shep Workstreams

    shep-ai/shep

    A skill your agent uses when a large body of work (a version milestone, an epic, a roadmap, a set of PRDs/design docs) needs to be broken into parallel workstreams and executed with the shep CLI.

    264 GitHub stars~2.5k tokensUpdated yesterday
    Product & Project ManagementAuto-check passed
  • Write new TiDB documentation or update existing TiDB documentation from code changes, PRs, issues, design docs, product specs, rough drafts, existing docs, or short feature descriptions.

    616 GitHub stars~2.3k tokensUpdated today
    Product & Project ManagementAuto-check passed
  • App Spec Packager

    instructa/agent-skills

    A skill your agent uses when the user wants to turn an application, product, startup idea, SaaS, mobile app, web app, API, AI product, or internal tool into a production-ready Markdown specification…

    139 GitHub stars~1.5k tokensUpdated 12 days ago
    Product & Project ManagementAuto-check passed

More from smallnest/goal-workflow

All 20 skills in this repo
  • Article Icons

    smallnest/goal-workflow

    Illustrate an article (Markdown, HTML, etc.) with animated-style icons from itshover.com/icons.

    291 GitHub stars~1.6k tokensUpdated 27 days ago
    Auto-check passed
  • Graph

    smallnest/goal-workflow

    Graph engineering for parallel task execution: convert a task, PRD, SPEC, or issue set into a dependency graph (DAG), layer it into supersteps, then implement each independent node concurrently with…

    291 GitHub stars~3.9k tokensUpdated 27 days ago
    Auto-check passed
  • Walkthrough

    smallnest/goal-workflow

    Generate a Phase-2 Walkthrough artifact (walkthrough.md) once implementation and verification are complete.

    291 GitHub stars~4.7k tokensUpdated 27 days ago
    Auto-check: notes
  • Insight Diagram

    smallnest/goal-workflow

    为任意项目生成 UML 图、架构图和流程图。分析代码库后让用户选择要生成的图表类型,使用 architecture-diagram skill 渲染为 HTML+SVG,保存到 docs/ 目录。适用于任何软件项目的文档可视化。

    291 GitHub stars~1.6k tokensUpdated 27 days ago
    Auto-check passed
  • Code To Spec

    smallnest/goal-workflow

    Reverse-engineer a SPEC document from an existing project. An agent skill from smallnest/goal-workflow.

    291 GitHub stars~2.7k tokensUpdated 27 days ago
    Auto-check passed
  • Design It

    smallnest/goal-workflow

    A skill your agent uses when turning a requirement, spec, or feature brief into a single self-contained HTML design document in a fixed house style — one styled HTML page with a table-of-contents…

    291 GitHub stars~1.1k tokensUpdated 27 days ago
    Auto-check passed

Questions about To Design

What does To Design do?

Generate a design document (design proposal) from a PRD, in the style of Go's official design proposals — Abstract / Background / Design / Rationale / Compatibility / Implementation, heavy on the…. To Design is an agent skill from smallnest/goal-workflow. Generate a design document (design proposal) from a PRD, in the style of Go's official design proposals — Abstract / Background / Design / Rationale / Compatibility / Implementation, heavy on the 'why' and tradeoffs.

When should I use To Design?

To Design fits situations like: design proposal; tasks that involve PRD writing; tasks that involve Proposals and quotes.

How do I install To Design in Claude Code?

Run `npx skills add smallnest/goal-workflow --skill to-design -a claude-code`. Or copy the skill folder (skills/to-design in smallnest/goal-workflow) into .claude/skills/to-design in your project. Claude Code loads it when a task matches its description.

How do I install To Design in Codex?

Run `npx skills add smallnest/goal-workflow --skill to-design -a codex`. Or copy the skill folder (skills/to-design in smallnest/goal-workflow) into .agents/skills/to-design in your project. Codex loads it when a task matches its description.

Can I use To Design in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add smallnest/goal-workflow --skill to-design -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/to-design, .gemini/skills/to-design, .github/skills/to-design and .opencode/skills/to-design in your project.

What does To Design need to run?

SKILL.md names no scripts, command-line tools or credentials: To Design is instructions for the agent only.

Does To Design access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is To Design safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does To Design use?

To Design is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does To Design use?

About 2.2k tokens (SKILL.md is roughly 8.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to To Design?

Skills that share tags, products or a category with To Design: Frame A Proposal (inkeep/open-knowledge, 4.5k stars), Schematic (blader/schematic, 241 stars), Tdoc (tornado-doc/tdoc, 103 stars) and Shep Workstreams (shep-ai/shep, 264 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains To Design?

smallnest (a GitHub user) maintains it in smallnest/goal-workflow, which has 291 GitHub stars. The repository holds 20 skills in this directory. The repository was last updated on September 13, 2026.

Source: smallnest/goal-workflow on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.