最近圈子里都在聊 AI 的 skills 机制。Claude Code 的 skills、Codex 的 skills还有 GitHub 上那些 superpower skills、baoyu skills 仓库本质上都是在给 AI Agent 装上一个个技能包一个目录、一份 SKILL.md、几个参考脚本它就能在一个具体任务上表现得更专业。我自己的配置目录里skills 文件夹不到三个月就堆了四十多个前端、测试、文档、数据清洗全部混在一起想找一个都费劲更别说让AI 实习生真正学会这些技能、在合适的场景下主动调用它们了。于是我把 Obsidian 搬了出来给这些 AI Agent skills 做了一套完整的知识管理方案。这篇文章记录的就是这套方案的完整实践适合正在大量使用 AI 编程助手、并且手上已经积累了不少 skills 文件的开发者参考。1. 先搞清楚 Skills 是什么以及为什么非要用 Obsidian1.1 Skills 机制的本质从提示词到工程化很多人第一次接触 skills 时都会有个疑问它跟我在系统提示词里写一段你是一个前端专家要遵循某某规范有什么区别其实区别大了去了。早期我们调教 AI靠的是把大段规则塞进 CLAUDE.md、或者写在项目根目录的说明文档里。这种方式最大的问题是所有知识全部叠在一起模型每次对话都要翻一遍这一大坨文本响应变慢不说真正需要的信息往往被淹没在无关内容里效果自然打折。而 skills 机制把知识拆成了一个个颗粒度更小的独立单元。每个 skill 本质上是一个文件夹里面通常包含一份带 YAML frontmatter 的 SKILL.md它负责描述这个技能的名称、适用场景和使用步骤还可以附带 scripts 脚本、references 参考资料、examples 示例等。AI Agent 拿到一个任务时会先根据任务描述去匹配各个技能的描述字段匹配上了才加载那个技能文件夹里的全部内容匹配不上就当作不存在。这有点像一个实习生手里拿着一摞岗位手册接手任务时先翻目录找到对应那本才打开细读而不是把整个书柜的书全背下来。这个设计直接改变了我们管理 AI 知识的方式知识开始以文件为单位存在每个技能可以独立更新、独立测试、独立版本化。也正因如此当 skills 数量多起来之后如何管理这些技能文件本身就变成了一个全新的工程问题。1.2 AI 实习生和管理者的知识管理痛点我习惯把 AI Agent 比作一个实习生而且是那种学习能力极强、但经验几乎为零的实习生。它记性好、响应快、执行力强问题是你不知道它脑袋里到底装了什么也不知道它什么时候会用一个过时的方案去处理新问题。我复盘了一下自己过去三个月遇到的问题基本上集中在四类。第一类是不知道有什么我明明写过好几个测试相关的 skill但真到一个需要写测试的任务时AI 没有主动调用因为 description 描述得不够准确或者干脆被我遗忘了。第二类是不知道哪个最新同一类任务我先后写过两个不同版本的 skill它们之间是什么关系哪个是替代哪个完全没有标记时间一长根本分不清。第三类是知识之间没有关联前端开发的 skill 里明明应该引用设计规范相关的 skill可它们散落在两个目录里谁也没有链接谁AI 调用时只能加载其中一个看不到完整的上下文。第四类是无法快速复用想把这个技能从我的配置里复制给团队其他成员或者迁移到新的 Agent 平台上发现目录结构混乱、依赖缺失根本没法直接给别人用。这些问题本质上跟一个普通职场新人没有知识管理习惯时遇到的问题一模一样内容在积累但结构没有建立起来于是积累得越多越混乱。如果继续靠在文件管理器里翻目录的方式去维护 skills迟早会失控。所以我当时就确定了需要引入一个工具把这些散落的技能文件变成一张有结构、有关联、可检索、可迭代的知识网络。1.3 为什么选 Obsidian本地、纯文本、可编程当时我也考虑过 Notion、语雀这样的在线笔记工具它们做团队知识库确实方便但对 skills 管理来说有个致命问题skills 的本质是给 AI 读的纯文本文件而不是给人看的在线文档。把技能内容从本地 Markdown 文件搬进在线笔记再导出用这中间多了一步格式转换还要担心平台锁死、内容同步、权限控制这些问题完全违背了以文件为单位的初衷。选择 Obsidian 有四个理由我逐一验证过都很扎实。第一它本身就是管理本地 Markdown 文件库每条笔记都是一个真实的 .md 文件跟 SKILL.md 的格式天然统一不存在格式失真。第二它支持双向链接和标签体系可以把 skill 和 skill、skill 和相关文档之间建立关联这正是传统文件夹做不到的。第三它有极强的插件生态尤其是 Dataview 和 Templater能让我把skills 清单调用频率覆盖场景这些信息自动生成出来相当于给知识库加了一个查询引擎。第四它的数据完全在本地可以用 Git 做版本管理配合 Obsidian Sync 或者其他同步盘可以多端访问不会因为某个在线服务关停导致整个知识库报废。还有一个很多人忽略的点Obsidian 对 Markdown 的支持非常干净这意味着我可以直接把 Obsidian 当作skills 的唯一事实源然后通过软链接或者构建脚本把库里的内容同步到 AI Agent 真正加载的配置目录里。这套一处维护、多处引用的架构是其他在线笔记工具很难做到的。2. 用 Obsidian 搭建 Skills 管理库目录、命名与模板2.1 目录结构与命名规范设计知识管理的第一步永远是设计结构而不是急着往里面塞内容。我踩过没有结构直接乱建的坑后来花了整整一个下午把目录推倒重来。你可以直接参考我现在的这套结构它经过了三个月的实际使用验证稳定可靠。核心思路是把技能仓库区域、Agent 配置说明区、个人备忘区彻底分开。仓库根目录下我建了三块。第一块叫10-Skills存放所有技能内容下面按照技能领域分二级目录比如frontend/、backend/、testing/、documentation/、>TABLE tags AS 标签, updated AS 最近更新, status AS 状态, description AS 描述 FROM 10-Skills WHERE file.name ! SKILL.md SORT updated DESC这段查询会把10-Skills目录下所有技能文件列成一张表格按更新时间倒序排列。如果你想只看某个领域的技能加一个WHERE contains(tags, area:frontend)就行。我把这个总览放在一个叫00-技能总览的入口笔记里每次打开 Obsidian 第一眼就能看到整个技能库的全貌。说实话有了这张表之后我再也没有在文件管理器里翻过目录。Dataview 还有一个进阶用法是用FLATTEN把 YAML 数组拆开做反向索引。比如我想知道有哪些技能引用了性能审计这个技能可以写FROM 10-Skills FLATTEN related WHERE related performance-audit一条查询就能把所有依赖关系倒查出来。这对重构技能时的影响面分析特别有用改一个底层技能之前先跑一遍反向索引看谁依赖它心里就有底了。3.3 Canvas 画布把技能地图画出来Dataview 解决的是结构化查询的问题但人脑有时候需要更直观的图景。Obsidian 自带的 Canvas 功能我用来做技能地图。具体做法很朴素在画布上以领域为分区每个技能做一张卡片卡片之间用连线标注依赖或协同关系再用颜色区分状态绿色是活跃、灰色是已废弃、黄色是草稿。这样的技能地图贴在知识库首页任何一个新加入项目的同事第一眼就能看懂整个知识库的版图前端有哪些技能、测试依赖哪些前端技能、哪个技能是全局基础能力。这比读十页文档来得都快。Canvas 我有个使用心得不要把它做成一张包罗万象、密密麻麻的大图一旦卡片超过三四百个画布就失去了意义。正确的做法是为每个领域画一张领域技能地图控制在三十张卡片以内全局只画一张高层架构图展示领域之间的关联。画布图如果过期了比没有图更误导人所以我会在每个月末花十五分钟更新一次顺便检查哪些卡片对应的技能文件确实存在避免画出幽灵节点。4. 实操案例从零管理一整套前端开发 Skills4.1 技能拆解与入库前面讲了这么多方法论这一节我用一个真实案例把它串起来。假设你手上有一堆前端开发相关的 skills 文件比如component-review.md、api-check.md、performance-audit.md、storybook-coverage.md它们散落在.claude/skills/目录里没有统一格式。现在要全部纳入 Obsidian 知识库。第一步是盘点。我把目录下所有 md 文件列出来逐个打开看一遍按照active可用、deprecated废弃、draft草稿三个状态给它们归档。这一步不需要做任何修改只需要建立认知我到底有哪些技能、每个技能的现状是什么。当时我盘下来发现有五六个技能已经明显过时了比如里面还在推荐一个已经被废弃的构建工具这种技能如果不清出来AI 随时可能被误导。第二步是拆解重组。有些技能文件实际上揉了好几件事比如api-check.md里既讲了接口契约校验又讲了 Mock 数据生成这两个场景相关性有限应该拆成两个技能。拆开之后接口契约校验归入backend领域Mock 数据生成归入frontend领域各自补充好description和tags。第三步是文件夹落地每个技能新建一个编号-技能名称文件夹放入重整后的SKILL.md再补上示例和参考文件的链接入口。整个入库过程最花时间的既不是写文档也不是设标签而是想清楚每个技能的边界。技能拆得过细AI 匹配时容易犹豫不决拆得过粗调用时又会夹带太多无关内容。我的经验是一个技能应该能在一千字以内讲清楚使用步骤超过这个体量就考虑拆判断标准是这个技能被调用时AI 需要关注的上下文是否聚焦在一个场景上。4.2 编写标准 SKILL.md给 AI 和人都能看懂的文档入库之后要给每个技能补齐一份标准格式的 SKILL.md。我以前端组件代码审查这个 skills 为例展示一下核心结构。Frontmatter 部分--- name: component-review description: 用于对前端 React 组件进行代码审查检查组件拆分、状态管理、样式隔离、可访问性和性能隐患。适合在提交 PR 前对组件代码做系统检查不适用于整站架构评审。 tags: - area:frontend - type:review - level:intermediate status: active version: 2.3.0 updated: 2025-06-15 related: - performance-audit - design-token-check ---正文部分我一般分五个小节。第一是技能目标用三到五句话说明这个技能完成后会得到什么产出比如输出一份按严重级别分组的组件问题清单并给出修复建议。第二是适用场景与禁用场景写清楚什么问题用它、什么问题不要用这一节能有效减少 AI 的误触发。第三是执行步骤写成编号列表每步拆到 AI 能直接照着做比如第一步检查 props 是否使用解构赋值并给出默认值第二步检查组件是否拆分了 render 子模块。第四是检查清单做成表格形式左侧是检查项、右侧是判断标准。第五是测试用例包含三个示例输入与对应预期输出用来验证技能描述与实际行为一致。有个细节特别重要description字段要写会给 AI 读到的完整描述不要惜字如金也不能写成论文。我调试过很多次才发现如果 description 里只写审查组件代码AI 在多个技能候选时经常选错后来我把适用什么框架、排除什么任务都写进去命中率一下子提升了。你也可以理解为description是技能的门面它决定了 AI 会不会推门进来而正文决定了 AI 进门后能不能把事情办好两者都不能省。4.3 同步给 AI Agent 使用Obsidian 做母本配置目录做产物知识库建好只是第一步最关键的问题是Obsidian 里的技能怎么变成 AI Agent 真正能加载的 skills我的方案是Obsidian 做母本配置目录做构建产物中间靠脚本同步。具体来说Obsidian 仓库里维护着一份完整的技能文件而 AI Agent 实际读取的目录比如.claude/skills/并不直接参与编辑而是由一个同步脚本把10-Skills下status为active的技能复制过去同时带上scripts/和examples/目录。这里有个非常隐蔽的坑如果你直接复制文件过去那么在 Obsidian 里对技能做的任何修改AI 端都不会感知到必须手动跑同步脚本。所以我后来改成了一个伪软链方案在 Agent 的 skills 目录里放一个说明文件内容是此目录由 Obsidian 知识库脚本自动生成请修改 Obsidian 中的母本文件然后配合构建脚本的钩子在 Obsidian 里用 Templater 按钮一键触发同步。用代码实现一个最简单的同步脚本大概长这样#!/bin/bash SOURCE$HOME/ObsidianVault/10-Skills TARGET$HOME/.claude/skills rm -rf $TARGET mkdir -p $TARGET # 只同步 active 状态的技能目录排除草稿和废弃内容 for dir in $SOURCE/*/; do if [ -f $dir/SKILL.md ]; then # 用 grep 检查 status 字段只有 active 才同步 if grep -q status: active $dir/SKILL.md; then cp -R $dir $TARGET/$(basename $dir) echo synced: $(basename $dir) fi fi done echo Sync complete.这个脚本虽然简陋但核心逻辑是对的以status字段作为过滤条件把可用的技能同步到 Agent 目录。你完全可以根据自己的平台改成 PowerShell 版本或者接进你的自动化工作流。这种母本 构建产物的结构让我在 Obsidian 里怎么改都不怕影响 Agent 运行只有确认一个技能稳定了、把状态改成active它才会进入同步清单。5. 常见问题与避坑实录5.1 Obsidian 性能问题技能多了会不会卡有人担心 Obsidian 在技能文件超过几百个之后会卡顿我实测下来这个担心基本多余。Obsidian 是本地 Markdown 文件库对纯文本文件的索引效率非常高几百个 md 文件对它来说是小意思。真正影响性能的往往是三个因素图片等二进制附件太多、某些插件在后台频繁执行重查询、以及笔记里嵌入了大量需要渲染的代码块。我自己的库现在有三百多份笔记其中技能文件一百余个日常打开和检索都是秒开。如果你发现自己的库变卡了第一件事检查是不是有坏的 Dataview 查询在全局扫描所有文件第二件事检查是不是有大型附件混进了仓库第三件事检查插件数量。我的原则是能不用插件就不用插件目前只保留了 Dataview、Templater 和 Excalidraw 三个核心插件其他花里胡哨的一律不装。5.2 多端同步与团队协作资料在手机上怎么看知识管理有个绕不开的需求我出门在外突然想起一个技能的思路想用手机记一笔回到电脑上再整理。Obsidian 官方的 Sync 服务体验最好但需要付费免费的方案是用 Git 仓库配合 Obsidian Git 插件做自动提交推送手机上用 Obsidian 打开同一个 Git 仓库目录也能同步查看和编辑。我自己用的是 Git 方案坦白讲对新手有一定门槛但换来的是数据完全自主可控而且技能文件的版本历史对 AI 知识管理特别有价值如果某个技能改坏了我可以随时回溯到上一个版本。团队协作时我会把 Obsidian 仓库建在 Git 私有仓库上每个成员克隆下来各自维护内容定期推送合并。这里有个很重要的经验团队协作一定要约定好谁负责哪些领域的模块边界否则经常会出现两个人同时改一个技能、合并时冲突不断的情况。还要提醒一句不要指望 Obsidian 能替代真正的团队知识管理系统比如 Confluence 或者飞书文档。Obsidian 适合作为技术团队内部面向 AI 的知识底座把它当作一个专注于内容、不失真的 Markdown 源仓库而面向全公司展示的文档最终还需要有人工二次整理的环节。5.3 知识库建好却成了摆设怎么让维护形成习惯踩过最大的坑是花一天时间把知识库建得漂漂亮亮然后三个月没再打开过最后变成一个数字坟场。知识管理真正的难度不在建库而在日常维护。我后来给自己定了几条很轻的规则才让这个习惯坚持下来。第一条是收件箱清零任何随手记的新想法先丢进30-Inbox每周五花十五分钟统一整理归档不在收件箱里留超过一周的笔记。第二条是内容变更马上更新每次调整一个 AI 技能顺手就打开 Obsidian 更新对应的 SKILL.md 和updated字段不要攒到月底一起补。第三条是月度技能体检每个月末用 Dataview 拉一份全量清单检查有没有长时间没更新的技能、有没有新增但没入库的技能、有没有状态标错的技能顺便更新一下 Canvas 技能地图。这三条规则都不重但能保证知识库始终处于新鲜状态。知识管理跟健身一样最怕的不是动作不标准而是三分钟热度之后不再坚持。把维护动作压缩到每周十五分钟以内是让它可持续的关键。6. 经验与扩展这套方案还能怎么用这套用 Obsidian 管理 AI skills 的方法本质上是一种把 AI 的知识资产当作代码来维护的思路。它天然可以扩展到很多同类场景比如管理你给 AI 写的一系列提示词模板、管理 AI Agent 的工作流定义、管理你在多个 AI 平台间复用的指令集甚至是管理 AI 生成的文档和代码片段。只要是以 Markdown 为核心载体、需要频繁迭代、需要被多个消费端引用的知识内容都可以套用这套Obsidian 母本 脚本产物的架构。我自己的下一步计划是给这个知识库加上更完整的自动化链路用 Templater 做一个一键生成新技能的命令让创建技能时自动生成测试用例骨架再加一个 CI 脚本在每次 Git 提交时自动跑一遍同步逻辑把 Obsidian 里状态为active的技能推送到 AI Agent 目录。等到这些链路跑通整个知识管理流程就不再依赖人工记忆和手工操作了知识资产会像代码一样被持续集成、持续交付。最后再分享一个我个人的体会AI 的技能管理本质上是在管理经验这件事。以前人的经验写进文档、存在 wiki 里等着人去查阅现在经验写进 skills、存在知识库里等着 AI 去调用。Obsidian 很适合作为这个经验的载体但它不是终点真正的挑战在于我们能不能持续地、结构化地把自己的实践沉淀下来。保持简单、保持更新、保持可检索这套方案就能长期陪着你。
用 Obsidian 管理 AI Agent Skills：从技能包到知识网络的工程化实践
最近圈子里都在聊 AI 的 skills 机制。Claude Code 的 skills、Codex 的 skills还有 GitHub 上那些 superpower skills、baoyu skills 仓库本质上都是在给 AI Agent 装上一个个技能包一个目录、一份 SKILL.md、几个参考脚本它就能在一个具体任务上表现得更专业。我自己的配置目录里skills 文件夹不到三个月就堆了四十多个前端、测试、文档、数据清洗全部混在一起想找一个都费劲更别说让AI 实习生真正学会这些技能、在合适的场景下主动调用它们了。于是我把 Obsidian 搬了出来给这些 AI Agent skills 做了一套完整的知识管理方案。这篇文章记录的就是这套方案的完整实践适合正在大量使用 AI 编程助手、并且手上已经积累了不少 skills 文件的开发者参考。1. 先搞清楚 Skills 是什么以及为什么非要用 Obsidian1.1 Skills 机制的本质从提示词到工程化很多人第一次接触 skills 时都会有个疑问它跟我在系统提示词里写一段你是一个前端专家要遵循某某规范有什么区别其实区别大了去了。早期我们调教 AI靠的是把大段规则塞进 CLAUDE.md、或者写在项目根目录的说明文档里。这种方式最大的问题是所有知识全部叠在一起模型每次对话都要翻一遍这一大坨文本响应变慢不说真正需要的信息往往被淹没在无关内容里效果自然打折。而 skills 机制把知识拆成了一个个颗粒度更小的独立单元。每个 skill 本质上是一个文件夹里面通常包含一份带 YAML frontmatter 的 SKILL.md它负责描述这个技能的名称、适用场景和使用步骤还可以附带 scripts 脚本、references 参考资料、examples 示例等。AI Agent 拿到一个任务时会先根据任务描述去匹配各个技能的描述字段匹配上了才加载那个技能文件夹里的全部内容匹配不上就当作不存在。这有点像一个实习生手里拿着一摞岗位手册接手任务时先翻目录找到对应那本才打开细读而不是把整个书柜的书全背下来。这个设计直接改变了我们管理 AI 知识的方式知识开始以文件为单位存在每个技能可以独立更新、独立测试、独立版本化。也正因如此当 skills 数量多起来之后如何管理这些技能文件本身就变成了一个全新的工程问题。1.2 AI 实习生和管理者的知识管理痛点我习惯把 AI Agent 比作一个实习生而且是那种学习能力极强、但经验几乎为零的实习生。它记性好、响应快、执行力强问题是你不知道它脑袋里到底装了什么也不知道它什么时候会用一个过时的方案去处理新问题。我复盘了一下自己过去三个月遇到的问题基本上集中在四类。第一类是不知道有什么我明明写过好几个测试相关的 skill但真到一个需要写测试的任务时AI 没有主动调用因为 description 描述得不够准确或者干脆被我遗忘了。第二类是不知道哪个最新同一类任务我先后写过两个不同版本的 skill它们之间是什么关系哪个是替代哪个完全没有标记时间一长根本分不清。第三类是知识之间没有关联前端开发的 skill 里明明应该引用设计规范相关的 skill可它们散落在两个目录里谁也没有链接谁AI 调用时只能加载其中一个看不到完整的上下文。第四类是无法快速复用想把这个技能从我的配置里复制给团队其他成员或者迁移到新的 Agent 平台上发现目录结构混乱、依赖缺失根本没法直接给别人用。这些问题本质上跟一个普通职场新人没有知识管理习惯时遇到的问题一模一样内容在积累但结构没有建立起来于是积累得越多越混乱。如果继续靠在文件管理器里翻目录的方式去维护 skills迟早会失控。所以我当时就确定了需要引入一个工具把这些散落的技能文件变成一张有结构、有关联、可检索、可迭代的知识网络。1.3 为什么选 Obsidian本地、纯文本、可编程当时我也考虑过 Notion、语雀这样的在线笔记工具它们做团队知识库确实方便但对 skills 管理来说有个致命问题skills 的本质是给 AI 读的纯文本文件而不是给人看的在线文档。把技能内容从本地 Markdown 文件搬进在线笔记再导出用这中间多了一步格式转换还要担心平台锁死、内容同步、权限控制这些问题完全违背了以文件为单位的初衷。选择 Obsidian 有四个理由我逐一验证过都很扎实。第一它本身就是管理本地 Markdown 文件库每条笔记都是一个真实的 .md 文件跟 SKILL.md 的格式天然统一不存在格式失真。第二它支持双向链接和标签体系可以把 skill 和 skill、skill 和相关文档之间建立关联这正是传统文件夹做不到的。第三它有极强的插件生态尤其是 Dataview 和 Templater能让我把skills 清单调用频率覆盖场景这些信息自动生成出来相当于给知识库加了一个查询引擎。第四它的数据完全在本地可以用 Git 做版本管理配合 Obsidian Sync 或者其他同步盘可以多端访问不会因为某个在线服务关停导致整个知识库报废。还有一个很多人忽略的点Obsidian 对 Markdown 的支持非常干净这意味着我可以直接把 Obsidian 当作skills 的唯一事实源然后通过软链接或者构建脚本把库里的内容同步到 AI Agent 真正加载的配置目录里。这套一处维护、多处引用的架构是其他在线笔记工具很难做到的。2. 用 Obsidian 搭建 Skills 管理库目录、命名与模板2.1 目录结构与命名规范设计知识管理的第一步永远是设计结构而不是急着往里面塞内容。我踩过没有结构直接乱建的坑后来花了整整一个下午把目录推倒重来。你可以直接参考我现在的这套结构它经过了三个月的实际使用验证稳定可靠。核心思路是把技能仓库区域、Agent 配置说明区、个人备忘区彻底分开。仓库根目录下我建了三块。第一块叫10-Skills存放所有技能内容下面按照技能领域分二级目录比如frontend/、backend/、testing/、documentation/、>TABLE tags AS 标签, updated AS 最近更新, status AS 状态, description AS 描述 FROM 10-Skills WHERE file.name ! SKILL.md SORT updated DESC这段查询会把10-Skills目录下所有技能文件列成一张表格按更新时间倒序排列。如果你想只看某个领域的技能加一个WHERE contains(tags, area:frontend)就行。我把这个总览放在一个叫00-技能总览的入口笔记里每次打开 Obsidian 第一眼就能看到整个技能库的全貌。说实话有了这张表之后我再也没有在文件管理器里翻过目录。Dataview 还有一个进阶用法是用FLATTEN把 YAML 数组拆开做反向索引。比如我想知道有哪些技能引用了性能审计这个技能可以写FROM 10-Skills FLATTEN related WHERE related performance-audit一条查询就能把所有依赖关系倒查出来。这对重构技能时的影响面分析特别有用改一个底层技能之前先跑一遍反向索引看谁依赖它心里就有底了。3.3 Canvas 画布把技能地图画出来Dataview 解决的是结构化查询的问题但人脑有时候需要更直观的图景。Obsidian 自带的 Canvas 功能我用来做技能地图。具体做法很朴素在画布上以领域为分区每个技能做一张卡片卡片之间用连线标注依赖或协同关系再用颜色区分状态绿色是活跃、灰色是已废弃、黄色是草稿。这样的技能地图贴在知识库首页任何一个新加入项目的同事第一眼就能看懂整个知识库的版图前端有哪些技能、测试依赖哪些前端技能、哪个技能是全局基础能力。这比读十页文档来得都快。Canvas 我有个使用心得不要把它做成一张包罗万象、密密麻麻的大图一旦卡片超过三四百个画布就失去了意义。正确的做法是为每个领域画一张领域技能地图控制在三十张卡片以内全局只画一张高层架构图展示领域之间的关联。画布图如果过期了比没有图更误导人所以我会在每个月末花十五分钟更新一次顺便检查哪些卡片对应的技能文件确实存在避免画出幽灵节点。4. 实操案例从零管理一整套前端开发 Skills4.1 技能拆解与入库前面讲了这么多方法论这一节我用一个真实案例把它串起来。假设你手上有一堆前端开发相关的 skills 文件比如component-review.md、api-check.md、performance-audit.md、storybook-coverage.md它们散落在.claude/skills/目录里没有统一格式。现在要全部纳入 Obsidian 知识库。第一步是盘点。我把目录下所有 md 文件列出来逐个打开看一遍按照active可用、deprecated废弃、draft草稿三个状态给它们归档。这一步不需要做任何修改只需要建立认知我到底有哪些技能、每个技能的现状是什么。当时我盘下来发现有五六个技能已经明显过时了比如里面还在推荐一个已经被废弃的构建工具这种技能如果不清出来AI 随时可能被误导。第二步是拆解重组。有些技能文件实际上揉了好几件事比如api-check.md里既讲了接口契约校验又讲了 Mock 数据生成这两个场景相关性有限应该拆成两个技能。拆开之后接口契约校验归入backend领域Mock 数据生成归入frontend领域各自补充好description和tags。第三步是文件夹落地每个技能新建一个编号-技能名称文件夹放入重整后的SKILL.md再补上示例和参考文件的链接入口。整个入库过程最花时间的既不是写文档也不是设标签而是想清楚每个技能的边界。技能拆得过细AI 匹配时容易犹豫不决拆得过粗调用时又会夹带太多无关内容。我的经验是一个技能应该能在一千字以内讲清楚使用步骤超过这个体量就考虑拆判断标准是这个技能被调用时AI 需要关注的上下文是否聚焦在一个场景上。4.2 编写标准 SKILL.md给 AI 和人都能看懂的文档入库之后要给每个技能补齐一份标准格式的 SKILL.md。我以前端组件代码审查这个 skills 为例展示一下核心结构。Frontmatter 部分--- name: component-review description: 用于对前端 React 组件进行代码审查检查组件拆分、状态管理、样式隔离、可访问性和性能隐患。适合在提交 PR 前对组件代码做系统检查不适用于整站架构评审。 tags: - area:frontend - type:review - level:intermediate status: active version: 2.3.0 updated: 2025-06-15 related: - performance-audit - design-token-check ---正文部分我一般分五个小节。第一是技能目标用三到五句话说明这个技能完成后会得到什么产出比如输出一份按严重级别分组的组件问题清单并给出修复建议。第二是适用场景与禁用场景写清楚什么问题用它、什么问题不要用这一节能有效减少 AI 的误触发。第三是执行步骤写成编号列表每步拆到 AI 能直接照着做比如第一步检查 props 是否使用解构赋值并给出默认值第二步检查组件是否拆分了 render 子模块。第四是检查清单做成表格形式左侧是检查项、右侧是判断标准。第五是测试用例包含三个示例输入与对应预期输出用来验证技能描述与实际行为一致。有个细节特别重要description字段要写会给 AI 读到的完整描述不要惜字如金也不能写成论文。我调试过很多次才发现如果 description 里只写审查组件代码AI 在多个技能候选时经常选错后来我把适用什么框架、排除什么任务都写进去命中率一下子提升了。你也可以理解为description是技能的门面它决定了 AI 会不会推门进来而正文决定了 AI 进门后能不能把事情办好两者都不能省。4.3 同步给 AI Agent 使用Obsidian 做母本配置目录做产物知识库建好只是第一步最关键的问题是Obsidian 里的技能怎么变成 AI Agent 真正能加载的 skills我的方案是Obsidian 做母本配置目录做构建产物中间靠脚本同步。具体来说Obsidian 仓库里维护着一份完整的技能文件而 AI Agent 实际读取的目录比如.claude/skills/并不直接参与编辑而是由一个同步脚本把10-Skills下status为active的技能复制过去同时带上scripts/和examples/目录。这里有个非常隐蔽的坑如果你直接复制文件过去那么在 Obsidian 里对技能做的任何修改AI 端都不会感知到必须手动跑同步脚本。所以我后来改成了一个伪软链方案在 Agent 的 skills 目录里放一个说明文件内容是此目录由 Obsidian 知识库脚本自动生成请修改 Obsidian 中的母本文件然后配合构建脚本的钩子在 Obsidian 里用 Templater 按钮一键触发同步。用代码实现一个最简单的同步脚本大概长这样#!/bin/bash SOURCE$HOME/ObsidianVault/10-Skills TARGET$HOME/.claude/skills rm -rf $TARGET mkdir -p $TARGET # 只同步 active 状态的技能目录排除草稿和废弃内容 for dir in $SOURCE/*/; do if [ -f $dir/SKILL.md ]; then # 用 grep 检查 status 字段只有 active 才同步 if grep -q status: active $dir/SKILL.md; then cp -R $dir $TARGET/$(basename $dir) echo synced: $(basename $dir) fi fi done echo Sync complete.这个脚本虽然简陋但核心逻辑是对的以status字段作为过滤条件把可用的技能同步到 Agent 目录。你完全可以根据自己的平台改成 PowerShell 版本或者接进你的自动化工作流。这种母本 构建产物的结构让我在 Obsidian 里怎么改都不怕影响 Agent 运行只有确认一个技能稳定了、把状态改成active它才会进入同步清单。5. 常见问题与避坑实录5.1 Obsidian 性能问题技能多了会不会卡有人担心 Obsidian 在技能文件超过几百个之后会卡顿我实测下来这个担心基本多余。Obsidian 是本地 Markdown 文件库对纯文本文件的索引效率非常高几百个 md 文件对它来说是小意思。真正影响性能的往往是三个因素图片等二进制附件太多、某些插件在后台频繁执行重查询、以及笔记里嵌入了大量需要渲染的代码块。我自己的库现在有三百多份笔记其中技能文件一百余个日常打开和检索都是秒开。如果你发现自己的库变卡了第一件事检查是不是有坏的 Dataview 查询在全局扫描所有文件第二件事检查是不是有大型附件混进了仓库第三件事检查插件数量。我的原则是能不用插件就不用插件目前只保留了 Dataview、Templater 和 Excalidraw 三个核心插件其他花里胡哨的一律不装。5.2 多端同步与团队协作资料在手机上怎么看知识管理有个绕不开的需求我出门在外突然想起一个技能的思路想用手机记一笔回到电脑上再整理。Obsidian 官方的 Sync 服务体验最好但需要付费免费的方案是用 Git 仓库配合 Obsidian Git 插件做自动提交推送手机上用 Obsidian 打开同一个 Git 仓库目录也能同步查看和编辑。我自己用的是 Git 方案坦白讲对新手有一定门槛但换来的是数据完全自主可控而且技能文件的版本历史对 AI 知识管理特别有价值如果某个技能改坏了我可以随时回溯到上一个版本。团队协作时我会把 Obsidian 仓库建在 Git 私有仓库上每个成员克隆下来各自维护内容定期推送合并。这里有个很重要的经验团队协作一定要约定好谁负责哪些领域的模块边界否则经常会出现两个人同时改一个技能、合并时冲突不断的情况。还要提醒一句不要指望 Obsidian 能替代真正的团队知识管理系统比如 Confluence 或者飞书文档。Obsidian 适合作为技术团队内部面向 AI 的知识底座把它当作一个专注于内容、不失真的 Markdown 源仓库而面向全公司展示的文档最终还需要有人工二次整理的环节。5.3 知识库建好却成了摆设怎么让维护形成习惯踩过最大的坑是花一天时间把知识库建得漂漂亮亮然后三个月没再打开过最后变成一个数字坟场。知识管理真正的难度不在建库而在日常维护。我后来给自己定了几条很轻的规则才让这个习惯坚持下来。第一条是收件箱清零任何随手记的新想法先丢进30-Inbox每周五花十五分钟统一整理归档不在收件箱里留超过一周的笔记。第二条是内容变更马上更新每次调整一个 AI 技能顺手就打开 Obsidian 更新对应的 SKILL.md 和updated字段不要攒到月底一起补。第三条是月度技能体检每个月末用 Dataview 拉一份全量清单检查有没有长时间没更新的技能、有没有新增但没入库的技能、有没有状态标错的技能顺便更新一下 Canvas 技能地图。这三条规则都不重但能保证知识库始终处于新鲜状态。知识管理跟健身一样最怕的不是动作不标准而是三分钟热度之后不再坚持。把维护动作压缩到每周十五分钟以内是让它可持续的关键。6. 经验与扩展这套方案还能怎么用这套用 Obsidian 管理 AI skills 的方法本质上是一种把 AI 的知识资产当作代码来维护的思路。它天然可以扩展到很多同类场景比如管理你给 AI 写的一系列提示词模板、管理 AI Agent 的工作流定义、管理你在多个 AI 平台间复用的指令集甚至是管理 AI 生成的文档和代码片段。只要是以 Markdown 为核心载体、需要频繁迭代、需要被多个消费端引用的知识内容都可以套用这套Obsidian 母本 脚本产物的架构。我自己的下一步计划是给这个知识库加上更完整的自动化链路用 Templater 做一个一键生成新技能的命令让创建技能时自动生成测试用例骨架再加一个 CI 脚本在每次 Git 提交时自动跑一遍同步逻辑把 Obsidian 里状态为active的技能推送到 AI Agent 目录。等到这些链路跑通整个知识管理流程就不再依赖人工记忆和手工操作了知识资产会像代码一样被持续集成、持续交付。最后再分享一个我个人的体会AI 的技能管理本质上是在管理经验这件事。以前人的经验写进文档、存在 wiki 里等着人去查阅现在经验写进 skills、存在知识库里等着 AI 去调用。Obsidian 很适合作为这个经验的载体但它不是终点真正的挑战在于我们能不能持续地、结构化地把自己的实践沉淀下来。保持简单、保持更新、保持可检索这套方案就能长期陪着你。