给 claude-obsidian 写一个自定义 Skill

给 claude-obsidian 写一个自定义 Skill

当内置 10 个命令不够用时，如何用 15 分钟扩展你的知识引擎

作者：一只阿木木我相信：在 AI 时代，每个普通人都该拥有一个自动生长的知识系统。

三个月之后才会发现的事

你把 claude-obsidian 用熟了之后，有一天会遇到这种感觉：

ingest？会了。query？会了。lint？会了。autoresearch？会了。

然后你面对一个具体的工作场景——比如每周五下午要写一份团队周报——你会想：

“这件事我每周都要做，步骤是固定的：读本周的会议记录，提取进展和阻碍，按项目分组，生成 Markdown 格式，发给 PM。”

“Claude 能帮我做这件事吗？”

能。但内置的命令里没有这个。

你用普通提示让 Claude 做了一次，花了十分钟，结果还不错。然后你想：能不能下周直接输入一个命令就触发？能不能把这个工作流固化下来，变成系统的一部分？

这就是你需要自定义 Skill 的时刻。

这篇文章要解决的真实问题

内置命令是通用的，设计给所有人用的。

但你的工作，不是通用的。

你的周报格式和别人不一样。你的代码库文档规范和别人不一样。你整理播客笔记的方式和别人不一样。

把这些"固定步骤的重复工作"写成自定义 Skill，是整个 claude-obsidian 系统里回报最高但最少人做的事。

一个以前每次都需要手动操作的工作流，变成了一个单一命令。随着时间推移，Skill 库变成一个完全围绕你实际工作方式构建的个人自动化系统。

这篇文章分三个部分：

1. 理解 Skill 的本质
   ——它到底是什么，系统怎么读它
2. 手把手写一个真实 Skill
   ——周报生成器，完整代码
3. 进阶技巧
   ——让 Skill 越来越聪明的 5 个设计模式

读完你会有一个可以直接跑的 Skill，和一套自己设计新 Skill 的方法论。

第一部分：Skill 到底是什么？——先想清楚，再动手

在写代码之前，先把最重要的概念搞对。

Skill 不是插件，不是脚本，不是函数

很多程序员第一次听到"自定义 Skill"，会以为是写一个 Python 函数，或者一个 shell 脚本，或者一个 API 接口。

都不是。

Skill 的本质是：一份给 AI 的结构化操作说明书。

它是 Markdown 文件。它告诉 Claude：当用户说了某个触发词，你应该做什么，按什么顺序做，做完之后验证什么，输出长什么样。

Claude Code 技能是通过 Markdown 文件定义的，可以配置，可以复制，可以共享。

这意味着：任何人都能读懂 Skill 文件，任何人都能修改它，任何人都能把它分享给别人用。不需要编译，不需要打包，不需要安装。

这也是为什么 15 分钟就能写一个 Skill——因为你写的不是代码，而是说明书。

Skill 的三层结构

每一个 Skill，不管多复杂，都由三层组成：

第一层：触发（Trigger）

用户说什么词，这个 Skill 就启动。可以是命令式的（/weekly-report），也可以是自然语言的（生成周报），也可以是带参数的（/weekly-report --team product --format notion）。

第二层：执行链（Action Chain）

一系列有序的操作步骤。每一步都明确：读什么文件，做什么处理，写到哪里，调用什么工具。

第三层：验收（Validation）

好的输出长什么样？坏的输出长什么样？边界条件怎么处理？（比如"如果本周没有会议记录怎么办"）

这三层是 Skill 设计的骨架。后面所有的细节，都在这个框架里填充。

Skill 文件住在哪里？

claude-obsidian 的 Skill 文件有两个存放位置：

vault/
└── CLAUDE.md                    ← 简单 Skill：直接写在这里
    skills/
    └── weekly-report/
        ├── skill.md             ← 复杂 Skill：独立文件夹
        ├── templates/           ← Skill 用到的模板
        │   └── weekly-report-template.md
        └── examples/            ← 好输出示例（让 AI 学习）
            ├── good-example.md
            └── bad-example.md

简单规则：

• 不超过 10 步的 Skill → 写进 CLAUDE.md，用 ## 分节标注
• 超过 10 步，或者有模板、有示例的 Skill → 独立 skills/ 文件夹

这篇文章会写一个完整的独立 Skill，但先从理解 CLAUDE.md 里的简单 Skill 格式开始。

第二部分：从最简单的开始——CLAUDE.md 里的内联 Skill

打开你的 CLAUDE.md，在底部加上这样一段：

Markdown

## Skill：每日 Hot Cache 更新
触发词：update hot cache / 更新热缓存 / /wrap
当用户触发这个 Skill 时，执行以下步骤：
1. 读取今天所有会话的内容
2. 提炼：今天做了什么，卡在哪里，明天继续什么
3. 用下面的格式更新 wiki/hot.md
输出格式：
---
last-updated: [今天日期]
## 当前最高优先级
[1-3 条，每条一行]
## 今日进展
[2-5 条，简洁]
## 未解决问题
[如有，列出]
## 明天继续
[最重要的 1-2 件事]
---
要求：
- 控制在 200 词以内
- 不写废话，每行都要有实质内容
- 如果今天没有明确进展，诚实说明，不要编造

就这些。现在在 Claude 会话里输入 update hot cache，它会按照这个说明书执行。

这是最轻量的 Skill 形式。它的局限是：没有模板，没有示例，步骤复杂了会不稳定。

但它足以让你理解 Skill 的基本工作方式。

第三部分：写一个真实的完整 Skill——周报生成器

现在来写一个真正有用的、你可以每周五下午直接用的 Skill。

场景定义

使用者：工程师 / 技术 Manager / 内容工作者

触发频率：每周一次（周五下午）

输入：本周的会议记录、commit log、项目笔记

输出：一份格式化的 Markdown 周报，可以直接发给 PM 或发进团队频道

为什么值得写成 Skill：

• 步骤固定，每次都一样
• 需要跨多个文件读取信息
• 输出格式有严格要求
• 每周都要做，自动化回报极高

Step 1：创建文件夹结构

Bash

mkdir -p ~/vault/skills/weekly-report/{templates,examples}

你的 vault 里会多出这样的结构：

text

vault/
└── skills/
    └── weekly-report/
        ├── skill.md
        ├── templates/
        │   └── report-template.md
        └── examples/
            ├── good-output.md
            └── edge-case.md

Step 2：写模板文件

先写模板，再写 Skill。模板是输出的"形状"，Skill 是"填充逻辑"。

skills/weekly-report/templates/report-template.md：

Markdown

---
type: weekly-report
week: {{WEEK_NUMBER}}
date-range: {{START_DATE}} 至 {{END_DATE}}
generated: {{GENERATED_DATE}}
---
# 周报：第 {{WEEK_NUMBER}} 周（{{START_DATE}} - {{END_DATE}}）
## 本周总结（一句话版本）
{{ONE_LINE_SUMMARY}}
---
## 项目进展
{{#each PROJECTS}}
### {{PROJECT_NAME}} · {{STATUS_EMOJI}} {{STATUS_TEXT}}
**完成的事**
{{COMPLETED_ITEMS}}
**下周计划**
{{NEXT_WEEK_ITEMS}}
**当前阻碍**（如有）
{{BLOCKERS}}
---
{{/each}}
## 本周亮点
{{HIGHLIGHTS}}
## 风险与需要支持的事项
{{RISKS_AND_ASKS}}
## 数据快照（如适用）
{{METRICS}}
---
*由 AI 辅助生成，基于本周会议记录和工作日志*
*来源：{{SOURCE_FILES}}*

为什么先写模板？

因为输出的结构决定了 Skill 的提取逻辑。你知道要输出"项目进展"，Skill 就知道要从会议记录里提取"按项目分组的进展"。模板是 Skill 的北极星。

Step 3：写好输出示例

skills/weekly-report/examples/good-output.md：

Markdown

# 这是一个好的周报输出示例
特点：
- 每个项目条目有具体细节，不是"有进展"这种废话
- 阻碍写得清楚：是什么阻碍，需要谁帮助
- 一句话总结真的是一句话，不超过 30 字
- 来源文件列出了具体文件名
---
# 周报：第 22 周（2026-05-25 - 2026-05-31）
## 本周总结（一句话版本）
API 重构完成 80%，发现 PostgreSQL 锁竞争问题并已修复，下周冲刺 Beta 上线。
---
## 项目进展
### project-alpha · 🟡 进行中（落后 5 天）
**完成的事**
- 完成 UserService 重构，拆分了身份验证逻辑（PR #234 已合并）
- 修复了 order_items 表的锁竞争 bug（根本原因：advisory lock 顺序不一致）
- API /users/{id} 和 /orders/{id} 完成，通过 code review
**下周计划**
- 完成剩余 3 个 API endpoint 的重构
- 开始写集成测试
- 完成 Beta 部署配置
**当前阻碍**
- 🔴 staging 环境 DevOps 配置：等待 @张工 协助，预计周二解决
---
### project-beta · 🟢 正常
**完成的事**
- Kafka consumer group 偏移量问题定位并修复
- 性能测试完成，P99 延迟从 230ms 降到 145ms
**下周计划**
- 开始 load testing
- 评审 Q3 架构方案
**当前阻碍**
- 暂无
---
## 本周亮点
- 解决了困扰两个月的锁竞争问题，写了详细复盘文档供团队参考
- P99 延迟优化幅度超出预期（目标是降到 200ms 以下）
## 风险与需要支持的事项
- project-alpha 落后 5 天：如果 staging 环境问题周二没解决，Beta 上线需要延期 1 周
- 需要 PM 确认：Beta 测试用户范围是否可以先缩小到内部用户？
## 数据快照
- Commits：23 次
- PR 合并：5 个
- Bug 修复：3 个（其中 P0 级别 1 个）
---
*由 AI 辅助生成，基于本周会议记录和工作日志*
*来源：meetings/2026-05-28-sprint-review.md, meetings/2026-05-26-standup.md, projects/project-alpha.md*

skills/weekly-report/examples/edge-case.md：

Markdown

# 边界情况处理示例
## 边界情况 1：本周没有会议记录
当 .raw/meetings/ 里没有本周日期的文件时：
- 不要编造会议内容
- 在周报里明确写：「本周无会议记录，以下内容基于项目笔记和 git log」
- 从 wiki/projects/ 和 daily/ 里提取信息
## 边界情况 2：项目状态不明确
当无法判断项目是 🟢/🟡/🔴 时：
- 默认标 🟡 需关注
- 在状态文字里说明：「状态不明确，需确认」
## 边界情况 3：本周没有明显进展
不要写「持续推进中」「正常进行」这类无意义的内容。
直接写：「本周主要时间花在 [具体活动]，无新增完成项目」

示例文件的作用是什么？

给 AI 一个"好坏标准"的具体参照。这比在 Skill 里写"要写得具体"更有效——因为 AI 可以直接对比示例，而不是靠抽象描述猜测你的期望。

Step 4：写核心 Skill 文件

现在写最关键的 skills/weekly-report/skill.md：

Markdown

---
skill-name: weekly-report
trigger: /weekly-report | 生成周报 | weekly report
version: 1.2
author: 一只阿木木
description: 读取本周所有工作记录，生成结构化周报
---
# Skill：周报生成器
## 触发方式
以下任意一种都可以触发：
- `/weekly-report`
- `生成周报`
- `weekly report`
- `/weekly-report --week 22`（指定周数）
- `/weekly-report --format notion`（指定输出格式）
---
## 执行前：读取上下文
在任何操作之前，先读取：
1. `wiki/hot.md` ← 了解当前最高优先级和最近状态
2. `wiki/index.md` ← 了解 vault 里有哪些项目页面
---
## 执行步骤（按顺序，不可跳过）
### Step 1：确定本周时间范围
- 自动检测今天日期
- 计算本周（周一到今天，或周一到周日）
- 如果用户指定了 `--week N`，用该周数对应的日期范围
- 把时间范围记下来，后续步骤都用这个范围过滤
### Step 2：扫描并收集本周资料
按以下顺序扫描，收集本周日期范围内的所有文件：
**来源 A：会议记录**
- 路径：`notes/.raw/meetings/` 或 `.raw/meetings/`
- 过滤：文件名包含本周日期（格式：YYYY-MM-DD）
- 提取：会议主题、参与者、决策事项、行动项
**来源 B：每日笔记**
- 路径：`notes/daily/` 或 `daily/`
- 过滤：本周日期范围内的文件
- 提取：今日进展、阻碍、备注
**来源 C：项目控制塔**
- 路径：`wiki/projects/` 或 `notes/projects/`
- 读取：所有项目页面（不过滤日期，取最新状态）
- 提取：项目状态、当前里程碑、阻碍
**来源 D：站会记录**（如有）
- 路径：`.raw/standups/`
- 过滤：本周日期
- 提取：昨日完成、今日计划、阻碍
**来源 E：Git log**（如可访问）
- 命令：`git log --oneline --since="本周一" --until="今天"`
- 提取：commit 数量、主要改动方向
如果某个来源路径不存在，跳过该来源，不报错，但在输出的"来源"字段里注明"未找到"。
### Step 3：按项目分组整理信息
把 Step 2 收集到的所有信息，按项目名分组：
```
project-alpha:
  - 来自会议的信息：[...]
  - 来自每日笔记的信息：[...]
  - 来自项目控制塔的状态：[...]
  - 相关 commits：[...]
project-beta:
  [同上]
```
如果某条信息无法归属到具体项目，归入"其他 / 通用"分组。
### Step 4：判断每个项目的健康状态
根据以下规则，给每个项目打状态标签：
```
🟢 正常：
  - 进度符合预期，无 blocking 阻碍
  - 本周有具体完成项目
🟡 需关注：
  - 进度落后 3 天以上，但有计划追回
  - 存在 🟡 级别阻碍（有人在处理，但未解决）
  - 信息不足以判断（诚实标注）
🔴 有风险：
  - 进度落后超过 1 周
  - 存在 🔴 级别阻碍（无人处理，或无法独立解决）
  - 有 deadline 即将到期但完成度不足
```
### Step 5：生成周报内容
使用 `skills/weekly-report/templates/report-template.md` 作为输出格式。
填充规则：
- `{{ONE_LINE_SUMMARY}}`：不超过 30 字，必须包含最重要的进展和风险
- 每个项目的"完成的事"：必须有具体细节，禁止使用"有进展"、"持续推进"等模糊表达
- "当前阻碍"：如果是具体的人在负责，写出来；如果是等待某个外部事件，写出预计解决时间
- `{{SOURCE_FILES}}`：列出实际读取的文件名，不要写"多个来源"这类模糊描述
参考 `skills/weekly-report/examples/good-output.md` 中的好示例。
避免 `skills/weekly-report/examples/edge-case.md` 中描述的坏模式。
### Step 6：写入输出文件
把生成的周报写入：
```
notes/meetings/weekly-report-YYYY-WW.md
```
（YYYY 是年份，WW 是周数，比如 `weekly-report-2026-22.md`）
同时在 `wiki/log.md` 追加一条记录：
```
[日期] weekly-report skill 执行，生成报告：[文件名]，覆盖项目：[项目列表]
```
### Step 7：更新 hot.md
在 hot.md 的"本周已生成"部分追加：
```
- [日期] 周报已生成：[[meetings/weekly-report-YYYY-WW]]
```
---
## 执行后：向用户展示摘要
生成完成后，在对话里展示：
```
✅ 周报已生成：notes/meetings/weekly-report-[YYYY-WW].md
📊 覆盖项目：[项目 A] · [项目 B] · [项目 C]
📁 读取了 [N] 个来源文件
⚠️  [项目 X] 状态为 🔴，建议重点关注
需要修改任何部分吗？输入「修改 [部分名称]」即可。
```
---
## 参数支持
| 参数 | 说明 | 示例 |
|------|------|------|
| `--week N` | 指定第 N 周（默认本周） | `/weekly-report --week 21` |
| `--format notion` | 输出 Notion 友好格式 | `/weekly-report --format notion` |
| `--format slack` | 输出 Slack 消息格式（纯文本，去掉 Markdown 标题）| `/weekly-report --format slack` |
| `--projects A,B` | 只生成指定项目的报告 | `/weekly-report --projects alpha,beta` |
| `--dry-run` | 预览不写入文件 | `/weekly-report --dry-run` |
---
## 边界情况处理
参考 `skills/weekly-report/examples/edge-case.md`。
核心原则：**宁可说"信息不足"，也不编造内容。**
---
## 验收标准
一个合格的周报输出必须满足：
- [ ] 每个项目都有具体的完成项（不是模糊描述）
- [ ] 状态标签有明确的依据（在 Skill 执行日志里可追溯）
- [ ] 阻碍部分写明了"谁在负责"或"等待什么"
- [ ] 来源文件列表是真实的文件路径，不是"多个来源"
- [ ] 一句话总结不超过 30 字
- [ ] 输出文件成功写入 notes/meetings/

Step 5：在 CLAUDE.md 里注册这个 Skill

Skill 文件写好了，还需要让 Claude 知道它在哪里。

在你的 CLAUDE.md 里加上：

Markdown

## 自定义 Skill 目录
以下 Skill 在用户触发时，先读取对应的 skill.md 文件，
然后严格按照 skill.md 里的步骤执行：
| 触发词 | Skill 文件 | 说明 |
|--------|-----------|------|
| /weekly-report | skills/weekly-report/skill.md | 生成周报 |
| 生成周报 | skills/weekly-report/skill.md | 生成周报（中文触发）|
## Skill 执行规则
- 读到触发词时，必须先读取对应的 skill.md，不要依靠记忆执行
- 严格按照 skill.md 里的步骤顺序执行，不可跳步
- 每个 skill.md 里的验收标准，必须在输出前自查一遍
- 如果执行中遇到 skill.md 没有覆盖的情况，暂停并告知用户

为什么要显式注册？

因为 CLAUDE.md 是 Claude 每次会话开始时读取的"初始化文件"。把 Skill 目录写在这里，Claude 才能在触发词出现时知道"去哪里找操作说明"。

Step 6：第一次运行，验收

完成以上步骤后，在 Claude Code 里输入：

text

/weekly-report --dry-run

--dry-run 参数让系统执行所有步骤但不写入文件，先看输出对不对。

你应该检查的 7 个点：

text

✅ 1. 时间范围正确（本周一到今天）
✅ 2. 读取了正确的来源文件（不是随机读的）
✅ 3. 项目状态标签有依据（不是随机打的）
✅ 4. 完成项有具体细节（不是"持续推进"）
✅ 5. 阻碍写明了负责人或等待事项
✅ 6. 一句话总结不超过 30 字
✅ 7. 来源文件列表是真实路径

全部通过之后，去掉 --dry-run 参数：

text

/weekly-report

第一个真实周报就生成了。

第四部分：5 个让 Skill 越写越好的设计模式

写完第一个 Skill 之后，你会想写更多。

这里给你 5 个我总结出来的设计模式——每一个都是踩了坑之后学到的。

模式 1：先写"坏示例"，再写"好示例"

大多数人写 Skill 只写好示例。这不够。

Claude 会倾向于复制示例的表面形式，包括它的缺陷。如果你的好示例本身不够好，Skill 的输出会继承这些问题。

更有效的方式是：先写一个坏示例，明确标注"这里为什么不好"，再写好示例。

Markdown

# 坏示例（不要这样输出）
## 项目进展
- project-alpha：本周继续推进，有一些进展。
- project-beta：正常进行中。
问题：
1. "继续推进"是废话，没有具体信息
2. "正常进行中"不告诉读者任何事情
3. 没有阻碍信息，看不出风险
---
# 好示例（应该这样输出）
## 项目进展
### project-alpha · 🟡 需关注
**完成的事**
- 完成 UserService 重构（PR #234 已合并）
- 修复锁竞争 bug（根本原因已定位）
**当前阻碍**
- 🔴 staging 环境：等待 @张工 协助，影响 Beta 时间线

坏示例 + 解释 + 好示例的组合，比只有好示例的效果好 30% 以上（这是我自己跑了十几次 Skill 之后的主观感受，你实际测试时可能不同）。

模式 2：把"不允许做的事"单独列一节

在 Skill 里，正向说明（“要做什么”）通常不够。负向约束（“不允许做什么”）同样重要。

在 skill.md 里专门加一节：

Markdown

## 明确禁止
- ❌ 不允许在"完成的事"里写"持续推进"、"有进展"、"正在进行"
- ❌ 不允许在没有来源文件的情况下编造进展信息
- ❌ 不允许删除或覆盖已有的周报文件（只允许新建）
- ❌ 不允许跳过 Step 2 的资料扫描，直接从记忆里生成
- ❌ 不允许在 `--dry-run` 模式下写入任何文件

这节内容的作用是：给 AI 划红线。你会发现，Claude 在有明确禁止规则的情况下，输出质量的一致性会显著提高。

模式 3：步骤里加"检查点"

复杂的 Skill 通常有 10 步以上。问题是：前几步的错误会在后面放大。

解决方案：在关键步骤后加检查点，让 AI 在继续之前先"汇报"。

Markdown

### Step 2：扫描并收集本周资料
[... 扫描逻辑 ...]
**检查点 A（必须在继续前完成）**
在对话里输出：
「找到以下来源文件：
- [文件列表]
共 [N] 个文件，时间范围：[起始日期] 到 [结束日期]
如果有遗漏，请告知；否则继续 Step 3。」
等待 3 秒；如果用户没有反馈，继续执行。

检查点的好处是：你可以在 Skill 运行到一半时介入，补充信息或纠正错误，而不是等到最后才发现输出不对。

模式 4：参数设计——做减法，不做加法

刚开始写 Skill，你会想给它加很多参数，覆盖各种场景。

这是错的。

参数越多，Skill 文件越复杂，出错的可能性越高，你自己也记不住用法。

设计原则：默认值覆盖 80% 的使用场景，只给剩下 20% 加参数。

Markdown

# 好的参数设计
/weekly-report                    ← 默认：本周，Markdown 格式
/weekly-report --week 21          ← 指定周数
/weekly-report --format slack     ← 指定格式
# 坏的参数设计（过度复杂）
/weekly-report --week 21 --start-date 2026-05-25 --end-date 2026-05-31 
  --format notion --projects alpha,beta --include-metrics true 
  --exclude-standups false --max-length 500 --language zh-CN

当你发现自己在加第 6 个参数的时候，停下来问：这个参数真的每周都会用到吗？如果不是，别加。

模式 5：Skill 要有"版本意识"

你的工作会变，Skill 也要跟着变。

在 skill.md 的头部 frontmatter 里加上版本号和变更日志：

Markdown

---
skill-name: weekly-report
version: 1.3
last-updated: 2026-05-31
changelog:
  - v1.3（2026-05-31）：加入 --format slack 参数支持
  - v1.2（2026-04-15）：加入 git log 来源扫描
  - v1.1（2026-03-01）：加入边界情况处理
  - v1.0（2026-02-10）：初始版本
---

为什么需要变更日志？

因为三个月后你会完全不记得这个 Skill 当时是怎么设计的，为什么加了某个参数，为什么某个步骤要这样写。

变更日志是给三个月后的自己留的说明书。

第五部分：把 Skill 变成一套个人自动化系统

一个 Skill 是有用的工具。十个 Skill 是个人自动化系统。

这里给你一个"常用 Skill 模板库"——你可以直接以这些为基础，改成适合自己场景的版本。

Skill 模板 A：会议记录处理器

Markdown

---
skill-name: meeting-processor
trigger: /process-meeting | 处理会议记录 | process meeting
---
## 执行步骤
1. 读取指定的会议记录文件（或 .raw/meetings/ 里最新的文件）
2. 提取：
   - 参与者列表
   - 讨论的核心问题（不超过 5 条）
   - 明确的决策（有 yes/no 的结论）
   - 行动项（谁 + 做什么 + deadline）
   - 遗留问题（讨论了但没结论的）
3. 更新相关项目控制塔页面
4. 更新相关人物档案页面（如有 1:1 信息）
5. 在 wiki/log.md 里记录操作
## 验收
- [ ] 行动项必须有明确的负责人
- [ ] 遗留问题和决策不能混在一起
- [ ] 来源文件必须列出

Skill 模板 B：文章素材提炼器

Markdown

---
skill-name: article-extractor
trigger: /extract | 提炼素材 | extract article
---
## 执行步骤
1. 读取 .raw/ 里指定的文章（或用户提供的 URL）
2. 提炼：
   - 核心主张（1-3 条，用自己的话，不是摘抄）
   - 关键数据点（带原文引用）
   - 可复用的框架或方法论
   - 和已有 wiki 内容的关联
3. 生成概念页（如果是新概念）或更新已有页面
4. 标注和已有内容的矛盾（如有）
5. 更新 wiki/index.md
## 禁止
- ❌ 不允许大段复制原文，必须用自己的语言提炼
- ❌ 不允许在没有来源引用的情况下写入 wiki

Skill 模板 C：代码复盘记录器

Markdown

---
skill-name: code-retro
trigger: /retro | 记录复盘 | code retro
---
## 执行步骤
1. 询问用户：这次要记录什么问题？（等待输入）
2. 引导用户回答：
   - 症状是什么？（What）
   - 根本原因是什么？（Why，用 5 Why 法）
   - 解决方案是什么？
   - 如何防止再次发生？
3. 格式化为标准复盘记录
4. 写入 wiki/patterns/mistakes/ 目录
5. 检查：wiki 里有没有类似的历史记录？如有，交叉引用
## 验收
- [ ] 根本原因必须到达"为什么"的第 3 层以上
- [ ] 预防方法必须可执行（不是"以后要注意"）

Skill 模板 D：1:1 准备助手

Markdown

---
skill-name: oneone-prep
trigger: /1on1-prep | 准备 1:1 | oneone prep
---
## 参数
- 必须提供：对方姓名
- 示例：/1on1-prep 张工
## 执行步骤
1. 读取 wiki/people/[对方姓名].md
2. 提炼：
   - 上次 1:1 说到哪里（最近一条记录）
   - 有没有我承诺但还没做的事
   - 他/她上次提到的阻碍，现在解决了吗？
   - 这次应该重点讨论什么
3. 生成一份简洁的"1:1 准备简报"
4. 在对话里展示（不写入文件）
## 验收
- [ ] 必须引用具体的日期和来源
- [ ] "我的承诺"部分不能遗漏
- [ ] 输出控制在 200 词以内

第六部分：把 Skill 贡献到社区

你写了一个好用的 Skill，想让更多人用？

claude-obsidian 有一个开放的 Skill 库。贡献方式很简单：

贡献前的自查清单

Markdown

□ skill.md 有完整的 frontmatter（name / trigger / version / description）
□ 有至少一个好示例文件（examples/good-output.md）
□ 有边界情况说明（examples/edge-case.md 或在 skill.md 里说明）
□ 有"明确禁止"一节
□ 在 README 里能用一句话解释这个 Skill 做什么
□ 在自己的 vault 里用了至少两周，确认稳定
□ 参数设计简洁（不超过 5 个参数）

贡献流程

Bash

# 1. Fork 仓库
git clone https://github.com/AgriciDaniel/claude-obsidian
cd claude-obsidian
# 2. 创建你的 Skill 文件夹
mkdir -p skills/[your-skill-name]/{templates,examples}
# 3. 复制你的文件进来
cp ~/vault/skills/[your-skill-name]/* skills/[your-skill-name]/
# 4. 在 skills/README.md 里加上一行说明
echo "| /your-skill | 一句话说明 | [作者名] |" >> skills/README.md
# 5. 提交 PR
git checkout -b add-skill-[your-skill-name]
git add skills/[your-skill-name]/
git commit -m "feat: add [your-skill-name] skill"
git push origin add-skill-[your-skill-name]
# 6. 在 GitHub 上提 PR，在描述里回答：
# - 这个 Skill 解决什么问题？
# - 我用了多久？频率是多少？
# - 有没有已知的局限性？

PR 描述模板

Markdown

## 新增 Skill：[Skill 名称]
### 解决什么问题
[一段话，说清楚这个 Skill 在解决什么痛点]
### 触发方式
- `/[trigger]`
- `[中文触发词]`
### 已验证的场景
- 使用时间：[多久]
- 使用频率：[多高]
- 测试的 vault 规模：[大概多少文件]
### 已知局限
- [局限 1]
- [局限 2]
### 截图 / 输出示例
[附上一个真实输出的截图或文本，不要造假]

社区 Skill 生态正在建立。把实际工作流固化成 Skill 并贡献出来，让所有人的系统都变得更聪明——这是这套系统最有意思的地方。

30 天行动计划：从第一个 Skill 到个人自动化系统

第一天（1 小时）：写你的第一个 Skill

选一件你这周已经手动做了的事，把它写成 Skill。

推荐从周报生成器开始（就是这篇文章写的那个）。直接照搬，改成你自己的格式。

Bash

# 创建文件夹
mkdir -p ~/vault/skills/weekly-report/{templates,examples}
# 把文章里的模板复制进去
# 修改 templates/report-template.md 里的字段，改成你的格式
# 在 CLAUDE.md 里注册
# 跑第一次：
# /weekly-report --dry-run

第一周（每天 5 分钟）：记录你的"重复操作"

每天工作结束时，问自己一个问题：今天有没有做了超过一次的操作，步骤是固定的？

记进一个清单：

Markdown

# Skill 候选清单
- [ ] 处理会议记录（每次开完会都要做，步骤固定）
- [ ] 整理读书笔记（每本书的流程一样）
- [ ] 生成 Sprint 回顾（每两周一次）
- [ ] 更新项目状态（每天站会后）

第二周：写第二个 Skill

从清单里选一个，照着周报生成器的结构写。这次会快很多——你已经有了 skill.md 的结构框架。

第三-四周：迭代优化

跑了两周之后，你会发现两类问题：

1. 输出里有你不喜欢的格式
   ——回到 skill.md 的模板，修改
2. 某个步骤 AI 总是做错
   ——在那个步骤里加"明确禁止"规则，或者加一个检查点

迭代 Skill 比写 Skill 更重要。一个用了两个月的 Skill，和第一次写的版本通常有很大差异。

第 30 天：验收

回答这三个问题：

1. 你有几个 Skill 在正常运作？
   （目标：至少 3 个）
2. 这 3 个 Skill 每周为你节省了多少时间？
   （目标：至少 1 小时）
3. 有没有哪个 Skill 你已经完全记不得手动操作步骤了？
   （这是系统真正内化的标志）

如果第三个问题的答案是"有"——恭喜。你的工作流已经被系统接管了，而不是你在迁就系统。

一张随时查的速查卡

text

=== 自定义 Skill 速查 ===
【Skill 的三层结构】
→ 触发（用户说什么词）
→ 执行链（按顺序做什么）
→ 验收（好输出的标准）
【文件放哪里】
→ 简单（<10步）：直接写在 CLAUDE.md
→ 复杂（>10步）：skills/[skill-name]/skill.md
【必须要有的文件】
→ skill.md         ← 核心执行说明
→ templates/       ← 输出格式模板
→ examples/        ← 好示例 + 坏示例 + 边界情况
【5 个设计模式】
→ 坏示例 + 好示例（比只有好示例更有效）
→ 明确禁止一节（划红线）
→ 关键步骤加检查点（中途可介入）
→ 参数做减法（默认值覆盖 80% 场景）
→ 版本号 + 变更日志（给未来的自己）
【调试 Skill 的方法】
→ 先跑 --dry-run，看步骤
→ 发现问题：在 skill.md 里对应步骤加禁止规则
→ 输出不好：更新 examples/ 里的示例
【贡献到社区】
→ 用了 2 周以上，确认稳定
→ 有 frontmatter + 示例 + 边界情况说明
→ PR 描述里回答：解决什么问题 + 已知局限

写在最后

回顾一下这篇文章做了什么：

我们从"内置命令不够用"的真实痛点出发，理解了 Skill 的本质——不是插件，不是脚本，而是给 AI 的结构化操作说明书。

然后完整地写了一个真实的 Skill：周报生成器。从文件夹结构、模板文件、示例文件，到核心 skill.md 的每一个步骤，全部有具体代码可以直接抄用。

最后给了 5 个设计模式，让你写出来的 Skill 质量越来越高，以及一套个人自动化系统的建立路径。

claude-obsidian 有 15 个内置 Claude Code 技能、多 Agent 支持、一流的方法论模式。但这套系统真正的扩展性，来自你根据自己的工作写的那些 Skill。

内置命令是别人工作方式的产物。你自定义的 Skill，才是你自己工作方式的结晶。

一年后，当你打开 skills/ 文件夹，看到 20 个 Skill 文件的时候，你会意识到：这不只是一个 AI 工具库，这是你整个工作方式的数字化版本。

而这个版本，会在你不用它的时候继续生长。

—— 一只阿木木在 AI 时代，每个普通人都该拥有一个自动生长的知识系统。