Matt Pocock 实验性 - writing-beats

writing-beats：mattpocock/skills 方法论: in-progress/writing-beats，适用于工程实践、代码质量与开发流程优化。

Skill Documentation

Matt Pocock 实验性 - writing-beats

摘要

writing-beats：mattpocock/skills 方法论: in-progress/writing-beats，适用于工程实践、代码质量与开发流程优化。

> 来源: mattpocock/skills (141k stars) — Total TypeScript 创始人 Matt Pocock

> 类目: 实验性

> 原文件: skills/in-progress/writing-beats/SKILL.md

> 模型推荐: gpt-4.1 (代码工程)

这个 skill 是干嘛的

Matt Pocock (Total TypeScript, 141k stars) 沉淀下来的"日常代码工程动作"skill 模板。

每一个对应一个具体动作(代码评审 / TDD / 重构 / 文档对齐 / 任务交接),不是工具,是"该怎么干这件事"的工作流模板。

michael 强调"skill 要有相应的指导功能,指导用户使用",所以这里加了下面两节让 Agent 和用户对接。

---

🤖 Agent 使用说明

1. 接到任务后先按这个 skill 的检查清单走一遍

2. 清单里如果出现"先做 X 才能做 Y"的红线 → 必须先完成 X

3. 跑完清单后开始动手(改代码 / 写文档 / 评审)

4. 完工前用 `verification-before-completion`(superpowers) 或 `verification` 类 step 自检

5. 任务量大时考虑用 `dispatching-parallel-agents`(superpowers) 或 `wayfinder`(mattpocock) 拆解

👤 用户需要做什么?

1. 告诉 Agent 你要做什么(一句话即可)

2. Agent 跑 skill 清单时不要打断 — 它可能在收集上下文

3. 如果 Agent 主动问你"代码评审要不要安排一个 reviewer"等决策点 → 直接回答

4. 完工后让 Agent 跑一遍自检再交回

5. 整个过程 Agent 自动化,不需要手工介入

---

原 skill 内容(mattpocock/skills/in-progress/writing-beats/SKILL.md)

---

name: writing-beats

description: Writing, exploit — assemble raw material into a journey of beats, grounding each term before a beat leans on it.

disable-model-invocation: true

---

<what-to-do>

The user has passed (or will pass) a markdown file of raw material. This is **exploit**: the exploring is done, the pile is fixed — commit to a path through it and mine the pile to fill each beat.

If the user did not say where to save the article, ask once and remember the path.

Then run a beat-by-beat journey, choose-your-own-adventure style:

1. **Establish the prerequisites.** Before any beats, settle with the user what the audience already knows walking in — the concepts that are **grounded** from the start. Everything else must be grounded by a beat before a later beat can use it. See [Grounding](#grounding).

2. Write 2–3 candidate **starting beats**, drawn from the raw material. Each is a different entry point into the article. Each may only lean on grounded concepts; note what new concepts each one grounds. Show the user the beats before writing to the article file. The user picks one. Preview what beats that pick unlocks — as if the user is seeing a little way down the path.

3. Once the user picks a starting beat, write **only that beat** to the article file. A beat may be one sentence or several paragraphs — whatever that beat naturally is. Stop there.

4. Re-read the article file from disk. Then offer 2–3 candidate **next beats** — different directions the journey could pivot to from where the article now stands. Each must be reachable from the current grounded set; note what each one grounds.

5. Loop steps 3–5 until the article reaches a natural end.

</what-to-do>

<supporting-info>

Grounding

Every **concept** has to be **grounded** before a beat can lean on it: the audience either walked in knowing it or met it in an earlier beat. A beat that reaches for an ungrounded concept loses the reader — that is the one move the journey can't make. The unit is the concept, not the word for it: a beat can lean on an idea the reader lacks even with no jargon in sight. Where a concept has a name — a **term** — grounding it means landing the idea and the term together.

A concept gets grounded one of two ways:

• **Prerequisite** — grounded before the first beat. The audience brings it. Fixed at the start.
• **Introduced** — a beat establishes it, and from then on it's grounded for every later beat.

So each beat does two jobs: it **requires** concepts that are already grounded, and it **grounds** new ones. Keep a running list of what's grounded so far, and update it each time a beat lands.

This is what shapes the choose-your-own-adventure. A candidate beat is only reachable if everything it requires is already grounded; picking a beat that grounds concept X unlocks every beat that was waiting on X. When you offer next beats, they must all be reachable from the current grounded set — and say what each one grounds, so the user can see which paths it opens.

The big lever is what you make a prerequisite versus what you ground inside the piece. Demand too much up front and you shut out readers who don't have it; ground too much inside and the early beats drown in definitions. Settle this with the user when you establish prerequisites, and revisit it whenever a tempting beat turns out to require a concept nothing has grounded yet — the fix is either a grounding beat before it, or promoting the concept to a prerequisite.

What is a beat

A beat is one move in the journey. It does one thing — sets a scene, lands a point, asks a question, drops an aside, twists the angle. Then it stops, leaving the reader at a place where the next beat can pivot.

A beat is sized by what it needs:

• A single sentence if that's all the move is ("And then nothing happened for three weeks.").
• A short paragraph if the move needs setup.
• Multiple paragraphs if the beat is a self-contained vignette, argument, or example.

If a "beat" needs five paragraphs and three subheadings, it's not a beat — it's two beats glued together. Split it.

Pulling from the pile

Pull material from the raw pile to populate each beat. You can paraphrase, split, recombine, or quote. The pile is a quarry.

Ending the journey

The article ends when the journey is complete — not when the pile is empty. Most piles will have leftover fragments that don't make it in. That is fine; that is the point of having more raw material than you need.

Writing rhythm

• Append one beat at a time. Never write ahead.
• Re-read the article file from disk before every write. Preserve user edits absolutely.
• If the user edits a previous beat substantially, let it change what comes next.
• If the user says "rewrite that beat" or "go back and try a different beat 3", do it — edit in place, leave the rest alone.

</supporting-info>

常见问题（FAQ）

使用「writing-beats」这个 skill 能解决什么问题?

本 skill 专注于writing-beats，mattpocock/skills 方法论: in-progress/writing-beats。它将相关流程标准化，帮助用户更快拿到可靠结果，减少重复手工操作。

什么情况下适合使用「writing-beats」?

当你需要在writing-beats相关工作中获得稳定、可复用的产出时最适合——无论是单次任务还是纳入日常工作流，都能直接调用。

使用「writing-beats」前需要准备什么?

需要一个具体的项目或任务上下文，最好带有代码仓库或需求文档。