SKILL.md 完整创作指南：从理解触发机制，到三个真实模板，到调试迭代方法
一只阿木木约 22 分钟从使用者到创造者：写出你的第一个流程类 Skill
——SKILL.md 完整创作指南：从理解触发机制，到三个真实模板，到调试迭代方法
你有没有对 AI 说过同样的话超过三次？
如果有，那就是一个需要写成 Skill 的信号。
想象这个场景：你每周都要处理会议记录。你把转录稿粘贴给 Claude，然后开始说：
「按照我的格式整理这个会议记录，我的项目笔记放在 01_Projects 文件夹，格式是……会议参与者要用 wikilinks 格式，行动项用
- [ ]开头，负责人用 @ 标注……对了，如果提到的人在 People 文件夹里有笔记的话，记得双向链接……」
然后下周，你再说一遍。
下下周，再说一遍。
Skills 要解决的正是这件事：让你停止重复自己，改为教会 Claude 一次。它与 CLAUDE.md、hooks 和 subagents 等其他 Claude Code 定制选项有本质区别。
官方的 5 个 Skill 教会了 Claude 说 Obsidian 的"格式语言"。但你每周都要对 AI 重复的那些话——你的文件夹结构、你的命名规则、你的处理流程——没有任何官方 Skill 能替你定义它们。
kepano 仓库中的核心技能赋予了 Claude 在 Obsidian 内工作的能力。超出这个范围的一切，都是你需要自己来定义的。
这篇文章就是教你完成这"超出范围的一切"。
第一章：你必须先理解的那件事——description 字段是 Skill 的灵魂
很多人创建了 Skill，但它从来不触发。
原因几乎总是同一个：description 写错了。
如果你的 Skill 不触发，问题几乎从来不在于指令内容本身。问题在于 description。这是大多数人最终搞清楚的事情。
在动手写第一个 Skill 之前，必须先把这个机制搞清楚。
description 字段的工作原理：三层渐进式加载
Skills 不会把全部内容从一开始就倾倒进 AI 的上下文窗口——那会浪费 Token 并拖慢速度。所有主流平台都使用三层渐进式加载模型：目录层，会话开始时 Agent 只看到每个 Skill 的名称和描述，这份简洁的列表只消耗极少 Token，但已足够让 Agent 知道有什么可用。激活层，当 Agent 判断某个 Skill 相关时（无论是你触发还是任务匹配），才加载完整的 SKILL.md 内容。
这意味着：
description 是技能发现的关键。Claude 用它从可能多达 100+ 个可用 Skill 中选出正确的那一个。description 会被注入进系统提示中。
用一个清晰的比喻：description 是你在"书架"上放的书名和简介——Claude 先读这个，决定要不要把整本书从书架上取下来。书名和简介写得模糊，这本书就永远待在书架上。
description 的四条写作规则
规则一：用第三人称写，不用第一或第二人称。
description 字段要同时实现 Skill 发现和使用场景说明。始终用第三人称写作。description 会被注入进系统提示，视角不一致会导致发现问题。
YAML
# ❌ 错误：第一/第二人称
description: "I can help you process meeting notes"
description: "You can use this to format your meetings"# ✅ 正确：第三人称
description: "Processes meeting transcripts into structured Obsidian notes."
规则二：包含"做什么"和"何时触发"两部分。
好的描述示例："处理 Excel 文件并生成报告"……要具体，包含关键词。同时包含这个 Skill 做什么，以及何时使用它的具体触发场景和上下文。
在 description 字段中加入「Use when...」语言来明确触发条件：description: | Knowledge Management for Obsidian vault. USE WHEN user asks "what do I know about X", "find notes about", "load context for project", "save to vault", "capture this", "validate tags".
规则三：用真实的触发短语，不是技术描述。
description 字段是你要写的最重要的东西。它同时驱动隐式激活（Agent 自动选择）和搜索/发现功能。包含你实际使用的真实短语——"整理会议记录"、"处理 Inbox"、"写读书笔记"——而不只是技术描述。
规则四：Claude 只对它无法独立轻松处理的任务使用 Skill。
理解触发机制有助于设计更好的 description。Skills 在 Claude 的可用技能列表中以名称和描述出现，Claude 根据这个描述决定是否调用某个 Skill。重要的是，Claude 只会对它无法独立轻松处理的任务调用 Skill——简单的单步查询可能不会触发 Skill，即使 description 在字面上匹配。
这意味着：只有涉及多步骤、有特定约定、需要 Vault 上下文的任务，才真的需要 Skill。 「帮我写一句话总结」不需要 Skill；「按照我的 Vault 约定处理本周会议记录并建立双向链接」需要。
一个完整的 description 模板
YAML
description: |
[做什么，第三人称，一句话核心功能]。
Use when [触发场景1]、[触发场景2]，或用户提到 [关键词1]、[关键词2]。
不适合 [明确排除的场景]。
实际示例：
YAML
description: |
Processes raw meeting transcripts into structured Obsidian notes
following this vault's conventions (PARA folders, wikilinks for people,
action items with owners).
Use when user pastes a meeting transcript, says "整理这个会议"、
"处理会议记录"，or mentions "meeting notes"、"转录稿"、"会议整理".
Not for: casual note-taking, general formatting tasks.
第二章：SKILL.md 的完整解剖——每个部分的作用
Skills 通过 SKILL.md 顶部的 YAML frontmatter 和随后的 Markdown 内容来配置。Skill 文件可以包含任何指令，但思考你希望如何调用它有助于指导内容的组织：参考内容添加 Claude 应用于你当前工作的知识——约定、模式、风格指南、领域知识。这类内容内联运行，Claude 可以结合对话上下文使用。
一个完整的 Skill 文件结构是这样的：
text
你的-skill-名字/
├── SKILL.md ← 必须有（元数据 + 核心指令）
├── references/ ← 可选（详细参考文档，按需加载）
│ └── templates.md ← 笔记模板、格式范例
│ └── folder-map.md ← Vault 文件夹结构详细说明
└── scripts/ ← 可选（可执行脚本）
元数据（名称和描述）始终加载，约 100 个词。Claude 用它来决定 Skill 是否相关。SKILL.md 主体在 Skill 触发时加载，保持在约 500 行以内。绑定资源（脚本、参考文档、资产）按需加载，可以是任意大小。
这个设计有一个核心智慧：把「总是需要的内容」放进 SKILL.md，把「偶尔需要的细节」放进 references/ 文件夹。 Token 是有限的，按需加载让每次调用只消耗必要的上下文。
当 Skill 被触发时，Claude 用 bash 从文件系统读取 SKILL.md，将其指令带入上下文窗口。如果那些指令引用了其他文件（如 FORMS.md 或数据库 Schema），Claude 会通过额外的 bash 命令读取这些文件。当指令提到可执行脚本时，Claude 通过 bash 运行它们并只接收输出（脚本代码本身不进入上下文）。
SKILL.md 的六个核心部分
Part 1：YAML Frontmatter（必须有的两个字段）
YAML
---
name: meeting-processor
description: |
Processes meeting transcripts into structured vault notes.
Use when user provides meeting transcript, says "整理会议"、
"process this meeting"，or pastes raw transcript content.
---
使用一致的命名模式让 Skill 更容易引用和讨论。考虑使用动名词形式（动词 + -ing）作为 Skill 名称，因为这清楚地描述了 Skill 提供的活动或能力。name 字段只能使用小写字母、数字和连字符。
Part 2：Overview（简短的背景说明）
Markdown
# 会议记录处理 Skill## 概述
这个 Skill 将原始会议转录稿转化为结构化的 Obsidian 笔记，
遵循本 Vault 的约定（PARA 文件夹结构、People wikilinks、行动项格式）。
它不做的事情：
- 不修改已归档的会议笔记
- 不创建没有实体对应的 wikilinks
- 不推测不确定的日期或参与者
这个"不做什么"的列表非常重要——它防止 AI 在边界情况下发挥创意做出错误的事情。
Part 3：Vault 约定说明（这是流程类 Skill 的核心价值）
Markdown
## 本 Vault 的会议相关约定### 文件夹结构
- 会议笔记保存在：`02_Areas/Meetings/`
- 命名格式：`YYYY-MM-DD-会议主题.md`
- People 笔记在：`03_Resources/People/`
### Frontmatter 规范
所有会议笔记必须包含：
- title: 会议主题
- date: 会议日期（YYYY-MM-DD）
- type: meeting
- participants: [参会者列表，使用 wikilinks]
- status: processed
### 链接规范
- 参会者：必须使用 [[People/姓名]] 格式
- 提到的项目：使用 [[Projects/项目名]] 格式
- 如果对应笔记不存在：先创建空白占位笔记再链接
Part 4：执行步骤（清晰的多步骤指令）
在指令中使用祈使句形式。
Markdown
## 执行步骤1. **识别会议元数据**
- 从转录稿提取：日期、主题、参会者列表
- 如果任何信息不明确，在开始前询问确认
2. **检查参会者**
- 在 `03_Resources/People/` 中搜索每位参会者
- 如果笔记存在：使用 [[People/姓名]] 格式
- 如果笔记不存在：创建最简空白占位笔记，再链接
3. **提取结构化内容**
- 决策（以"决定"/"同意"/"确认"开头的句子）
- 行动项（以"需要"/"TODO"/"ACTION"开头的项目）
- 关键讨论点（重要的观点或信息，不是所有内容）
4. **生成笔记**
- 使用 `references/meeting-template.md` 中的模板
- 所有参会者名称用 wikilinks 格式
- 行动项格式：`- [ ] 任务描述 @[[负责人]]`
5. **建立反向链接**
- 在每位参会者的 People 笔记中追加：
`[[YYYY-MM-DD-会议主题]] - 一句话说明讨论了什么`
6. **确认完成**
- 列出创建/修改的所有文件
- 列出需要我手动确认的任何不确定项
Part 5：示例（这是最有效的质量控制手段）
加入示例。它们是引导输出质量最有效的方式。解释原因。Claude 从推理中的泛化能力比从僵化规则中更好。
Markdown
## 输入/输出示例**示例输入（原始转录片段）：**
"好的我们今天讨论了新产品的上线计划，小明说他下周会完成设计稿，
我们同意把发布日期定在3月15日。"
**期望输出（行动项格式）：**
- [ ] 完成产品设计稿 @[[People/小明]] (due: 2026-03-XX)
**期望输出（决策格式）：**
> [!info] 决策记录
> 产品发布日期确定为 2026-03-15
**不应该出现的格式：**
- [ ] 小明完成设计稿（错误：没有 @wikilink 格式）
- 发布日期：3月15日（错误：没有用 callout 格式的决策记录）
Part 6：Gotchas（这是让 Skill 真正可靠的关键）
Markdown
## 注意事项（Gotchas）- **日期歧义**：如果转录稿里说"下周一"而没有具体日期，
不要猜测——在行动项里写 `(due: 待确认)` 并告知我
- **外部人员**：如果参会者明显是外部客户或合作方，
不要在 People 文件夹创建笔记，只用普通文字记录名字
- **重复会议**：如果当天已有同主题的会议笔记，
在文件名末尾加 `-2` 而不是覆盖原有文件
- **英文转录**：如果输入是英文，笔记标题保持英文，
但行动项和决策可以用中文（因为这是中文 Vault）
第三章：三个完整的流程类 Skill 模板
接下来是本文最核心的部分：三个真实的、可以直接作为起点的流程类 Skill 模板。
重要提醒： 教 Agent 流程的技能不应该被复制——它们应该由你自己创建。为什么要考虑自己创建 Skill？自定义技能无限地更有用和可靠，因为它们是按照你的需求和流程量身定制的。使用别人创建的技能可能无法很好地适配你的工作流和 Vault 结构。
下面的模板是起点框架，不是可以直接使用的成品。你需要根据自己 Vault 的实际情况修改其中的文件夹路径、字段名称和处理规则。
模板 A：周回顾 Skill（weekly-reflection）
这是一个真实的使用案例。在核心技能之外，你可以在 Vault 文件夹中为你定期使用的特定工作流创建自定义技能。一个好的例子是每周回顾工作流——设置 Claude 以对话方式逐一询问模板中的默认问题，根据你的回答进行追问，然后浏览你过去一周创建的笔记，将你对回顾问题的回答和对这些笔记的总结合并成一篇新的周回顾笔记。
文件结构：
text
.claude/skills/weekly-reflection/
├── SKILL.md
└── references/
└── reflection-template.md
SKILL.md：
Markdown
---
name: weekly-reflection
description: |
Conducts weekly reflection session and creates structured weekly review note.
Use when user says "做周回顾"、"weekly review"、"本周总结"，
or when it's Friday/Sunday and user wants to review the week.
Reads this week's notes, asks reflection questions conversationally,
and creates a structured weekly note.
---# 周回顾 Skill
## 概述
这个 Skill 以对话方式引导每周回顾，并生成结构化的周回顾笔记。
它结合了本周的笔记内容和你对回顾问题的回答。
## 本 Vault 的回顾约定
- 周回顾笔记保存在：`02_Areas/Reviews/Weekly/`
- 命名格式：`YYYY-WXX-weekly.md`（如 2026-W15-weekly.md）
- 本周笔记定义：frontmatter date 在本周范围内，或文件修改时间在本周
## 执行步骤
### 阶段一：内容收集（先做，不要跳过）
1. 读取本周（周一到今天）所有修改过的笔记
2. 读取 `references/reflection-template.md` 获取回顾问题列表
3. 生成本周笔记的简短摘要（每篇一行，不超过 20 字）
### 阶段二：对话式回顾
4. 展示本周笔记摘要，然后说："好，我们开始本周回顾"
5. **逐一**提问 reflection-template.md 中的问题
6. 每个问题在我回答后，如果我的回答引出了有价值的延伸，
追问一个相关的问题（只追问一次，不要追问的追问）
7. 所有问题问完后，汇总我的所有回答
### 阶段三：生成周回顾笔记
8. 根据以下结构生成周回顾笔记：
## 输出模板
参见 references/reflection-template.md 中的笔记模板部分
## 注意事项（Gotchas）
- 如果我在问题之间说"跳过"，跳过这个问题，继续下一个
- 如果是第一次运行（没有之前的周回顾），不要引用"上周"的内容
- 不要在生成笔记时"填充"我没有明确说过的内容
references/reflection-template.md：
Markdown
# 回顾问题列表## 本周亮点
1. 本周你最满意的一件事是什么？
2. 你学到了什么新东西？
## 本周挑战
3. 本周最难处理的事情是什么？
4. 如果重来一次，你会做什么不一样的选择？
## 下周展望
5. 下周你最重要的一个目标是什么？
6. 有什么事情你一直在推迟但下周应该处理的？
---
# 周回顾笔记模板
---
title: YYYY年第XX周回顾
date: YYYY-MM-DD
type: weekly-review
week: YYYY-WXX
mood: [1-5 的数字，5=非常好]
---
## 本周笔记概览
[AI 生成的本周笔记列表和简短摘要]
## 本周亮点
[来自对话的回答]
## 本周挑战与学习
[来自对话的回答]
## 下周重点
[来自对话的回答]
## 下周第一个行动
- [ ] [最重要的那一件事]
模板 B：Inbox 智能分类 Skill（inbox-cleanup）
Claude 将你对回顾问题的回答和一周内创建笔记的总结合并在一起。最后，Claude 会使用另一个叫做 inbox-cleanup 的 Skill 来分类过去一周创建的所有笔记，决定是将笔记移至 Vault 中的永久位置（根据内容重要性），还是将其归档。
这是日常使用频率最高的流程类 Skill 之一。
文件结构：
text
.claude/skills/inbox-cleanup/
├── SKILL.md
└── references/
└── folder-map.md
SKILL.md：
Markdown
---
name: inbox-cleanup
description: |
Processes and categorizes notes in the Inbox folder according to vault conventions.
Use when user says "处理 Inbox"、"清理收件箱"、"process my inbox"，
or asks to organize recently captured notes.
Reads inbox notes, determines correct destinations, moves files,
and adds appropriate frontmatter.
---# Inbox 清理 Skill
## 概述
这个 Skill 读取 00_Inbox/ 文件夹中的所有笔记，
判断每篇笔记的类型和正确归属位置，然后执行移动和格式化。
## 执行顺序（必须遵守）
### 第一步：生成处理计划（不执行任何修改）
1. 读取 00_Inbox/ 中的所有文件
2. 读取 references/folder-map.md 了解各文件夹的用途
3. 对每个文件，判断：
- 笔记类型（article/note/meeting/idea/reference）
- 建议归属文件夹
- 建议的 frontmatter 补充
- 建议的 wikilinks（如果内容明确提到了已有实体）
4. 生成一份处理计划表格，**然后停止等待我确认**
计划表格格式：
| 文件名 | 当前位置 | 建议移至 | 类型 | 备注 |
|--------|----------|----------|------|------|
| ... | Inbox | ... | ... | ... |
### 第二步：等待确认（关键步骤）
展示计划表格后，说：
"以上是处理计划，请确认后我再执行。
如果有需要调整的项目，请指出具体条目和调整方向。"
**不要在未收到确认之前执行任何文件操作。**
### 第三步：执行（收到确认后）
5. 按照确认后的计划执行：
- 添加 frontmatter（不覆盖已有字段）
- 为实体添加 wikilinks
- 移动文件到目标文件夹
6. 报告已完成的操作列表
## 分类判断规则
**01_Projects/** → 有明确截止日期的主动项目笔记
**02_Areas/** → 持续负责的领域（工作/学习/健康）
**03_Resources/** → 参考资料：书摘、技术笔记、学到的东西
└── Books/ → 书相关
└── Articles/ → 文章相关
└── People/ → 人物相关
**04_Archive/** → 完成的项目，不要从 Inbox 直接归档
**不确定时：** 保留在 Inbox，在计划表格���备注列写"需要人工判断"
## 注意事项（Gotchas）
- 如果 Inbox 里有超过 20 个文件，先处理最新的 10 个，
完成后询问是否继续
- 文件名本身就是信息——不要修改文件名，只移动位置
- frontmatter 的 date 字段保留原始创建日期，不要用今天的日期覆盖
- 如果发现两篇笔记内容高度相似，标记出来让我决定是否合并
references/folder-map.md：
Markdown
# Vault 文件夹用途详细说明## 00_Inbox/
所有新捕获内容的暂存区。每天清空一次。
进来的内容：Readwise 同步、快速想法、待处理的网页剪辑
## 01_Projects/
有明确截止日期的主动项目。同时进行不超过 5 个。
判断标准：这个事情有截止日期吗？是主动在推进的吗？
## 02_Areas/
持续负责但没有截止日期的领域。
子文件夹：Work/ | Learning/ | Health/ | Finance/
## 03_Resources/
纯参考资料，按需查阅，不主动管理。
子文件夹：Books/ | Articles/ | People/ | Tools/ | Concepts/
## 04_Archive/
已完成或非活跃的内容。只从 Projects/ 归档，不直接接收新内容。
模板 C：阅读笔记处理 Skill（book-note-processor）
这是把"粗糙阅读记录"变成"结构化书评"的完整 Skill。
SKILL.md：
Markdown
---
name: book-note-processor
description: |
Transforms raw reading notes into structured book review notes following vault conventions.
Use when user provides messy reading notes, says "整理这本书的笔记"、
"把这个做成书评"、"process my book notes"，
or pastes unstructured highlights and thoughts about a book.
Preserves the user's voice while adding Obsidian structure.
---# 阅读笔记处理 Skill
## 概述
这个 Skill 接收原始的阅读笔记（可能是高亮摘录、零散想法、引语）
并将其转化为结构化的 Obsidian 书评笔记。
**核心原则：保留你的声音。**
这个 Skill 只做结构化和格式化，不添加你没有写过的内容，
不"改善"你的观点，不加 AI 的分析——那是你的工作。
## 必须先问的问题
在开始处理之前，如果以下信息不明确，必须先问：
1. 书名和作者是什么？
2. 这是"已读完"还��"阅读中"？
3. 你想要的输出语言（如果笔记是双语混合）？
## 执行步骤
1. **读取原始笔记**，识别以下元素：
- 直接引语（有引号或明确标注为摘录的文字）
- 作者的观点（描述书中内容的部分）
- 你的个人反应（"我认为"、"这让我想到"等）
- 行动项（"我要试试"、"下次..."等）
2. **生成结构化笔记**，使用以下格式：
### 输出格式
title: 书名 author: 作者名 type: book-note status: [read/reading] date-read: YYYY-MM-DD（如果已知） rating: [1-5]（如果你有提到） tags:
books/[主题分类]
核心主题
[1-3 句话，描述这本书的核心论点]
关键概念
[来自笔记的重要概念，每个概念一个小节]
重要引语
[精确引语] — 作者名
我的反思
[你的个人反应和想法，保持原话风格]
行动项
☐ [来自笔记的具体行动]
text
3. **建立链接**：
- 如果书中提到了你 Vault 里已有笔记的概念，添加 wikilinks
- 保存到 `03_Resources/Books/` 文件夹## 注意事项（Gotchas）
- **不要合并引语和你的反应**——这两者必须保持清晰分离
- **不要翻译引语**——引语保持原文语言
- **不要给出你自己的书评**——你只是整理，不是评价
- 如果笔记非常简短（少于 200 字），先问：
「这些是完整的笔记吗，还是你想继续补充内容后再整理？」
第四章：让 Skill 真正可靠的迭代方法
写出 Skill 的第一稿，只完成了工作的一半。
让系统达到这个状态需要迭代。CLAUDE.md 被重写了好几次。技能随着 Vault 的演进也进行了调整。但现在使用的版本真正契合了思考和工作方式，这种契合让使用感觉不像是在用工具，而是像有一个真正知道你要做什么、要实现什么的搭档。
一个正式的迭代方法：Claude A / Claude B 双角色法
Anthropic 官方的最佳实践文档里记录了一种特别有效的 Skill 迭代方法：
用 Claude B（使用 Skill 做真实工作的那个 Agent）来测试，观察 Claude B 的行为，然后把观察结果带回给 Claude A 改进。用 Skill 执行真实的工作流，给 Claude B 真实的任务，而不是测试场景。观察 Claude B 的行为：注意它在哪里挣扎、成功，或做出意外的选择。示例观察："当我让 Claude B 生成区域销售报告时，它写了查询但忘记过滤测试账户，尽管 Skill 里提到了这条规则。"带着观察结果回到 Claude A 改进：分享当前的 SKILL.md，描述你观察到的问题。
把这个方法翻译成 Obsidian 场景的操作流程：
第一轮（写初稿）： 描述你的需求，让 Claude A 生成初始 SKILL.md
第二轮（真实测试）： 用 Claude B 加载这个 Skill，给它一个真实任务，完整观察执行过程
第三轮（记录偏差）： 记下所有"这不对"的地方：
Skill 没有触发，需要手动激活 → description 需要修改 AI 做了你没要求的事情 → 在 Gotchas 里添加"不要做 X" AI 遗漏了一个步骤 → 在执行步骤里补充 输出格式不符合 Vault 约定 → 在输出模板里明确
第四轮（更新 Skill）： 把第三轮的记录告诉 Claude A：「这个 Skill 在运行时有以下问题：[描述]。请修改 SKILL.md 解决这些问题。」
一个关键的技术细节：Skill 编辑实时生效
有一个方便的细节：Claude 会主动监视这个文件夹。在会话进行中编辑 SKILL.md，修改会立即生效，不需要重启。
这意味着：在使用 Skill 的过程中发现问题，可以立即打开 SKILL.md 修改，然后在同一个会话里重新触发 Skill 验证修改效果。迭代可以是实时的，不需要重启 Agent。
三个常见的调试场景
场景一：Skill 不触发
官方文档强调了三个核心问题：Skill 不触发、触发太频繁，或 Claude 看不到所有你的 Skill。如果 Claude 拒绝使用你的 Skill，从 description 开始查。Claude 使用 description 决定何时应用一个 Skill，所以它应该听起来像你自然地表达那个任务的方式。如果你通常说"review my code"，但你的 description 说的是抽象的"audit software artefacts"，别奇怪 Claude 错过了这个连接。Anthropic 也建议检查当你问"What skills are available?"时 Skill 是否出现，以及必要时用 /skill-name 直接调用它。
调试步骤：
问 Claude：「你现在能看到哪些 Skill？」检查你的 Skill 是否在列表里 手动触发：在 Claude Code 中输入 /你的skill名字，看是否可以激活如果手动可以激活但不自动触发：修改 description，加入更多真实触发短语
场景二：Skill 触发了但行为不对
有一件重要的事需要内化：Skill 不保证执行。模型仍然决定是否遵循指令。把它们想成是大幅提升一致性的结构化指导，而不是确定性的自动化。如果模型偏离了脚本，修复几乎总是改进指令或 description，而不是调试运行时行为。
场景三：Skill 太长，每次都加载太多内容
关键洞察：只有 name 和 description 在初始时加载。保持 SKILL.md 在 500 行以内，把详细文档放在引用文件里。全部可用技能列表有 15,000 字符的 Token 限制。
解决方案：把详细的模板、示例、文件夹说明移到 references/ 子文件夹，在 SKILL.md 里只保留核心步骤，并明确注明「详见 references/templates.md」。
第五章：跨平台使用——你的 Skill 不只能在 Claude Code 用
这一章是一个值得了解但很多人不知道的信息：你写的 SKILL.md 文件，不只能在 Claude Code 里使用。
同样的 SKILL.md 格式可以在 Claude Code、Cursor、Gemini CLI 和其他兼容 Agent 上使用。
具体的跨平台路径：
Cursor（2026年2月原生支持）： Cursor 原生技能系统于 2026 年 2 月推出，与 SKILL.md 格式完全兼容——不需要规则文件。将文件复制到 ~/.cursor/skills/你的skill名字/，Cursor 自动识别，不需要重启。
OpenCode： 克隆完整仓库到 OpenCode skills 目录。OpenCode 自动发现 ~/.opencode/skills/ 下的所有 SKILL.md 文件。不需要修改 opencode.json 或任何配置文件。重启 OpenCode 后技能自动生效。
任何支持自定义系统提示的 AI 工具： SKILL.md 是一个纯 Markdown 文档。对于任何支持自定义系统提示或指令的 Agent：打开 Agent 的系统提示/自定义指令设置，粘贴 SKILL.md 的内容即可。
多 Vault 的统一管理： 可以把 obsidian-skills 的内容放在 .claude/skills/ 目录，不必每个 Vault 都复制一份。如果你有多个 Vault，可以利用 Claude Code 的架构，在父级目录定义通用的 Obsidian Skills，让所有下级 Vault 都可以调用。
团队共享（如果你和团队协作）： 如果你在团队中工作，记住之前的区分：教 Agent 如何使用 Obsidian CLI 或 Markdown 的工具类 Skill 绝对可以通过 Git 或技能市场共享。而编码了你个人流程的工作流 Skill 是值得自己构建的。
第六章：一个真实的安全警告——不要随意安装陌生人的流程类 Skill
这一章的存在是为了防止一个真实的风险被忽视。
彻底审计：审查 Skill 中捆绑的所有文件：SKILL.md、脚本、图片和其他资源。寻找异常模式，如意外的网络调用、文件访问模式，或与 Skill 声明目的不符的操作。外部来源有风险：从外部 URL 获取数据的 Skill 有特别高的风险，因为获取的内容可能包含恶意指令。即使是可信的 Skill 也可能在其外部依赖项随时间变化后被攻击。工具滥用：恶意 Skill 可以以有害方式调用工具（文件操作、bash 命令、代码执行）。像对待安装软件一样对待 Skill：只使用来自可信来源的 Skill。
具体建议：
工具类 Skill（官方格式规范）：可以安装，审查 SKILL.md 内容后确认 流程类 Skill（别人的个人工作流）：不要直接安装，用作参考和灵感，然后自己写 包含 scripts/目录的 Skill：必须仔细审查脚本内容，确认它在做你预期的事情来自陌生 GitHub 账号、有 Shell 命令的 Skill：高度谨慎
一个简单的自检标准： 如果你不理解一个 Skill 的每一行在做什么，不要运行它。
行动建议：分三层，对应三种准备状态
🟢 今天（30 分钟以内）
目标：写出你的第一个"只有你的" Skill 的草稿
识别你的触发场景：回答这个问题——「我最近一个月里，对 AI 说过超过 3 次完全相同的指令是什么？」 打开 Claude Code，运行： /plugins，选择skill-creator
在自己创建 Skill 之前，推荐使用 skill-creator Skill，因为它包含了编写高质量 Skill 定义的具体指导。在 Claude Code 中输入 /plugins 然后选择 skill-creator。配置��之后，你就可以对话式地描述你想让 Skill 做什么，它会在你本地的.claude/skills/文件夹中生成 Skill 定义。从那以后，Claude 就可以在正确的上下文出现时调用它了。告诉 skill-creator：「我需要一个 Skill，每次我整理[你的场景]时使用。我的 Vault 结构是[简短描述]，约定是[2-3条最重要的规则]。」 保存生成的草稿，不要现在就测试——明天用它处理一个真实任务，更容易发现问题。
🟡 本周（建立第一个可靠的 Skill）
目标：完成一个 Skill 的完整迭代，让它真正可靠
- Day 1-2
：识别一个小烦恼。也许你讨厌手动添加创建日期。也许你想让会议记录有统一的格式。选一件小事。 - Day 3-4
：用这个 Skill 处理 3 个不同的真实输入（不要用测试数据），记录每次"这不对"的地方 - Day 5-6
：修改一个已有的 Skill。改变一个字段的处理逻辑。熟悉这个模式。到这一周结束时，你应该有至少一个在你的 Vault 里运行的自定义 Skill。记住——目标不是完美，而是功能。你的第一个 Skill 可能写得比较粗糙。没关系，它能用就行，你以后会优化它。
🔵 本月（构建你的 Skill 体系）
目标：建立一套覆盖你核心工作流的 Skill 套件
识别你的"高频工作流"（每周至少用 2 次的流程），为每个写一个 Skill 建立 Skill 的版本管理习惯：每次修改 Skill 前，在 Skill 顶部的 # 修改记录里加一行评估一个月后的系统状态： 哪些 Skill 你每天都在用？（保留并完善） 哪些 Skill 你从来不用？（删除或重写 description） 你是否发现了新的"我总是重复说的话"？（为它写新 Skill）
结语：从使用者到创造者，这条线在哪里
在 2026 年，最强大的 Obsidian 设置不会是拥有最多插件的那些。而是拥有最经过深思熟虑的 Skills 的那些——那些让工具弯曲适应用户思维的微型自动化，而不是反过来。
这句话里藏着一个更深的洞见：
工具类 Skill 是格式规范，它是客观的——所有 Obsidian 用户遵循同一套 wikilinks 语法，所以可以共用。
流程类 Skill 是思维外化，它是主观的——你处理会议记录的方式，反映的是你对"什么是重要信息"的判断；你做周回顾的方式，反映的是你对"什么值得反思"的理解；你整理阅读笔记的方式，反映的是你的学习哲学。
这些东西，写成 SKILL.md 的过程本身就是有价值的——不只是因为 AI 会按照这些规则运行，而是因为把它们写清楚的过程，迫使你把模糊的习惯变成可执行的明确判断。
创建流程类 Skill 其实比你想象的更容易。容易到，实际上可能比从 Git 仓库把一个陌生的 Skill 复制粘贴到你的 .claude 文件夹更快。
到今天为止，这个系列已经走完了完整的旅程：
从理解"格式鸿沟"为什么存在（文章一），到知道安装什么（文章二），到选对工具（文章三），到建立完整系统（文章四），到今天——把你的思考方式本身，变成可以被 AI 执行的规范。
这条路的终点，不是一套"完美的 Skill 库"。
而是你开始感觉到：AI 真的在以你的方式思考和处理信息，而不是在用一种通用的方式处理你的信息。
那个感觉，是值得投入时间的。
AII
松花酿酒，春水煎茶。
眉上风止，见字如晤。
一只阿木木