企业官网建设流程全解析

📚second-brain-os是一个会用 AI 自我维护的第二大脑项目，内置了 18 个开箱即用的 Agent Skill（纯SKILL.md文件），配合 72 个斜杠命令，让 Claude Code 自动维护一个会自我组织的 Obsidian 知识库。这篇文章带你读懂这些 Skill 背后的编写方法——学完 5 个实战技巧，你就能为自己写出第一个SKILL.md。

一、先判断：什么任务值得写成 Agent Skill

不是每个任务都值得沉淀成一个 Skill。second-brain-os 官方给出的判断标准只有三条，Skills 与命令指南 的原文是：

一个值得写的 Skill 有三个特质：你反复做这件事、你对做法有观点、而且这些观点不显然到模型无法自己猜到。

反过来，以下任务不值得写：

• 一次性任务（做完就不做了）；
• 做法众所周知、模型默认就会做好的任务；
• 只需要改个参数就能覆盖的变体（那应该做成 Command，见文末）。

二、SKILL.md 完整结构：frontmatter + 五段式正文

每个 Skill 都是一个目录加一个文件，例如 skills/second-brain-ingest/SKILL.md。文件分两部分：

1. YAML frontmatter：name 和 description

--- name: my-skill-name description: >- 这个 Skill 做什么。什么时候该用它——写得大胆、主动，因为智能体会 少触发 Skill。不要用于哪些场景（把诱人的"近似场景"明确排除）。 ---

其中>-是 YAML 的块标量语法，表示"多行文本合并成一段"，在仓库的 18 个 Skill 中全部沿用。

2. 正文：五段式结构

官方推荐的结构骨架（docs/06-agents/skills-and-commands.md）：

三、技巧 1：description 写得"pushy"，把触发场景写全

官方直言："description 写得 pushy（主动），因为智能体天生会少触发 Skill。"看 second-brain-ingest 的 frontmatter 是怎么写的，它其实包含三层信息：

1. 做什么：把raw/里的原始素材变成带链接的 wiki 页面；
2. 触发词清单：用户把文件丢进raw/、粘贴文章/转录稿/PDF、说 "ingest this"、"add this to my second brain"、"process raw" 时都要用——即使用户没有点名这个命令；
3. 明确禁区：不用于回答 vault 里的问题、不用于 lint 修复、不用于编辑用户手写的笔记。

第 3 点最容易忽略。Skill 之间会"抢活"：ingest 的 description 里划出"不要用于回答问题"，query 的 description 里才敢写"任何问题都该从你自己的笔记里回答"。每个 Skill 把相邻场景排除干净，触发才稳定。

四、技巧 2：用"防止什么失败"开头，而不是罗列规则

正文第一行不是规则，而是一段"这个 Skill 为什么存在"。对比两个真实开篇：

• ingest（second-brain-ingest/SKILL.md）："只写总结页面的摄入，会让 vault 只长大、不变聪明。全部价值在后半程：把新素材和已有内容连起来。"
• query（second-brain-query/SKILL.md）："悄悄回退到通用知识的查询，是这个系统能做出的最有害行为。"

官方解释得很直白：规则覆盖你想到的情况，原因覆盖剩下的情况。

这也是官方反复强调的"解释 why"原则（docs/06-agents/skills-and-commands.md）：

"永远不要覆盖矛盾"会被字面执行，在边缘情况上翻车；而"永远不要覆盖矛盾，因为你相信过什么的轨迹，正是这个 vault 区别于搜索引擎的东西"能泛化到从没有描述过的场景。没有理由的 NEVER，通常说明解释缺失。

五、技巧 3：Core rule 写成一条"带边界"的底线

Core rule 只写一条，但要具体到能当边界。三个实例：

Workflow 紧随其后，用编号步骤展开，每一步以加粗动词领起。ingest 的 Workflow 是教科书式的示范（second-brain-ingest/SKILL.md）：先完整读完源文件再动笔 →先查已有页面（"向空 vault 摄入和向 300 页的 vault 摄入是两份不同的工作"）→ 写源页面 → 拆概念与实体 →双向加链接→ 同一次运行内更新index.md和log.md→ 汇报。

Output format 则是一个固定模板，让每次运行的产出可被肉眼验收：

Ingested: <source name> New pages: <n> (list) Updated pages: <n> (list) Links added: <n> Contradictions found: <none | description> Gaps created: <list of linked pages that do not exist yet>

六、技巧 4：Calibration 写"失败模式"，Example 写"可对照的一对"

Calibration专门回答规则没覆盖的灰度问题——通常会指出最常见的失败方向。例如 ingest 的校准（second-brain-ingest/SKILL.md）："过度提取是常见失败：一篇文章拆出十个薄页面，每个只是复述段落。一个来源通常只产出一到三个值得独立成页的概念。"

Example给一对具体输入输出："用户把一篇关于 LLM wiki 的文章丢进raw/，vault 里已有 Obsidian 和 Claude Code 两个页面 → 产出一篇源页面、一个新概念页、一个实体页、两个已有页面的更新、11 条新链接，并更新 index 与 log。"

有了这两节，Skill 才不只是流程说明书，而是一份"手感说明"。

七、技巧 5：Skill 管行为，Command 管入口，git 管版本

second-brain-os 把 18 个 Skill 放在 skills/、72 个 Command 放在 commands/，两者的分工值得直接抄作业：

• Skill = 行为：教会智能体一套可重复的做法，在相关时自动加载；
• Command = 入口：一个薄文件，指向某个 Skill 并设定作用范围。

看 commands/ingest.md 全文只有三行有效内容：一句任务描述 + 一句 "Follow thesecond-brain-ingestskill."。这就是官方说"比例是刻意的"（docs/06-agents/skills-and-commands.md）：行为集中在少数写好的 Skill 里，Command 很廉价，没必要让用户记住怎么措辞每周都要做的请求。

维护建议（同样来自官方文档）：

1. 随 vault 版本化：把 Skill 装进 vault 的.claude/skills/（团队共享），或装到全局~/.claude/skills/（个人使用），skills/README.md 给出了两种安装方式；
2. 用真实案例测过再上自动化：官方建议"用三四个真实案例测试 Skill，再交给定时任务"——每晚自动跑的 Skill 里的一个缺陷，一年后会变成三百页页面的缺陷；
3. 质量变了先查 diff：Skill 在 git 里，输出质量变化时，Skill 的 diff 是第一个要查的地方。

八、照着抄：18 个现成 Skill 是最佳教材

完整清单见 skills/README.md；配套的 Agent 角色定义（Ingestor、Linker、Reviewer 等六个角色，其中四个只读）在 agents/，想理解"为什么角色要拆细"值得一读 docs/06-agents/agent-roles.md。

最后总结：判断三问（重复做？有观点？不显然？）→ 套五段式结构（Why、Core rule、Workflow、Output format、Calibration + Example）→ description 写触发词和禁区 → 规则带理由 → 真实案例测过再上自动化。仓库本身就是一本 SKILL.md 教材，建议先通读 second-brain-ingest，再照着写出你的第一个。