我把自己的能力边界写进了 SKILL.md，才发现
一只阿木木约 27 分钟🛠️ 模块 11：自定义 Skill 开发
我把自己的能力边界写进了 SKILL.md，才发现升级这件事从来不是靠感觉的
——从「使用者」升级为「创作者」，写一个真正属于你自己的 SKILL.md
写在前面：当你学会写 Skill，你就掌握了这套系统的「源代码」
前十个模块，你一直是工具的使用者。
你使用 dbs-diagnosis，你调用 book-to-skill，你激活 obsidian-skills——这些工具都是别人写好的，你只需要学会触发它们。
模块 11 要做的，是让你成为创作者。
1 Agent Skills 是一个定义模块化、可复用 AI Agent 能力的开放规范，以自包含目录的形式存在。 1 它由 Anthropic 开发，于 2025 年 10 月 16 日公开发布；2025 年 12 月 18 日，该格式作为跨平台可移植的开放标准正式发布。
这意味着：你今天写的 Skill，可以在 Claude Code、Codex、Gemini CLI、GitHub Copilot 等 20 多个平台上运行。 你写的不是一个「Claude 专属工具」，你在为整个 AI Agent 生态做贡献。
但更重要的是：当你学会写 Skill，你就真正理解了整套工具链的底层逻辑——为什么 dbs-diagnosis 会在特定时刻触发？为什么 book-to-skill 能把 PDF 变成可查询的知识？为什么 obsidian-skills 能让 AI 读懂 Obsidian 的格式？
答案都在 SKILL.md 里。
当你能写出自己的 SKILL.md，你就从「使用系统」升级到了「设计系统」。
一、彻底理解 SKILL.md 的底层机制
1.1 SKILL.md 的本质是什么？
11 SKILL.md 本质就是一个增强版的 system prompt，但它有结构化的 frontmatter 让 Agent 知道什么时候触发、需要什么权限。
这个定义，隐藏了三个关键信息：
关键信息 1：「增强版 system prompt」
普通的 system prompt 是「永远在 context 里的」——不管你在聊什么，它都占着 token。SKILL.md 解决了这个问题：它只在被需要的时候才加载进来。
关键信息 2：「结构化的 frontmatter」
frontmatter 是 Agent 在启动时扫描的「目录」——Agent 不读正文，只读 frontmatter，从而知道「这个 Skill 叫什么、什么时候用它」。
关键信息 3：「知道什么时候触发」
这是整个 Skill 机制最精妙的地方——触发是自动的，不需要用户每次手动指定。当用户的请求匹配了 description 里描述的场景，Agent 自动加载对应的 Skill。
1.2 三层渐进加载架构
10 渐进加载架构把 Skill 信息组织成三个层级，每个层级在不同的上下文加载条件下激活。第一层是元数据（YAML frontmatter：名称、描述、版本、触发条件），在启动时预加载，约 30-100 token。
完整的三层架构：
text
Layer 1：元数据层（Agent 启动时扫描）
→ 只读 YAML frontmatter
→ 约 30-100 tokens/skill
→ Agent 知道：「有这个 skill，叫 X，描述是 Y」
Layer 2：指令层（Skill 被触发时加载）
→ 读取 SKILL.md 的 Markdown 正文
→ 约 500-5,000 tokens
→ Agent 知道：「这个 skill 具体怎么做，输出什么格式」
Layer 3：资源层（执行具体步骤时按需加载）
→ 读取 scripts/、references/、assets/ 目录
→ 约 2,000+ tokens/资源
→ Agent 知道：「这个步骤需要参考这个文件」
1 当被激活时，只有相关 skill 的指令会加载。你只为你使用的部分付费。这就是上下文效率。
这个架构告诉你写 SKILL.md 的核心原则：
text
能放 references/ 的，不要塞进 SKILL.md 正文
能用 description 触发的，不要让用户手动输入
能按需加载的，不要预先加载
1.3 发现机制：Skill 是怎么被找到的
6 Skill 从两个作用域被发现。项目级 Skill 在名称冲突时优先于全局 Skill。
Claude Code 的两个作用域：
text
全局 Skill（任何项目都能用）：
~/.claude/skills/{skill-name}/SKILL.md
项目级 Skill（只在当前项目可用）：
./.claude/skills/{skill-name}/SKILL.md
（在 ~/projects/my-project/.claude/skills/ 里）
实际用途：
text
全局 Skill：你的核心工具箱（dbs、obsidian、book-to-skill）
项目级 Skill：为某个特定项目定制的专属工具
比如：为「我的知识付费社群」专门写的
reading-to-atom skill
1.4 触发机制：Skill 是如何被激活的
9 显式触发：在提示词中直接引用 Skill。在 CLI/IDE 中，运行 /skills 或输入 $ 来提及一个 skill。隐式触发：Codex 可以在你的任务匹配 skill 描述时自动选择该 skill。由于隐式匹配依赖 description，请写清晰的 description，包含明确的使用范围和边界。
两种触发的设计哲学：
text
显式触发（你主动叫它）：
/my-skill
「提炼原子」
「用 reading-to-atom 处理这段文字」
隐式触发（它自己判断该出场）：
用户说：「把这段书摘转化成知识原子」
→ Agent 扫描所有 skill 的 description
→ 发现 reading-to-atom 的 description 匹配
→ 自动加载并执行
隐式触发的关键：description 是触发器，不是说明书。
15 写 description 时要像在聊天中向同事描述任务一样，用简单的词并包含用户实际会输入的名词。
二、SKILL.md 的完整格式规范
2.1 基础结构（必须掌握）
1 Skill 的核心是一个包含一个必要文件的文件夹：SKILL.md 文件有两个部分：包含元数据（name、description、version）的 YAML frontmatter，以及包含实际指令的 Markdown 正文。frontmatter 告诉 Agent 这个 skill 做什么以及何时使用它。正文告诉 Agent 如何做：输出格式、规则、约束和示例。
Markdown
---
name: skill-name
description: |
一句话核心描述（这里是触发器，Agent 在这里判断要不要用这个 skill）
触发条件：用户提到 X、Y、Z 时使用
关键词：词1、词2、词3
metadata:
version: "1.0"
author: "你的名字"
tags: [tag1, tag2]
---
# Skill 名称（正文从这里开始，只有被触发才加载）
## 核心任务
（这个 skill 做什么）
## 触发方式
（列出明确的触发命令和触发场景）
## 输出格式
（输出什么，格式是什么）
## 规则与约束
（必须遵守的规则，不做什么）
## 示例
（一个完整的输入→输出示例）
2.2 完整目录结构（进阶）
5 Skill 还可以打包脚本、参考资料、模板和其他资源。标准目录结构是：my-skill/（Skill 根目录）、SKILL.md（必须：元数据 + 指令）、scripts/（可选：可执行代码）、references/（可选：文档）、assets/（可选：模板、资源）。
text
my-skill/
├── SKILL.md ← 必须。元数据 + 核心指令
├── scripts/ ← 可选。可执行脚本（Agent 调用）
│ └── process.py
├── references/ ← 可选。参考文档（大文件放这里）
│ ├── methodology.md
│ └── examples.md
└── assets/ ← 可选。输出模板、图片等
└── output-template.md
什么内容放哪里的判断标准：
text
放 SKILL.md 正文：
- 核心工作流（步骤 1→2→3）
- 输出格式规范
- 关键规则（不超过 10 条）
放 references/：
- 大型知识库（超过 500 字的参考文档）
- 案例库（多个详细案例）
- 方法论文档
放 scripts/：
- 需要执行的代码逻辑
- 数据处理脚本
- 格式验证脚本
放 assets/：
- 输出模板（Markdown 模板文件）
- 图片、字体等静态资源
12 注意：触发条件必须写在 description 中，不要写在正文里（正文只在触发后才被读取）。
2.3 description 的写法：这是最重要的一行
2 如果你的 skill 无法触发，问题几乎从来不在指令里，而在 description。这才是大多数人后来才明白的事。
description 的四个必备要素：
YAML
description: |
[1] 一句话说清这个 skill 做什么（核心功能）
[2] 触发条件：用户提到哪些词/场景时使用
[3] 关键词：用户实际会输入的名词（不是你定义的名词）
[4] 边界：什么情况下不该用这个 skill
好的 description vs 差的 description：
YAML
# ❌ 差的 description（太抽象，无法触发）
description: |
A skill for processing knowledge.
# ❌ 差的 description（触发条件太窄）
description: |
当用户输入 /reading-to-atom 时，
把书摘转化为原子格式。
# ✅ 好的 description（清晰、有触发词、有边界）
description: |
把书摘、文章片段或阅读笔记，
转化为符合 atoms.jsonl 格式的知识原子，
并写入 Obsidian vault 的原子笔记目录。
触发条件：用户说「提炼原子」「把这段话变成原子」
「转化成 atom 格式」「阅读输入」时使用。
关键词：原子、atom、提炼、书摘、阅读笔记、转化。
不适用：用户只是想做笔记（用 obsidian-cli）；
用户想做商业诊断（用 dbs）。
9 前置关键用例和触发词，即使 description 被截短，Agent 也能匹配到这个 skill。
三、课节 11-1：读懂「官方 Skill」的源码——以 skill-creator 为范本
在写自己的 Skill 之前，最快的学习方式是直接读顶级 Skill 的源码。
19 skill-creator 是一个当用户想创建新 skill、构建自定义 skill、开发 CLI skill，或者想为 CLI 扩展新能力时应该使用的 skill。它自动化了从头脑风暴到安装的整个 skill 创建工作流。
Step 1：安装并读懂 skill-creator
Bash
# 安装 Anthropic 官方 skill-creator
git clone https://github.com/anthropics/skills.git ~/anthropic-skills
cp -r ~/anthropic-skills/skills/skill-creator ~/.claude/skills/
# 直接读源码（这是最好的学习材料）
cat ~/.claude/skills/skill-creator/SKILL.md
精读 skill-creator 的三个关键设计决策：
决策 1：它用「反转语言」描述规则
14 skill-creator 自身也遵循了一个原则——它的 SKILL.md 用了很大篇幅说「什么不该写」（What to Not Include in a Skill），而不是泛泛地说「写好内容」。
在你自己的 Skill 里，把正面指导改写成「不要做 X」的形式，通常更精确。
决策 2：祈使语气，没有模糊空间
14 skill-creator 要求 SKILL.md 的正文统一使用祈使语气/不定式形式。这不是美学偏好，而是为了减少歧义——祈使句天然就是指令。
Markdown
# ❌ 模糊的指令
可以考虑把内容分成多个步骤
# ✅ 精确的指令
把内容分成不超过 5 个步骤
每步骤以动词开头
决策 3：references/ 避免信息重复
14 最佳实践：避免重复——信息应该只存在于 SKILL.md 或 references 文件中，不能两边都有。详细信息优先放 references，SKILL.md 只保留核心流程指令和工作流指导。
Step 2：研究 dbskill 的路由器设计
dbs（路由器 Skill）是整个 dbskill 工具箱中设计最精妙的一个。读懂它，你就理解了「Skill 编排」的核心逻辑：
23 它的核心功能包括：识别用户的明确需求，立即转接到正确的 skill；对于模糊请求，用单问题菜单确认意图；以及在路由期间，提供简短的移交短语并触发相应的 skill。严格边界：不在此处执行诊断、分析或提供建议；不闲聊。
Bash
# 读 dbs 路由器的 SKILL.md
cat ~/.claude/skills/dbs/SKILL.md
路由器 Skill 的设计模式：
Markdown
---
name: dbs
description: |
dontbesilent 商业工具箱入口。
当用户有商业问题、想诊断、想拆解概念、
想做内容、想解决执行卡点时触发。
关键词：/dbs、商业、诊断、品牌、流量、变现
---
# DBS 商业工具箱路由器
## 唯一任务
搞清楚用户需要什么，然后路由到正确的 skill。
## 路由规则
| 用户意图 | 路由到 |
|---------|-------|
| 概念模糊、定义不清 | /dbs-deconstruct |
| 商业模式问题 | /dbs-diagnosis |
| 找对标、学对手 | /dbs-benchmark |
| 内容创作问题 | /dbs-content |
| 执行卡住了 | /dbs-action |
## 严格禁止
- 不在这里做任何诊断
- 不在这里给建议
- 不闲聊
- 不同时处理多个意图（问用户优先做哪个）
这个设计告诉你： 一个 Skill 只做一件事——连「路由器」也只做「路由」，不做诊断。
Step 3：对比三个不同类型的 Skill，理解设计差异
| dbs | ||
| dbs-diagnosis | ||
| book-to-skill | ||
| obsidian-markdown |
在写自己的 Skill 之前，先判断：你的 Skill 属于哪种类型？
四、课节 11-2：写你的第一个自定义 Skill——reading-to-atom
这是本模块的核心实战——写一个真正有用的、你会每天用到的 Skill。
场景： 你每次读书，都需要把书摘手动整理成原子笔记，格式要求严格（YAML frontmatter + 固定章节），很重复，很耗时。你想用一个 Skill 自动化这件事。
Step 1：四维思考框架（写之前必须做）
12 如果你有一个新需求，在动笔之前，请从以下 4 个维度进行思考，这将决定你的 SKILL.md 怎么写：触发条件（写在 description 中）；任务类型（严格步骤 vs 灵活发挥）；知识密度（核心流程 vs 大段参考文档）；输出目标（文档、代码、操作）。
reading-to-atom 的四维思考：
text
维度 1：触发条件
→ 用户说「提炼原子」「把这段话变成原子」「阅读转化」
→ 用户粘贴了一段书摘或阅读笔记
→ 用户说完 /book-to-skill 的查询后，想保存成原子
维度 2：任务类型
→ 需要严格的格式（YAML frontmatter + 固定章节）
→ 但核心观点的提炼需要灵活判断（不是按模板填空）
→ 结论：核心格式严格，观点提炼灵活
维度 3：知识密度
→ 核心流程简单（5步），放 SKILL.md 正文
→ 原子格式规范（详细），放 references/atom-format.md
→ 高质量原子的案例（3-5个），放 references/examples.md
维度 4：输出目标
→ 在 Obsidian vault 里创建一个 .md 文件
→ 触发：obsidian create 命令
→ 附加：更新书籍索引笔记
Step 2：建立目录结构
Bash
# 创建 Skill 目录
mkdir -p ~/.claude/skills/reading-to-atom/{scripts,references,assets}
# 目录结构
reading-to-atom/
├── SKILL.md ← 核心（马上写）
├── references/
│ ├── atom-format.md ← 原子格式规范（详细版）
│ └── examples.md ← 高质量原子示例
└── assets/
└── atom-template.md ← 原子笔记模板文件
Step 3：写 references/ 文件（先写参考文档，再写 SKILL.md）
这个顺序很重要： 先把详细规范写进 references/，才知道 SKILL.md 里该保留什么。
references/atom-format.md（原子格式规范）：
Markdown
# 知识原子格式规范 v1.0
## 必须字段（YAML Frontmatter）
```yaml
---
type: atom # 固定值，不可修改
id: 'YYYYMM_领域_序号' # 如 202606_retail_001
source: '书名 / 作者名' # 来源标注
topics: [主题1, 主题2] # 2-4个，用中文
skills: [关联的dbs-skill] # 可选，关联工具
atom-type: insight # insight/anti-pattern/framework/case
confidence: high # high/medium/low
date: YYYY-MM-DD # 创建日期
tags: [atom, 领域标签] # 必须包含 atom
---
必须章节（Markdown Body）
核心观点（一句话）
要求：
不超过 50 字 必须以动词或名词开头，不以「我」开头 删掉后，整个原子就失去了价值的那一句话
展开说明
要求：
2-4 句话 解释为什么这个观点成立 可以引用书中的具体例子
反直觉之处
要求：
1-2 句话 这个观点颠覆了什么常识？ 如果没有反直觉，填「暂无明显反直觉」
我的应用场景
要求：
具体的，不是「当我需要的时候」 格式：「当 [具体情况] 时，用这个原子来 [具体行动]」
关联原子
使用 wikilink 格式 3 条以内，质量优先于数量
text
---
**`references/examples.md`（高质量原子示例）：**
```markdown
# 高质量原子示例
## 示例 1：insight 类型
---
type: atom
id: '202606_retail_001'
source: 零售的哲学 / 铃木敏文
topics: [用户需求, 零售, 产品定位]
atom-type: insight
confidence: high
date: 2026-06-13
tags: [atom, retail]
---
# 潜在需求 vs 表达需求
## 核心观点（一句话）
顾客能表达的需求是已被满足过的需求；
真正的机会在于顾客说不出来但确实存在的那一层。
## 展开说明
表达需求是顾客已知的痛点，竞争者也都在满足它。
潜在需求是顾客感受到问题，但无法描述解决方案的部分——
这里是差异化的来源，也是护城河的起点。
## 反直觉之处
大多数市场调研收集的是表达需求，
但产品差异化来自潜在需求的发现——
这意味着：直接问用户「想要什么」，永远找不到真正的护城河。
## 我的应用场景
当我在做用户访谈，感觉答案都很平庸时，
用这个原子来提醒自己：
「他们说的不是他们想要的，我需要问他们在什么情况下感到卡住」。
## 关联原子
- [[原子-用户访谈的局限性]]
---
## 示例 2：anti-pattern 类型
（类似格式，但 atom-type: anti-pattern，
核心观点描述的是一种常见错误）
assets/atom-template.md（输出模板文件）：
Markdown
---
type: atom
id: '{{年月}}_{{领域}}_{{序号}}'
source: '{{书名}} / {{作者}}'
topics: [{{主题1}}, {{主题2}}]
skills: []
atom-type: {{insight|anti-pattern|framework|case}}
confidence: {{high|medium|low}}
date: {{今天日期}}
tags: [atom, {{领域}}]
---
# {{原子标题}}
## 核心观点（一句话）
{{不超过50字的核心洞见}}
## 展开说明
{{2-4句话，解释为什么成立}}
## 反直觉之处
{{1-2句话，颠覆了什么常识}}
## 我的应用场景
当 {{具体情况}} 时，用这个原子来 {{具体行动}}。
## 关联原子
- [[]]
Step 4：写核心 SKILL.md
有了 references/ 的详细规范，SKILL.md 就可以保持精简：
Bash
cat > ~/.claude/skills/reading-to-atom/SKILL.md << 'EOF'
---
name: reading-to-atom
description: |
把书摘、文章片段、阅读笔记或 book-to-skill 的查询结果，
转化为符合 atoms.jsonl 格式的知识原子，
并写入 Obsidian vault 的 02-Skills/atoms/ 目录。
触发条件：用户说「提炼原子」「把这段话变成原子」
「转化成 atom 格式」「阅读输入」「书摘提炼」时触发。
也在用户粘贴一段书摘/笔记并没有说明用途时，
主动询问「是否提炼成原子？」
关键词：原子、atom、提炼、书摘、阅读笔记、转化、insight。
不适用：用户只是想做普通笔记（改用 obsidian-cli create）；
用户想做商业诊断（改用 /dbs）；
用户想把整本书转化（改用 /book-to-skill）。
metadata:
version: "1.2"
author: "你的名字"
vault-path: "~/Documents/My-Vault"
atoms-dir: "02-Skills/atoms"
---
# reading-to-atom · 阅读转原子
## 核心任务
把任意阅读输入转化为一个高质量的知识原子，
写入 Obsidian vault，并更新相关索引。
## 五步工作流
### Step 1：识别输入类型
判断用户提供的是：
- 书摘（有明确来源）→ 直接提炼
- 阅读笔记（自己的想法）→ 提炼时区分「来源观点」和「个人解读」
- 查询结果（来自 book-to-skill）→ 注明查询来源
如果来源不明确，先问用户：「这段话来自哪本书/文章？作者是谁？」
### Step 2：提炼核心洞见
读取 references/atom-format.md 了解格式规范。
提炼原则：
- 核心观点必须一句话说完（不超过 50 字）
- 如果说不完，说明这段内容包含多个洞见——分成多个原子
- 原子类型判断：
- 正向洞见 → insight
- 常见错误 → anti-pattern
- 操作框架 → framework
- 真实案例 → case
### Step 3：确定原子 ID
格式：YYYYMM_领域缩写_序号
- 领域缩写：retail、content、biz、exec、life 等
- 序号：当月该领域第几个原子（检查已有原子）
```bash
# 检查当月已有的原子数
obsidian search tag="atom" property="date:2026-06*" | wc -l
Step 4：创建原子笔记
使用 assets/atom-template.md 模板，填入提炼结果：
Bash
obsidian create \
name="02-Skills/atoms/原子-{{标题缩写}}" \
template="atom-template"
确保：
所有 YAML 字段都填写完整 「关联原子」用 wikilink 格式 来源书名和作者名准确
Step 5：更新索引
如果这本书有对应的书籍笔记，追加记录：
Bash
obsidian append \
file="01-Books/{{书名}}/书籍笔记" \
content="- [[原子-{{标题}}]]（$(date +%Y-%m-%d)）"
更新原子数量属性：
Bash
obsidian property:set \
file="01-Books/{{书名}}/书籍笔记" \
name="atoms-count" \
value="{{新数量}}"
质量自检（输出前必做）
检查以下四项，全部通过才输出：
核心观点不超过 50 字 YAML frontmatter 所有必填字段都有值 atom-type 选择正确（insight/anti-pattern/framework/case） 至少有一条关联原子（哪怕暂时是空的 [[]]）
输出确认
创建完成后，告诉用户： 「原子已创建：02-Skills/atoms/原子-{{标题}}.md 类型：{{atom-type}} | 置信度：{{confidence}} 是否继续提炼下一段？」
严格禁止
不修改已有原子（除非用户明确要求） 不自动发布或分享原子内容 不在 SKILL.md 里放大段参考内容（已放入 references/） 一次只创建一个原子（不批量生成） EOF
text
---
### Step 5：测试你的第一个 Skill
```bash
# 验证 SKILL.md 语法
cat ~/.claude/skills/reading-to-atom/SKILL.md
# 启动 Claude Code，测试隐式触发
claude
# 测试 1：明确触发词
「提炼原子：铃木敏文说「顾客不是在买商品，
而是在买解决问题的方案」。来自《零售的哲学》。」
# 测试 2：隐式触发（粘贴书摘）
「『大多数创业者的问题不是执行力，
而是在用错误的指标衡量进度。』
——《精益创业》埃里克·莱斯」
# 测试 3：显式触发
/reading-to-atom 「定价不是你说值多少，
而是用户在那一刻认为值多少。」
来源：dontbesilent 推文
验收标准：
text
✅ 三种触发方式都能激活 Skill
✅ 每次都询问来源（如果用户没提供）
✅ 生成的原子笔记符合 atom-format.md 规范
✅ 自动更新书籍索引（如果能找到对应文件）
✅ 完成后询问「是否继续提炼下一段？」
五、课节 11-2 进阶：写一个「元 Skill」——weekly-review
掌握了基础 Skill 的写法后，进入进阶——写一个组合多个工具的元 Skill。
场景： 每周一，你想做一次完整的「周复盘」——但这需要：读取本周新增内容、更新项目诊断、生成知识摘要、提交 git、更新 Obsidian。这七八个步骤，你总是漏做某几个。
把这七八个步骤，封装成一个 weekly-review Skill。
Step 1：设计 weekly-review 的完整流程
text
每周一 weekly-review 触发后：
Phase 1：本周知识统计（2分钟）
→ 扫描本周新增原子数
→ 扫描本周新增书籍 Skill 数
→ 统计 Inbox 积压数量
Phase 2：项目诊断状态更新（5分钟）
→ 列出所有活跃项目（有 dbs-save 存档的）
→ 对每个项目，检查 next_actions 完成情况
→ 更新未完成的 action 的截止时间
Phase 3：本周知识图谱更新（3分钟）
→ 检查本周新增原子有没有加入 Canvas
→ 如果没有，自动补充
Phase 4：生成本周摘要笔记（5分钟）
→ 创建 System/WeeklyReview/YYYY-W{周数}.md
→ 包含：知识增量 + 项目进度 + 下周重点
Phase 5：Git 提交 + 清洁（2分钟）
→ git add . && git commit -m "weekly: 第X周复盘"
→ 清理 Inbox 中超过 7 天的未处理笔记
Step 2：写 weekly-review SKILL.md
Bash
mkdir -p ~/.claude/skills/weekly-review/references
Markdown
---
name: weekly-review
description: |
每周复盘 Skill。
在每周开始（通常是周一）执行一次完整的知识库复盘：
统计本周知识增量、更新项目状态、
生成周摘要笔记、提交 git 存档。
触发条件：用户说「周复盘」「weekly review」
「本周复盘」「每周整理」时触发。
关键词：周复盘、weekly、本周、复盘、整理知识库。
metadata:
version: "1.0"
vault-path: "~/Documents/My-Vault"
dbs-sessions: "~/.dbs/sessions"
---
# weekly-review · 每周知识库复盘
## 触发方式
- `/weekly-review`
- 「本周复盘」「周复盘」「weekly review」
## 执行前确认
告知用户本次 weekly-review 将执行以下操作，等待确认：
1. 扫描并统计本周知识增量（只读，安全）
2. 检查项目 next_actions 状态（只读）
3. 更新知识图谱（会修改 .canvas 文件）
4. 创建本周摘要笔记（会创建新文件）
5. Git commit（会提交到本地仓库）
6. 清理超过7天的 Inbox 笔记（会移动文件）
确认后开始执行。
## Phase 1：知识增量统计
```bash
# 本周新增原子数
WEEK_START=$(date -v-Mon +%Y-%m-%d 2>/dev/null || \
date -d "last Monday" +%Y-%m-%d)
obsidian search \
property="type:atom" \
property="date:>=$WEEK_START" | wc -l
# 本周新增书籍 Skill 数
ls ~/Documents/My-Vault/01-Books/ | wc -l
# Inbox 积压
obsidian search tag="needs-review" | wc -l
输出格式： 「📊 本周知识增量 新增原子：X 个 书籍 Skill：Y 个（累计） Inbox 积压：Z 个」
Phase 2：项目状态检查
读取 references/project-check-template.md 了解检查流程。
对每个 ~/.dbs/sessions/ 下的活跃项目：
读取最新存档文件 提取 next_actions 列表 询问用户每个 action 的完成状态
输出格式： 「📋 [项目名] Action 1：[描述] → ✅ 已完成 / ⬜ 未完成 / ⏭ 推迟 Action 2：...」
Phase 3：知识图谱更新
Bash
# 检查本周新增原子是否在 Canvas 里
# 如果不在，提示用户更新
obsidian read file="System/Canvas/Skill-Stack-全景图.canvas"
对每个不在 Canvas 里的新原子，询问： 「原子「{{名称}}」尚未加入知识图谱，是否添加到 [集群名] 集群？」
Phase 4：生成本周摘要笔记
Bash
WEEK_NUM=$(date +%V)
YEAR=$(date +%Y)
obsidian create \
name="System/WeeklyReview/${YEAR}-W${WEEK_NUM}" \
content="---
type: weekly-review
week: ${YEAR}-W${WEEK_NUM}
date: $(date +%Y-%m-%d)
tags: [weekly-review, system]
---
# ${YEAR} 第 ${WEEK_NUM} 周复盘
## 知识增量
- 新增原子：X 个
- 书籍 Skill：Y 个
## 项目进度
（自动填入 Phase 2 的结果）
## 本周最有价值的一个原子
（用户填写）
## 下周最重要的一件事
（用户填写）
"
Phase 5：Git 提交 + 清洁
Bash
# 提交 Vault 变更
cd ~/Documents/My-Vault
git add .
git commit -m "weekly: ${YEAR}-W${WEEK_NUM} 复盘完成"
# 提交 dbs 存档
cd ~/.dbs
git add .
git commit -m "weekly: ${YEAR}-W${WEEK_NUM} 项目状态更新"
# 移动超过7天的 Inbox 笔记
# （列出候选，等用户确认后执行）
完成后输出
「✅ YEAR−WYEAR−W{WEEK_NUM} 周复盘完成
摘要笔记：System/WeeklyReview/YEAR−WYEAR−W{WEEK_NUM}.md Git 已提交 耗时：约 15 分钟
下周见 👋」
严格禁止
不在用户确认前执行任何写操作 不删除任何文件（只移动） 不修改 dbs-save 的存档内容
text
---
## 六、Skill 迭代优化的四个阶段
### 阶段 1：能用（v0.1）
第一版 Skill，能触发，输出大致正确。这就够了。
**常见的第一版问题：**
description 太模糊，触发率低 输出格式不稳定 对边界情况没有处理 references/ 里的内容太多或太少
text
**验证方法：**
```bash
# 测试 10 种不同的触发方式，看哪些能正确激活
# 10次中能激活 7 次以上 = 基本合格
阶段 2：稳定（v1.0）
description 精准，输出格式一致，边界情况有处理。
提升关键：description 的 A/B 测试
Bash
# 版本 A：动词触发
description: "当用户要提炼原子、转化书摘时触发"
# 版本 B：名词触发
description: "原子、atom、提炼、书摘、阅读笔记"
# 版本 C：场景触发
description: "用户粘贴了一段书中文字，想永久保存这个洞见"
实际测试三个版本，记录触发成功率，选最高的。
阶段 3：高效（v1.5）
添加 scripts/ 脚本，自动化重复操作。
Python
# scripts/generate-atom-id.py
# 自动生成不重复的原子 ID
import os
import re
from datetime import datetime
ATOMS_DIR = os.path.expanduser("~/Documents/My-Vault/02-Skills/atoms/")
def get_next_id(domain: str) -> str:
"""获取某个领域下一个可用的原子 ID"""
prefix = datetime.now().strftime("%Y%m")
pattern = rf"{prefix}_{domain}_(\d+)"
existing_ids = []
for filename in os.listdir(ATOMS_DIR):
match = re.search(pattern, filename)
if match:
existing_ids.append(int(match.group(1)))
next_num = max(existing_ids, default=0) + 1
return f"{prefix}_{domain}_{next_num:03d}"
if __name__ == "__main__":
import sys
domain = sys.argv[1] if len(sys.argv) > 1 else "misc"
print(get_next_id(domain))
在 SKILL.md 里引用这个脚本：
Markdown
### Step 3：生成原子 ID
运行脚本获取不重复的 ID：
```bash
python3 ~/.claude/skills/reading-to-atom/scripts/generate-atom-id.py {{领域}}
text
---
### 阶段 4：可分享（v2.0）
加入 README.md，完善边界文档，可以给别人用了。
<!--citation:27-->一个完整的可分享 Skill 应包含：SKILL.md、README.md、LICENSE，以及 references/、scripts/ 目录。SKILL.md 必须包含元数据（名称、描述），遵守大小限制，并使用 references/ 存放扩展内容。
```bash
# 添加 README.md
cat > ~/.claude/skills/reading-to-atom/README.md << 'EOF'
# reading-to-atom
把书摘、阅读笔记转化为 Obsidian 知识原子。
## 安装
```bash
npx skills add https://github.com/你的账号/my-skills --skill reading-to-atom
使用
触发方式：「提炼原子」「把这段话变成原子」/reading-to-atom
输入：一段书摘或阅读笔记（带来源信息） 输出：格式规范的 Obsidian 原子笔记（写入 vault）
依赖
Obsidian（需打开） obsidian-cli 插件（需启用） 标准 vault 目录结构（02-Skills/atoms/）
版本历史
v1.0：基础原子创建 v1.2：添加书籍索引自动更新 v2.0：添加 ID 自动生成脚本 EOF
text
---
## 七、发布你的 Skill：让更多人用到它
### 7.1 发布到 GitHub
```bash
# 初始化 Skill 仓库
cd ~/.claude/skills
git init my-skills
cd my-skills
# 复制你的 Skill
cp -r reading-to-atom ./
cp -r weekly-review ./
# 提交并推送
git add .
git commit -m "feat: 初始化个人 Skill 仓库"
git remote add origin https://github.com/你的账号/my-skills.git
git push -u origin main
7.2 让别人可以一键安装
Bash
# 别人可以用这个命令安装你的 Skill
npx skills add https://github.com/你的账号/my-skills --skill reading-to-atom
# 或者安装全部
npx skills add https://github.com/你的账号/my-skills --all
3 这意味着你构建的 Skill 在 OpenAI Codex、Gemini CLI、GitHub Copilot、Cursor、VS Code 以及其他采用该标准的超过 20 个平台上都能完全工作。
7.3 提交到 LobeHub Skills Marketplace
25 LobeHub 提供了发现、安装、配置和管理 Skill 的完整平台——这些工具和集成扩展了你的 Agent 能做的事情。
Bash
# 提交到 LobeHub marketplace
npx @lobehub/market-cli skills submit \
https://github.com/你的账号/my-skills/tree/main/reading-to-atom \
--description "把书摘转化为 Obsidian 知识原子"
# 查看提交状态
npx @lobehub/market-cli skills status reading-to-atom
八、常见问题深度解析
Q1：Skill 写好了，但就是不触发，怎么排查？
text
排查顺序：
Step 1：检查 description 的触发词
→ 用户实际输入的词，在 description 里出现了吗？
→ 如果没有，添加进去
Step 2：检查 SKILL.md 文件位置
→ ~/.claude/skills/skill-name/SKILL.md
→ 文件名必须全大写 SKILL，扩展名小写 .md
Step 3：检查 YAML frontmatter 语法
→ 用 yaml linter 检查：echo "$(cat SKILL.md | head -20)" | python3 -c "import yaml,sys; yaml.safe_load(sys.stdin)"
→ 常见错误：多余的空格、冒号后面没有空格
Step 4：重启 Claude Code 会话
→ 新会话才会重新扫描 skills 目录
→ 修改 SKILL.md 后，必须重开会话
Step 5：显式触发测试
→ /skill-name 明确触发，看 Skill 是否被加载
→ 如果显式触发成功，问题在 description 的隐式匹配
Q2：SKILL.md 写了很多内容，但 AI 好像没有严格遵守，怎么办？
16 SKILL.md 应当作为 Skill 的入口和导航，而不是一个包罗万象的大文件。详细的参考资料、示例、脚本或文档应拆分成独立文件，从而减轻模型初次加载的负担，让信息按需流动。
text
解决方法：
1. 精简 SKILL.md 正文
→ 正文超过 3,000 字，AI 很难记住所有规则
→ 把详细内容移到 references/ 目录
2. 用「不要做 X」替代「应该做 Y」
→ 禁止语言比建议语言更容易被遵守
3. 关键规则放最前面
→ SKILL.md 正文的前 500 字，是被遵守最好的部分
4. 减少规则数量
→ 10 条规则：AI 能记住 3-5 条
→ 5 条规则：AI 能记住 4-5 条
→ 规则少，每条的权重就大
Q3：我的 Skill 需要读取大量参考文档，但又不想每次都加载，怎么做？
6 资源应该只在 Agent 明确需要它们来完成某个步骤时才加载 scripts/、references/ 和 assets/ 的内容。永远不要预先加载所有资源。
Markdown
# 在 SKILL.md 里用「按需读取」指令：
## 格式规范
参考 references/atom-format.md 了解完整格式规范。
仅在需要验证格式时读取，不要在开始前预加载。
## 示例
如需查看高质量原子的示例，读取 references/examples.md。
仅在用户询问示例时读取。
Q4：写自己的 Skill 和直接把规则写进 CLAUDE.md 有什么区别？
text
写进 CLAUDE.md：
- 永远在 context 里（消耗 token）
- 不能按需加载
- 不能跨工具使用
写成 Skill：
- 只在需要时加载（节省 token）
- 可以跨 Claude Code / Codex / Gemini 使用
- 可以分享给别人
- 可以版本管理
结论：
CLAUDE.md 放「永远需要的核心规则」（20 行以内）
Skill 放「特定场景需要的专业能力」
九、模块 11 作业：提交标准与验收
Markdown
═══════════════════════════════════════════
📋 模块 11 作业清单
═══════════════════════════════════════════
【必交作业】
□ 1. 精读两个官方 Skill 的源码
要求：
- skill-creator（来自 anthropics/skills）
- dbs（来自 dontbesilent2025/dbskill）
提交：
- 两个 Skill 各写 3 条「我学到的设计决策」
- 说明为什么这个设计是好的
□ 2. 完成四维思考框架
对你要写的 Skill，完整填写四维思考：
触发条件、任务类型、知识密度、输出目标
提交：填写完整的四维思考表格
□ 3. 建立完整的 Skill 目录结构
要求：
- SKILL.md（符合规范）
- references/（至少一个参考文档）
- assets/（至少一个模板）
提交：目录结构截图
□ 4. 完成 SKILL.md 的完整编写
要求：
- frontmatter 字段完整
- description 包含触发条件、关键词、边界
- 正文使用祈使语气
- 有「严格禁止」章节
提交：SKILL.md 全文截图
□ 5. 完成三种触发方式测试
要求：显式触发、隐式触发、口语触发各测一次
提交：三次测试的对话截图
□ 6. 完成一次完整的 Skill 使用记录
用你写的 Skill 处理一个真实输入
提交：输入内容 + 输出结果截图
□ 7. 推送到 GitHub
提交：GitHub 仓库链接
【选交作业（加分）】
○ 8. 完成「Skill 迭代」
从 v0.1 迭代到 v1.0
记录：发现了什么问题，如何修复
提交：两个版本的 description 对比
○ 9. 写一个「元 Skill」（组合多个工具）
比如 weekly-review 或其他组合工作流
提交：SKILL.md + 一次完整执行记录
○ 10. 发布到 LobeHub 或 awesomeskill.ai
提交：发布链接 + 安装命令截图
═══════════════════════════════════════════
【作业提交格式】
1. SKILL.md 全文截图（必须清晰可读）
2. 三次触发测试截图
3. 完整使用记录截图
4. GitHub 仓库链接
5. 一段文字（300字）：
「我写的 Skill 解决了什么痛点，
四维思考中最难想清楚的是哪个维度，
写完第一版后发现了什么意料之外的问题，
如果让我给一个月前的自己一个建议，我会说___」
文件命名：模块11-作业-[你的名字]-[skill名称].pdf
═══════════════════════════════════════════
十、模块 11 结语：创作者思维，是这套系统给你的最后一课
走到这里，你已经是整个 Skill Stack 课程的毕业生了。
回头看这十一个模块：
模块 1-2：你学会了「输入」——把书变成可用的知识 模块 3-5：你学会了「思考」——诊断、对标、执行 模块 6-7：你学会了「沉淀」——自动化和检索 模块 8-9：你学会了「验证」——多视角和跨会话 模块 10：你学会了「串联」——走完完整闭环 模块 11：你学会了「创造」——写自己的 Skill
最后这一步，是最重要的一步。
3 MCP 给了你的 Agent 访问外部工具和数据的能力。Skills 则教 Agent 如何使用这些工具和数据。
这个区分，在模块 11 有了更深的含义：
工具是别人给的，Skills 是你自己写的。
当你学会写 Skill，你不再受限于「市面上有什么工具」——任何你觉得有价值的工作流，都可以被编码成一个 Skill，在任何支持 Agent Skills 规范的工具上运行，分享给任何和你有相似需求的人。
8 为 Claude Code 写的 Skill 可以直接复制进 Codex 的 skills 目录并正常工作。团队可以以 SKILL.md 为标准，让每个开发者都能使用，不管他们偏好哪个 Agent。
这就是开放标准的力量——你创造的东西，不会被锁在某一个工具里。
4 Agent Skills 解决了一个真实的、具体的问题：如何在不压垮上下文窗口的情况下，给 AI Agent 提供专业的、可复用的专长。解决方案在其简洁性中体现出优雅。
整个 Skill Stack 工作流的设计哲学，也是这个道理：
不是用最复杂的工具，而是用最简洁的方式，解决一个真实的问题。
一个好的 Skill，就像一把好的工具——它不张扬，它只是在你需要它的时候，精确地做好那一件事。
当你写出第一个真正解决了你自己问题的 Skill，你就完成了从「使用者」到「创作者」的升级。
这不只是一个技能，这是一种思维方式：把任何可以重复的工作流，都变成一个可以被复用的标准。
这才是这套系统教给你的最后一课，也是最重要的一课。
💡 模块 11 的核心心智，只有一句话：「使用工具的人，受限于工具的边界；创造工具的人，定义边界在哪里。」
从今天开始，你是 Skill Stack 生态的创作者。 你写的每一个 Skill，都是你留在这套系统里的一块砖。
🎓 课程完整总结
至此，Skill Stack 阅读工作流完整课程的全部 11 个模块已经完成。
你走过的完整路径：
text
模块 0：搭建环境（地基）
↓
模块 1：book-to-skill（输入层·书变知识）
模块 2：dbs-deconstruct（输入层·概念清晰化）
↓
模块 3：商业诊断闭环（思考层·结构化判断）
模块 4：内容生产线（输出层·知识变内容）
模块 5：执行力系统（执行层·知道到做到）
↓
模块 6：Obsidian 自动化（沉淀层·知识库自动生长）
模块 7：知识原子挖矿（检索层·历史经验可查询）
↓
模块 8：多视角思辨（验证层·决策前听反对）
模块 9：存档与续写（记忆层·跨会话持续进化）
↓
模块 10：综合实战（整合层·全栈串联）
模块 11：自定义 Skill（创造层·从使用者到创作者）
这不是一套工具的操作手册，而是一套思维方式的培养系统。
当你把书中的知识原子、商业诊断的判断、内容创作的反馈、执行力的教训——都沉淀进一个持续生长的知识库，并且可以在任何时候被检索、被接续、被分享……
你建立的，不只是一个知识管理系统——你建立的，是一个持续进化的判断力系统。
这才是 Skill Stack 的真正价值所在。
普通人如何用 AI 搭建自己的知识操作系统？
一个程序员出身的知识工作者，公开记录自己如何用 AI 工具搭建个人知识系统、把读过的书和做过的项目变成可复用资产的全过程。
我是【一只阿木木】——公开建造我的 AI 第二大脑。
欢迎加入行动营👇获取更多Obsidian + AI数字大脑实践
我相信：在 AI 时代，每个普通人都该拥有一个自动生长的知识系统
欢迎关注【一只阿木木】🌊