33-js-concepts 的 write-concept 技能：把文档写作规范、SEO 策略与质量清单变成机器可读的 AI 工作流

33-js-concepts 是一个收录 JavaScript 核心概念详解的开源文档项目，而 .opencode/skill/write-concept/SKILL.md（1444 行）是该项目为 AI 编码代理（OpenCode）编写的“编辑手册”：它规定了概念页面的目标读者、语气与用词红线、必须遵循的页面结构、完整的 SEO 优化策略、外链资源筛选标准，以及发布前的双层质量检查清单。读完本文，你可以掌握“把文档写作规范工程化为可执行 AI 技能”的完整做法：从 frontmatter 双标题模式、关键词簇布局、精选摘要（Featured Snippet）优化，到用 Vitest 测试验证文档代码示例的闭环流程。

write-concept 是什么

SKILL.md 的 frontmatter 定义了这个技能的名称与用途：

---
name: write-concept
description: Write or review JavaScript concept documentation pages for the 33 JavaScript Concepts project, following strict structure and quality guidelines
---

文档明确规定了四种触发场景：

• 在 /docs/concepts/ 下创建新的概念页面
• 重写或大幅改进已有概念页面
• 审阅现有概念页面的质量与完整度
• 为某个概念补充解释性内容

同时文档强调了目标读者画像：读者可能是从未写过代码的人，也可能是正在学习 JavaScript 的新手。写作要求对初学者保持共情，同时为中级开发者提供深度，并且“绝不能在没有链接到前置知识的情况下假设读者已有相关背景”。

技能集群定位：一个可编排的质量流水线

write-concept 并不是孤立的。从 opencode.jsonc 的配置可以看到，项目为 OpenCode 启用了 skill 工具，并以白名单方式放行 6 个项目级技能：

"tools": {
  // Enable the skill loading tool
  "skill": true
},
"permission": {
  // Skill permissions - allow all project skills by default
  "skill": {
    "write-concept": "allow",
    "fact-check": "allow",
    "seo-review": "allow",
    "test-writer": "allow",
    "resource-curator": "allow",
    "concept-workflow": "allow",
    // Default behavior for other skills
    "*": "ask"
  }
}

对应地，.opencode/skill/ 目录下有 6 个技能子目录，各自是一个职责单一的 SKILL.md：

技能	职责（摘自各自 SKILL.md 描述）
write-concept	撰写或审阅概念页面，遵循严格的结构与质量指南（本文主角）
resource-curator	寻找、评估、维护外链资源，审计失效与过时链接
test-writer	为文档中的代码示例生成 Vitest 测试
fact-check	核对代码示例与 MDN/ECMAScript 规范的一致性，防止传播错误信息
seo-review	对概念页面做 SEO 审计，优化搜索可见性与精选摘要
concept-workflow	端到端编排其余五个技能：资源筛选 → 概念写作 → 测试编写 → 事实核查 → SEO 审阅

从源码结构看，concept-workflow 把“写一篇合格的概念页”拆解成了五个可独立执行、又可串行编排的阶段。write-concept 处于这条流水线的第二步：它消费 resource-curator 筛选出的资源，产出符合结构与 SEO 规范的 MDX 页面，再交由 test-writer 生成测试、fact-check 与 seo-review 做终检。内容侧的落点则是 docs/concepts/ 与 docs/beyond/concepts/ 两个目录（核心概念与进阶概念），整站基于 Mintlify 构建，对应 package.json 中的脚本：

"scripts": {
  "test": "vitest run",
  "test:watch": "vitest",
  "docs": "cd docs && npx mintlify dev",
  "docs:build": "cd docs && npx mintlify build"
}

写作语气：让文字“听起来像人”

这是 SKILL.md 中最具差异化的部分：它把“避免 AI 腔”写成了一份可逐条执行的替换规则，而不是笼统的“要自然”。

五种语气要素

• Conversational but authoritative：像在给一个聪明的朋友解释
• Encouraging：让复杂话题显得可以接近
• Practical：聚焦真实应用场景与用例
• Concise：尊重读者时间，避免无谓冗长
• Question-driven：每个小节从读者会问的问题切入

禁用词替换表

文档给出了一张“AI 高频词 → 人类替代词”对照表，要求写作时逐条规避：

避免	改用
"Master [概念]"	"Learn [概念]"
"dramatically easier/better"	"much easier" 或 "cleaner"
"one fundamental thing"	"one simple thing"
"one of the most important concepts"	"This is a big one"
"essential points"	"key things to remember"
"understanding X deeply improves"	"knowing X well makes Y easier"
"To truly understand"	"Let's look at" 或 "Here's how"
"This is crucial"	"This trips people up"
"It's worth noting that"	直接陈述事实
"It's important to remember"	"Don't forget:" 或 "Remember:"
"In order to"	"To"
"Due to the fact that"	"Because"
"At the end of the day"	整句删掉
"In this section, we will"	直接开始解释
"As mentioned earlier"	删掉，或改为链接到对应小节

强调引导语的多样性

重复使用同一种引导语（如连续多个 "Key insight:"）是 AI 文本的典型指纹。文档给出了替换池：

不要反复使用	轮换使用
"Key insight:"	"Don't forget:"、"The pattern:"、"Here's the thing:"
"Best practice:"	"Pro tip:"、"Quick check:"、"A good habit:"
"Important:"	"Watch out:"、"Heads up:"、"Note:"
"Remember:"	"Keep in mind:"、"The rule:"、"Think of it this way:"

破折号（em dash）用量红线

AI 文本过度使用 em dash。文档给出的硬性标准是：一篇约 1500 词的文档，结构化章节之外的 em dash 超过 10-15 个就算滥用；写完后应全文搜索 “—” 逐个评估。改写示例：

滥用	更好
"async/await — syntactic sugar that..."	"async/await. It's syntactic sugar that..."
"understand Promises — async/await is built..."	"understand Promises. async/await is built..."
"Fails fast — if any Promise rejects..."	"Fails fast. If any Promise rejects..."

只有四类场景允许保留 em dash：Key Takeaways 编号列表（统一格式）、MDN 卡片标题（如 "async function — MDN"）、面试答案的分步解释、以及真正的自然插入语。

填充词与僵化措辞

两类“空转”词汇需要清除。第一类是不增加信息量的最高级与填充词：dramatically、fundamentally、incredibly、extremely、absolutely、basically（“如果你需要它，说明你没讲清楚”）、essentially、very、really、actually、In fact、Interestingly，处理方式基本都是删除或具体化。第二类是学术腔措辞，替换表包括：

僵化	口语化
"It should be noted that"	"Note that" 或直接陈述
"One might wonder"	"You might wonder"
"This enables developers to"	"This lets you"
"The aforementioned"	"this" 或再次点名
"Subsequently"	"Then" 或 "Next"
"Utilize"	"Use"
"Prior to"	"Before"
"In the event that"	"If"

克制的俏皮感

文档允许代码注释里出现一两句自然的人工痕迹，例如：

// ✓ 好：每个小节最多一句俏皮注释
// Callback hell - nested so deep you need a flashlight

// ✓ 好：口语化的插话
// forEach and async don't play well together — it just fires and forgets:

// ❌ 坏：用力过猛
// Callback hell - it's like a Russian nesting doll had a baby with a spaghetti monster!

// ❌ 坏：硬凹幽默
// Let's dive into the AMAZING world of Promises!

配套准则：每个主要小节一两句即可；幽默应从内容自然生长；正文避免表情符号；不要解释自己的笑话；如果俏皮句不成立，就直接陈述。

页面结构模板：唯一标准顺序

SKILL.md 给出了每一篇概念页必须严格遵循的 MDX 骨架，顺序不可调换：

1. frontmatter：三个字段 title（SEO 标题）、sidebarTitle（侧边导航标题）、description（150-160 字符的 SEO 描述，以动词开头）
2. 开场钩子：用让读者好奇的问题开头，并立即给出一个最小可运行的代码示例
3. <Info> 学习清单：列出 5-7 条“读完本文你将学到”
4. <Warning> 前置知识（可选）：紧接 Info 框之后，声明前置概念并链接到对应页面
5. 主体小节：各主要章节之间用 --- 水平线分隔；类比章节配 ASCII 艺术图
6. 核心概念：深水区内容，配合 <Steps>、<AccordionGroup>、<Tip> 等 Mintlify 组件
7. API/实现章节：Basic Usage 与高级模式两级代码示例
8. 常见错误章节：如 "The #1 Fetch Mistake"，用 WRONG/RIGHT 视觉对比加代码正误对照
9. Key Takeaways：8-10 条编号要点，收束全文
10. Test Your Knowledge：5-6 道折叠式问答（<AccordionGroup>）
11. Related Concepts：<CardGroup> 相关概念卡片
12. Reference：MDN 官方参考卡片
13. Articles：4-6 篇精选文章
14. Videos：3-4 个精选视频

仓库中的 docs/concepts/dom.mdx 是一份按此规范落地的实例，其开头与模板逐条对应：frontmatter 声明双标题与描述，正文以连环问题开场（"How does JavaScript change what you see on a webpage?..."），随后是极简代码示例、<Info> 七条学习清单、<Warning> 前置知识框，第一个 H2 直接以问句 “What is the DOM in JavaScript?” 承接搜索意图，并用加粗词组加 MDN 内联链接给出 40-60 词的定义段，接着是 DOM 家族树的 ASCII 图。

frontmatter 最小形态如下：

---
title: "Concept Name: [Hook] in JavaScript"
sidebarTitle: "Concept Name: [Hook]"
description: "SEO-friendly description in 150-160 characters starting with action word"
---

Mintlify 组件与图标约定

文档给出了组件使用速查表，约束了每个组件的职责边界：

组件	使用场景
<Info>	“What you'll learn” 框、Key Takeaways
<Warning>	常见错误、坑、前置知识
<Tip>	经验技巧、经验法则、最佳实践
<Note>	补充上下文、旁注
<AccordionGroup>	可折叠内容、问答区、可选深水区
<Tabs>	并排对比不同实现方式
<Steps>	顺序流程、编号工作流
<CardGroup>	资源链接（文章、视频、参考）
<Card>	带图标与链接的单个资源

卡片图标按内容类型固定：MDN/官方文档用 book，文章用 newspaper，视频用 video，课程用 graduation-cap，相关概念按语境选（handshake、hourglass、arrows-spin、sitemap 等）。ASCII 图则要求“带边框、带标题、带标注”，例如文档示例中的请求-响应循环图，把浏览器（YOU）与服务端（KITCHEN）画成两个方框，用箭头标注 REQUEST/RESPONSE，底部一句话点出 HTTP 是完成交换的协议。

SEO 体系：从关键词簇到精选摘要

SKILL.md 中占比最大的部分是 SEO 策略，核心立场是“每一个写作决策都要考虑搜索意图”，目标查询族包括 "what is [概念] in JavaScript"、"how does [概念] work in JavaScript"、"[概念] JavaScript tutorial"、"JavaScript [概念] example" 等。

关键词簇（Keyword Cluster）

每篇页面对应一个关键词簇，动笔前先识别：

关键词类型	模式	示例（DOM）
主关键词	[概念] + JavaScript	"DOM JavaScript"
What is	what is [概念] in JavaScript	"what is the DOM in JavaScript"
How does	how does [概念] work	"how does the DOM work in JavaScript"
How to	how to [动作] with [概念]	"how to manipulate the DOM"
Tutorial	[概念] tutorial/guide/explained	"DOM tutorial JavaScript"
对比	[概念] vs [相关概念]	"DOM vs virtual DOM"

文档还内置了四个现成的关键词簇样例，其中 Closures 一簇展示了完整形态：主关键词（"JavaScript closures"）、What is（"what is a closure in JavaScript"）、How does（"how do closures work in JavaScript"）、Why use（"closure use cases"）、Example（"closure examples"）、Interview（"closure interview questions JavaScript"）。Event Loop 与 Call Stack 两簇则额外包含 Visual 类查询（"event loop visualization"、"call stack explained"）和错误类查询（"call stack overflow JavaScript"、"maximum call stack size exceeded"）这类长尾意图。

双标题模式（Two-Title Pattern）

frontmatter 有两个标题字段，分工明确：title 是搜索结果显示的 <title> 标签，sidebarTitle 是侧边导航文案。规则如下：

---
title: "Closures: How Functions Remember Their Scope in JavaScript"
sidebarTitle: "Closures: How Functions Remember Their Scope"
---

• title 以 "in JavaScript" 收尾，做关键词后置
• sidebarTitle 去掉 "JavaScript"（反正整个站都是 JS 站点）
• 理想长度 50-60 字符（Google 会截断更长的标题），概念名放最前，后跟“钩子”（读者能理解或做到什么）
• 字数自检：<50 字符说明还可以加描述；50-60 最佳；>60 必须缩短

文档给出的完整示例对照表：

差标题	title（SEO）	sidebarTitle（导航）
"Closures"	"Closures: How Functions Remember Their Scope in JavaScript"	"Closures: How Functions Remember Their Scope"
"DOM"	"DOM: How Browsers Represent Web Pages in JavaScript"	"DOM: How Browsers Represent Web Pages"
"Promises"	"Promises: Handling Async Operations in JavaScript"	"Promises: Handling Async Operations"
"Event Loop"	"Event Loop: How Async Code Actually Runs in JavaScript"	"Event Loop: How Async Code Actually Runs"
"this"	"this: How Context Binding Works in JavaScript"	"this: How Context Binding Works"

Meta Description 公式

description 字段就是搜索结果里用户看到的摘要片段。规则：150-160 字符封顶；主关键词放前半段；空间允许时自然带 1-2 个次关键词；以动词开头（Learn、Understand、Discover，禁用 "Master"）；承诺具体价值；结尾留钩子。公式与示例：

[动词] [概念是什么] in JavaScript. [具体将学到的]：[主题1]、[主题2] 和 [主题3]。

概念	差（过短，低点击率）	好（150-160 字符）
Closures	"Functions that remember"	"Learn JavaScript closures and how functions remember their scope. Covers lexical scoping, practical use cases, memory considerations, and common closure patterns."
Event Loop	"How async works"	"Discover how the JavaScript event loop manages async code execution. Understand the call stack, task queue, microtasks, and why JavaScript is single-threaded but non-blocking."

长度自检：<120 字符是浪费空间，应补充细节；150-160 最优；>160 会被截断，需狠心删。

关键词布点与搜索意图

关键词必须出现在策略位置，但必须自然。优先级表：

优先级	位置	布点方式
关键	标题	主关键词在前半段
关键	Meta 描述	主关键词 + 1-2 次关键词
关键	首段	前 100 词内自然出现
高	H2 标题	疑问句式 + 关键词
高	“What you'll learn” 框	主题相关短语
中	H3 子标题	相关关键词与概念
中	Key Takeaways	自然强化主关键词
好	图片 alt 文本	如使用图片则含关键词

过度堆砌的警示信号：同一短语每 1000 词出现超过 3-4 次；句子读起来别扭；在代词更自然的位置硬塞关键词。

回答搜索意图有两条硬规则。其一是首段规则：每个 H2 之后的第一段必须直接回答隐含问题，不许铺垫。文档给出的反例是先用三段话讲“单线程特性”再引出事件循环；正例是首句直接定义 “The event loop is JavaScript's mechanism for executing code, handling events, and managing asynchronous operations...”。其二是疑问句 H2，让标题与搜索词同构：

搜索查询	使用的 H2
"what is the DOM"	## What is the DOM?
"how closures work"	## How Do Closures Work?
"why use promises"	## Why Use Promises?
"when to use async await"	## When Should You Use async/await?

精选摘要（Featured Snippet）四模式

精选摘要占据搜索结果第零位。文档定义了五种查询类型对应的内容结构：

查询类型	摘要格式	对应内容结构
"What is X"	段落	H2 后紧跟 40-60 词定义
"How to X"	编号列表	<Steps> 组件或 Markdown 编号列表
"X vs Y"	表格	列头清晰的对比表
"Types of X"	项目列表	描述性 H2 下的无序列表
"[X] examples"	列表或代码块	带简短说明的代码示例

四种获胜模式各配有可直接套用的范例：定义型（闭包 40-60 词定义，首句加粗关键词，解释 why 而非只说 what）、步骤型（fetch 四步，每步一个 <Step>）、对比型（== vs === 四行对比表加两行代码）、类型列表型（Global/Function/Block 三种作用域）。

倒金字塔与篇幅基准

内容组织遵循倒金字塔：前 100 词给答案（定义 + 核心概念），随后约 300 词讲机制并配图，再给代码证明，然后是边界情况与常见错误，最后才是延伸阅读。可扫描性元素各有明确用途：2-4 句短段落（降低跳出率）、三项以上用无序列表、“How to” 用有序列表、对比与参考数据用表格、关键词首次出现加粗、每个主要话题切换用 H2/H3。

篇幅基准表：

篇幅	评估	动作
不足 1000 词	太薄	增加深度、示例、边界情况
1000-1500 词	最低可用	简单概念可接受
1500-2500 词	良好	多数概念页标准
2500-4000 词	优秀	综合指南的理想区间
超过 4000 词	需评估	考虑拆分为多页

并附注：长度本身不保证排名，每节都必须增加价值，不许注水。

站内链接与 URL 规范

概念页之间应按“主题簇”互联，每个概念链接 3-5 个相关概念。文档内置了异步概念的簇图：Promises 居中，向下连接 async/await、Event Loop、Callbacks，再共同指向 Call Stack。链接放在三个位置：前置知识 <Warning> 框、正文自然上下文、Related Concepts 卡片区。锚文本要求描述性：不要用 "click here"、"here"、"read more"，而应写 "event loop guide"、"understanding the call stack" 这类含关键词的自然短语。

URL slug 规则：全小写、连字符分隔、3-5 词以内、包含主关键词、跳过停用词。对照示例：The Event Loop 用 event-loop 而非 the-event-loop；"this, call, apply and bind" 用 this-call-apply-bind。

代码示例与内联链接规范

代码示例六原则

1. 从最简单的示例起步：如“fetch 拿用户”只有三行，且注释写明这是“在 JavaScript 中 fetch 数据的方式”
2. 分步注释：复杂示例用 // Step 1: ...、// Step 2: ... 标出数据流动
3. 注释里写出预期输出：console.log(numbers.length) // 3
4. 用 ❌/✓ 标注正误模式：文档给出的经典案例是 fetch 错误处理。错误写法只 catch 了网络错误（404 不会进 catch），正确写法在解析前先检查 response.ok 并主动 throw，使网络错误与 HTTP 错误都进入同一个 catch
5. 有意义的变量名：const doubled = numbers.map(num => num * 2) 而非 const y = x.map(z => z * 2)
6. 由简入繁分级：Level 1 基础调用 → Level 2 带 options → Level 3 完整真实世界模式（含 Content-Type 头、失败抛错、返回 response.json()）

内联链接两条铁律

第一条：每引入一个新的 Web API、方法、对象或 JavaScript 概念，首次出现就链接到 MDN。文档给出了常见 MDN URL 的组织模式（按 Web/API、Web/JavaScript/Reference/Global_Objects、Web/HTTP 及方法与头子路径分类拼装），并示范了正确写法（加粗术语 + 首现即链）与反例（裸文本不链接）。

第二条：提到项目内其他概念页已覆盖的主题时，链接到对应概念页，例如在正文中引用 async/await 或 Promises 概念页，而不是只说“你应该先学那个”。

资源筛选标准与双层质量清单

外链资源：五标准 + 两句话描述公式

文章与视频必须同时满足五条质量标准：JavaScript 主题专属（C#、Python、Java 等资源一律排除，即使概念相似）、链接可访问、来源可靠、内容新鲜、技术准确（速读确认不教反模式）。

每条资源的描述必须具体，公式为：第一句说明该资源的独特之处或具体覆盖范围，第二句说明读者点击后能获得什么。文档给出了好坏对照：坏描述是 "Learn about Promises in JavaScript"、"A comprehensive guide to async/await"；好描述会点出独特内容，例如“文末附练习，检验重写 Promise 链的理解”、“用动画 GIF 展示调用栈、微任务队列与事件循环”。被点名的禁用描述套路包括 "Comprehensive guide to..."、"Great tutorial on..."、"Learn all about..."、"Everything you need to know about..."。

推荐来源分两张清单。文章侧：javascript.info（体系完整、维护勤、带练习）、MDN Web Docs（官方参考）、freeCodeCamp（新手友好）、dev.to 上的高信誉作者（图解见长）、CSS-Tricks（DOM 与浏览器 API 视觉向）。视频侧：Web Dev Simplified（清晰简洁）、Fireship（快节奏）、Traversy Media（综合速成）、Fun Fun Function（有人格的深挖）、Wes Bos（实战导向）。

入库前的五步验证：点链接确认可加载且不付费墙、速读内容确认准确、查看发布日期、读评论与社区反馈、如果资源含代码则实际运行验证。

发布前质量清单（六大类）

SKILL.md 用六组勾选清单收束整个流程。结构类：以提问钩子开场、开场后立即给简单代码示例、Info 框紧随其后、主要章节以 --- 分隔、有带 ASCII 图的现实类比、有“常见错误”章节、Key Takeaways 8-10 条、Test Your Knowledge 5-6 问、结尾顺序为 Related Concepts → Reference → Articles → Videos。链接类：新 API 首现即 MDN 链、相关概念链向 /concepts/slug、Reference 区多个 MDN 链接、4-6 篇文章、3-4 个视频。代码类：首个示例极简、复杂示例分步注释、注释带输出、正误模式用 ❌/✓、变量名有意义、由简入繁。内容质量类：为可能的新手写作、前置知识用 Warning 组件注明、表格承载速查信息、视觉概念配 ASCII 图。语言质量类：描述以 Learn/Understand 开头（而非 Master）、em dash 少于 15 个（结构化章节外）、无 AI 最高级、无僵化短语、强调模式轮换、俏皮句每节 1-2 句、无填充词、句子直接。资源质量类：链接全部验证可用、资源全部 JavaScript 主题、每条两句话具体描述、无过时资源。此外还有一份独立的 SEO 清单，覆盖标题与描述字数、关键词布点、首段回答规则、1500 词以上篇幅、精选摘要优化、3-5 个站内链接、slug 规范、外链与 MDN 链接有效性。

从文档到测试：用 Vitest 验证示例

SKILL.md 规定：文档里加入代码示例时，必须在 /tests/ 下创建对应测试，路径约定为 tests/{category}/{concept-name}/{concept-name}.test.js，模板形如：

import { describe, it, expect } from 'vitest'

describe('Concept Name', () => {
  describe('Basic Examples', () => {
    it('should demonstrate the core concept', () => {
      // Convert console.log examples to expect assertions
      expect(typeof "hello").toBe("string")
    })
  })

  describe('Common Mistakes', () => {
    it('should show the wrong behavior', () => {
      // Test the "wrong" example to prove it's actually wrong
    })

    it('should show the correct behavior', () => {
      // Test the "correct" example
    })
  })
})

这条要求与仓库现状完全吻合：vitest.config.js 以 tests/**/*.test.js 为收集范围，默认 Node 环境；tests/ 目录按“分类/概念/测试文件”三级组织（如 tests/fundamentals/call-stack/call-stack.test.js、tests/async-javascript/callbacks/callbacks.test.js），与 docs/concepts/ 的概念一一对应，且带 .dom.test.js 后缀的文件承载需要 DOM 环境的用例。配合 npm test（即 vitest run），文档作者可以把“示例注释里写的预期输出”转成断言，用测试证明文档说的行为真实成立，包括故意验证“错误示例确实会错”。这就是 write-concept 与 test-writer、fact-check 两个技能协同的落点：文档、测试、事实核查构成同一条质量链。

小结

.opencode/skill/write-concept/SKILL.md 展示的是一种可复用的方法论：把“写文档”这个模糊的软技能，拆解为 frontmatter 双标题模式、疑问句 H2、关键词簇布点、精选摘要四模式、破折号与填充词红线、Mintlify 组件职责表、资源五标准、双层勾选清单，以及 tests/ 下的可执行验证，全部写成 AI 代理可逐条执行的指令，并通过 opencode.jsonc 的权限白名单与 concept-workflow 的五阶段编排接入生产流程。对任何需要批量生产技术文档的项目而言，这套“规范即技能（spec-as-skill）”的组织方式，比单纯的人类可读 CONTRIBUTING 指南更能保证输出的一致性：规范不仅写在纸上，而且被执行者（AI）在每一步强制遵循。