如果你在自己的笔记软件里搜过 skills大概率会翻出一堆半年前收藏的文章、几个再也没打开过的文件夹甚至还有一份写着“技能树”但只有根节点的脑图。我最初把项目标题定为 skills 时想法很朴素把所有想学、该学、正在学的东西全部收进去。结果一个月后里面躺了八十多个条目真正能用上的不到五个。后来我把这八十多个条目删掉重新用一个非常笨的方法整理反而让这套体系活了过来。这篇文章想说的就是这套被反复折腾后的方法它适合所有想把技能从“知道”变成“做到”、从零散收集变成可复用方法的人。1. 从名称说起skills 到底在解决什么问题1.1 大多数人理解错了“技能”技能不是知识。你看完十篇关于某个概念的文章不代表你拥有这项技能只能说明你增加了信息存量。真正的技能是在特定条件下能稳定地交付一个结果的能力。这个概念听起来像废话但我在整理 skills 的过程中发现绝大多数人包括当时的我都把“收藏资料”误当成了“掌握技能”。你可以把知识类比成菜谱把技能类比成炒菜。菜谱告诉你什么食材、什么火候、什么步骤但如果你从没在锅里实操过没经历过火开太大导致糊锅、盐放多了补救不回来这类真实状况你就不能说“我会做这道菜”。技能必须经过实践验证必须有一个明确的“完成”状态。所以搭建技能体系的第一步不是到处找教程而是先定义清楚对你来说什么叫做“会了”。另一个常见的误解是把技能拆得太碎。我最初会写“了解某命令行工具”“读过某框架文档”这种条目后来发现它们既没有触发场景也没有输出产物根本称不上技能。真正值得写进 skills 目录里的应该是“排查某个服务不可用”“生成一份竞品分析报告”“做一次高质量的代码评审”这类可以独立执行、可以判断成败的事情。1.2 我想要的 skills 不是收藏夹收藏夹的核心动作是“获取”而技能库的核心动作是“调用”。收藏夹带来的快感是瞬间的一篇文章存进去大脑就会产生一种“我已经掌握了”的错觉技能库带来的回报是迟到的你必须反复调用、修正、验证才能感受到它的价值。这也是为什么很多人建技能库会失败因为他们仍然在用收藏夹的逻辑做技能库只是换了一个文件夹继续囤积。我想要的是三件事快速检索、可执行、可演进。快速检索意味着当问题出现时我能立刻找到对应的解决路径而不是靠回忆在脑子里搜刮可执行意味着技能卡里的内容要能直接指导行动而不是一段含糊的心得可演进意味着每一次调用都会留下记录让这张卡越用越准确而不是永远停留在刚写好的状态。所以后来我给自己定了一个非常朴素的原则如果一个条目写完之后在未来一个月内没有任何场景可能触发它那就暂时不要进入技能库。你可以把它放在“探索清单”里但不能混进技能库。这条原则帮我砍掉了至少一半的无效内容。2. 整体设计与思路拆解先设计再动手避免建一个没人用的库2.1 先定义技能 可重复执行的解决问题流程在开始搭目录、写文件之前我建议先把“技能”的定义固定下来。我最喜欢的公式是技能 触发场景 前置条件 操作流程 输出产物 验收标准。触发场景是指“在什么情况下你会用到这项技能”。比如“每周一上午要生成上周的线上数据周报”这是一个触发场景而“学会数据分析”不是触发场景它是一个太宽泛的主题。前置条件是指“开始执行前需要准备什么”可能是数据源权限、目标文件地址、某个软件已经安装也可能是某个决策已经确定。写清楚前置条件可以避免你在执行到一半时才发现自己缺东少西。操作流程是技能卡的主体但我建议只保留核心步骤控制在五到七个以内。步骤太多说明这项技能还不够原子化需要先拆分成子技能。输出产物是你完成操作后得到的东西它可以是一份文档、一个被修复的问题、一张表也可以是一个明确的决策。验收标准决定了“这件事做成了”的判断依据如果没有这个步骤技能卡就退化成了一篇笔记。生活里最常见的例子是“做一顿饭”。你会的其实不是“做饭”这个技能而是“西红柿鸡蛋面”“清蒸鲈鱼”这样有明确步骤和成品的子技能。技能库也应该这样每个技能卡对应一道拿手菜而不是对应整个厨房。2.2 四层技能分类法先分清哪些技能值得沉淀分类不是目的分类是为了决定“投入多少精力”。我把技能分成四层核心技能、支撑技能、边缘技能、探索技能。核心技能决定你主要产出的质量。对程序员来说可能是“系统性地排查复杂问题”“设计可维护的接口”对内容创作者来说可能是“把复杂概念讲清楚”“持续稳定地产出内容”。核心技能需要反复打磨值得你投入整块时间去练习和复盘。支撑技能是配合核心技能使用的高频技能。例如做复杂问题排查时需要“高效检索文档”“结构化记录实验过程”它们不一定是核心但没有它们核心技能施展不开。支撑技能不需要像核心技能那样强化训练但必须足够熟练至少不能卡住你。边缘技能是偶尔用到、知道关键思路即可的东西“要用时再搜就行”。探索技能则是你感兴趣、未来可能进入核心圈层的方向现在只需要保持低成本关注。给一个简单的对照表层级定义沉淀策略更新频率核心技能决定主要产出质量完整技能卡 反复练习每次调用后都更新支撑技能配合核心技能高频出现标准技能卡 关键参数每月整理边缘技能偶尔使用知道思路即可一句话备忘 链接半年清理一次探索技能未来可能存在价值单条清单记录季度检查这套分类解决了一个核心问题资源分配。很多人搭建技能库失败是因为把所有技能都当成核心技能来写每张卡都要求图文并茂结果维护成本爆炸。更聪明的做法是不同层级的技能用不同的详细程度去沉淀核心技能才配拥有完整格式。2.3 技术选型为什么我坚持用纯文本而不是花哨软件最早我尝试过各种在线笔记工具和双链笔记软件它们确实好看也能建可视化关系图。但它们有两个问题第一专有格式天然存在迁移成本平台一旦调整功能你的“技能库”就跟着变形第二可视化关系图看起来很酷但真正维护起来需要花费大量精力去连接节点而这些连接在实际调用时往往用不上。我最后的选择非常朴素一个普通的文件夹里面全是 Markdown 文件文件头部用 YAML 写结构化字段再配一个极简的检索脚本。这套组合的好处是文本可以被版本管理工具记录变更可以跨设备同步可以被命令行工具和脚本处理也可以随时改成任何新的呈现形式。就算将来换了工作流这些 .md 文件依然能原封不动地迁移过去。如果你喜欢可视化可以把可视化界面当作“门面”把纯文本文件当作“底层数据库”。这样既满足了直观浏览的需求又不会让你的核心资产被困在某一个专有格式里。对我个人来说工具越简单维护的动力越强一旦引入复杂工具我大部分精力都会花在整理工具本身而不是打磨技能内容。3. 核心细节解析与实操要点技能卡的编写规范3.1 技能卡的最小字段设计够用但不过度我踩过的第一个坑是一开始写的技能卡像长篇小说背景、原理、截图、评论样样俱全。结果真到用时我根本不想打开它因为信息密度太低。后来我把技能卡压缩成最小字段名称、别名、适用场景、前置条件、核心步骤、输出产物、验收标准。这里最关键的是“别名”。人脑的检索词和文件名经常不一致。例如我有一张卡叫“每周复盘”但我日常想到的往往是“总结”“周报”如果不在别名里写明这些词搜索时就容易漏掉。别名是为“未来的你”准备的你越多写一些自己平时会用的说法这张卡就越容易被找到。一个最小可用的技能卡模板大概是这样的--- name: 生成竞品分析报告 alias: [竞品分析, 竞品调研, competitor-analysis] domains: [产品, 研究] level: applied status: active last_used: 2024-06-08 --- # 生成竞品分析报告 ## 适用场景 需要了解某个产品或方向的市场竞争格局。 ## 前置条件 确定目标产品收集可用的公开数据源。 ## 核心步骤 1. 明确分析维度功能、价格、目标用户、运营策略 2. 按维度收集信息 3. 整理成对比表格 4. 提炼差异点和机会点 5. 输出结论 ## 输出产物 一份含对比表与结论的 Markdown 报告。 ## 验收标准 每个维度都有至少一条真实数据支撑结论能被一句话概括。这个模板并不复杂但它已经足够让一张技能卡“自洽”。有了输出产物和验收标准你就不会在调用技能时自我欺骗。3.2 技能卡进阶触发条件、验收标准、复盘记录最小字段只是骨架进阶版需要加入三样东西触发条件、复盘记录、依赖关系。触发条件和适用场景略有不同。适用场景描述的是“什么情况下能用”触发条件更强调“什么时候应该主动想起它”。例如适用场景是“项目上线前需要评估风险”触发条件是“当项目经理发来上线计划时我需要立刻打开这张卡”。触发条件写得越具体越接近你真实的决策时刻。复盘记录是技能卡能够演化升级的关键。我习惯在每张卡末尾留出一个“复盘记录”区域## 复盘记录 - 2024-06-10用时 40 分钟比预期长原因是数据源分散下次先把数据源清单放在前置条件里。 - 2024-06-18按新前置条件执行用时 25 分钟结论质量提升。这里有一个小技巧复盘不要当天做至少隔一天再做。刚完成技能调用时你的记忆里还带着大量侥幸和情绪很容易认为“这次效果不错是因为我很熟练”。隔一天再回看你会更客观地看到流程里真正的瓶颈。依赖关系可以简单地用links:字段记录表示这张卡依赖哪些其他技能卡或资料。但我不建议把它扩展成复杂的知识图谱维护成本会指数上升。只要记录“做报告前要先拉数据”这种直接影响执行的前置技能就够了。3.3 命名与目录组织找不到的技能等于不存在技能文件命名直接决定检索效率。我建议使用“动宾短语”让文件名本身就说明这件事要做什么。比如“排查服务不可用.md”“生成竞品分析报告.md”“回复用户负面评价.md”。反面例子是“数据分析.md”“机器学习基础.md”这些是主题名称不是技能名称。看到前者你能大致猜到里面写了什么看到后者你什么都猜不到。目录结构也不宜过深最多两层。我当前的结构是这样skills/ README.md work/ write-report.md run-weekly-review.md tech/ debug-service.md recover-data.md communication/ pushback-request.md write-meeting-notes.md每个领域一个子目录内部文件全部使用动宾短语命名。这样就算半年没碰这份技能库只要扫一眼文件名也能快速判断卡片内容。再配合前面说过的 alias 字段检索时既可以走目录浏览也可以走关键词搜索两条路都不会断。4. 实操过程与核心环节实现从想法到一套可复用的技能库4.1 第一版用 Markdown 先跑通流程我建议任何人在搭建技能库时都不要先去写脚本或设计数据库先把最近三个月里反复做过的事情写成十张技能卡。这个步骤听起来很简单但它能逼你思考哪些事情真正高频出现哪些只是偶然发生。我当时做的第一件事是新建一个skills文件夹然后回忆过去几周里做过的事写周报、做需求评审、排查接口报错、整理项目文档、给同事讲方案。这些事都满足“触发场景明确、有输出产物、可以判断成败”的条件。于是我按照最朴素的 Markdown 格式每个事件写一个文件只写步骤和输出不写任何背景故事和感悟。用了一周之后问题很快就出现了文件一旦多起来光靠操作系统自带的文件搜索根本不够用。因为我会记得“排查问题”这件场景但忘了当时把文件叫“定位接口500错误.md”还是“debug-api.md”。于是我开始写 README 索引把技能名称、路径、触发场景列成一张表。但手动维护带动不了几天我又开始考虑给文件加上结构化字段让脚本能够自动生成索引和搜索入口。4.2 第二版用 YAML front matter 让内容可被程序读取Markdown 本身适合人阅读但机器不好处理。我借鉴了静态站点生成和文档系统里常见的做法在.md文件头部加一段 YAML front matter用键值对描述技能元信息。这样文件既能被人类直接阅读也能被脚本解析。YAML 是最适合做这件事的格式之一。它比 JSON 更容易手工编辑不需要各种引号和大括号也天然支持注释。唯一的注意点是不要把所有信息都塞进 YAML 里YAML 只放检索和判断需要的数据正文仍然保留给操作流程和细节。一个典型的 YAML front matter 看起来是这样--- name: 排查服务不可用 alias: [服务挂了, 排查宕机, service-down] domains: [运维, 问题排查] trigger: 用户反馈无法访问接口连续超时 status: active last_used: 2024-06-20 ---这里的trigger字段非常重要它是你在真实场景中“触发调用”的信号。写清楚触发条件后这张卡就不会只是一份静态文档而是成为一个有生命周期的工具。4.3 第三版写一个极简的检索脚本当文件越来越多时用眼睛翻目录已经不够了。我写了一个只有几十行的 Python 脚本遍历所有.md文件解析 YAML front matter然后按关键词搜索技能卡的名称、别名、领域和触发条件把所有匹配项输出到终端。脚本并不复杂核心逻辑如下import sys from pathlib import Path def parse_front_matter(text): if not text.startswith(---): return {} end text.find(---, 4) if end -1: return {} raw text[4:end] data {} for line in raw.strip().splitlines(): if : not in line: continue key, _, value line.partition(:) key key.strip() value value.strip() if key in (alias, domains): data[key] [v.strip() for v in value.strip([]).split(,)] else: data[key] value return data def search_skills(keyword, base_dirskills): hits [] for path in Path(base_dir).rglob(*.md): text path.read_text(encodingutf-8) data parse_front_matter(text) searchable \n.join([ data.get(name, ), .join(data.get(alias, [])), .join(data.get(domains, [])), data.get(trigger, ), path.name ]).lower() if keyword.lower() in searchable: hits.append((path, data)) return hits if __name__ __main__: keyword sys.argv[1] if len(sys.argv) 1 else if not keyword: print(使用方法: python search_skill.py 关键词) sys.exit(0) for path, data in search_skills(keyword): print(f[{data.get(name, path.stem)}] triger{data.get(trigger, )}) print(f {path})用这个脚本我只需要输入“宕机”“排查”“报告”等关键词就能立刻定位到对应技能卡。它没有使用任何外部依赖只靠 Python 标准库就能跑。如果你不写 Python用 shell 脚本配合 grep 也能达到类似效果但结构化字段解析还是用 Python 更省心。4.4 把技能卡变成智能体真正能用的 skills近两年我经常关注智能体应用的方向那里的 “skills” 和我一直在整理的技能卡有很多共通之处。很多智能体框架希望模型能够调用一组预先定义好的技能而这些技能本质上就是“输入 操作步骤 输出格式”的描述。我发现只要技能卡从一开始就写清楚了触发条件、输入输出和验收标准它完全可以被改造成智能体可调用的模块。区别在于写给自己的技能卡允许有大量隐式信息因为你自己知道很多背景知识但写给智能体的技能描述必须把所有关键信息显式化。例如我自己的技能卡可能写“分析竞品然后整理成表格”但智能体版本需要写清楚输入是什么格式、输出是什么格式、步骤中每一步的操作对象是什么。一个面向智能体的 skill 描述可以长这样name: generate_competitor_report description: 根据目标产品关键词生成一份结构化的竞品分析报告。 input: product: 目标产品名称 dimensions: [功能, 价格, 用户群, 运营策略] output: format: markdown sections: [概述, 对比表, 差异点, 结论] steps: - collect_data - organize_table - extract_insights - write_conclusion这套能力其实就藏在我们前面维护的技能卡里。做好个人技能库将来把高频技能变成智能体技能只是换个表达方式而已。这也是为什么我一直建议用结构化字段而不是自由书写因为你永远不知道未来哪个场景需要把这段文本交给机器处理。5. 常见问题与排查技巧实录5.1 技能写完了但查不到这是最常遇到的问题。明明写过一张卡但过两周想用的时候怎么搜都搜不到最后只能恨自己当时为什么要用那么文艺的文件名。问题的根源通常有两个关键词不匹配和目录层级太深。我的解决方法是把平时口语里会用到的所有说法都写进alias。比如我写“周复盘”但现实中常说的是“周报”“总结”“weekly”于是这些词全部进别名。同时检索脚本会把trigger也纳入搜索范围因为很多技能的名字和触发场景并不保持一致。5.2 技能卡太长根本看不进去写技能卡的时候人容易陷入“写详细一点才安心”的误区。我第一张技能卡写了差不多三千字后来发现真正执行时我根本不会去读那段长叙述只会扫一眼步骤列表。因为调用技能的场景通常带点压力你希望三分钟之内想起关键路径而不是五分钟后还在看背景介绍。我的新标准是一张卡不超过一页 A4。如果内容确实多就拆成两张卡一张是执行卡只保留最核心的路径一张是“参考资料”附件存详细说明和链接。执行卡用来调用附件用来补充两者分开才能兼顾效率与深度。5.3 熟练度评估流于形式很多人在技能库里喜欢给技能打等级标签比如“了解”“掌握”“熟练”。但这里有一个大问题这些标签没有任何验证成本容易变成自我安慰。我昨天给自己打了一个“熟练”今天有可能就忘了具体怎么做这个“熟练”根本没有参考价值。我更推荐用行为指标代替等级最近使用日期、复用次数、成功率。字段里维护last_used如果一张卡超过三个月没有被调用就把它标记为dormant也就是休眠状态。这比主观评价“我的这个技能还不够熟练”要准确得多因为你可以看到真实的调用频率和结果。5.4 技能越攒越多不知道怎么维护技能库和仓库一样是有熵增的。最初三十张卡时每张都能记住位置到两百张时你连里面有什么都想不起来。为了避免这种情况我给自己定了三条硬规矩。首先新增一张技能卡前必须先检查是否已经存在类似卡片如果存在就更新旧卡而不是新建。其次每个季度做一次技能审计把过去三个月内没有被last_used的卡挑出来先标为dormant再过一季如果仍然没有唤醒就删除或归档。最后控制总量核心技能加支撑技能尽量不超过五十张超出这个数量说明分类粒度有问题需要合并。下面是一张问题速查表问题可能原因解决思路搜不到技能命名/别名不一致补充 alias 并统一检索关键词卡太长不看单卡职责过大拆分卡把细节移到附件评估流于形式使用主观等级改用 last_used 和调用次数维护成本过高存量膨胀季度审计 总量上限5.5 独家避坑技巧保存失败现场比保存成功心得更值钱这是我在维护技能库过程里最大的发现。成功案例里的步骤通常会被大脑自动美化你会觉得“这一步本来就该这么走”但失败现场里记录下来的坑才是真正能帮你避开下一次同类错误的关键信息。所以我在技能卡里专门留了一节叫“坑点记录”只记失败或者不顺利的情况。比如“执行到第 4 步时发现数据源需要额外权限”“输入文件必须是 UTF-8 编码否则解析报错”。这些内容看起来不起眼但在真实调用时价值极高。甚至可以说一张技能卡如果没有坑点记录那它大概率还没有经历过足够多真实考验。6. 踩坑后的几条心得整理如果你打算开始维护一套自己的 skills我想把最终这几条心得放在最后当作一个过来人的直接提醒。第一技能卡是写给未来那个“焦头烂额”的自己看的不是写给老师看的。你不需要用书面语不需要解释概念来源只需要让未来的自己一眼看懂“先做什么、后做什么、怎么判断做完”。我过去总想把技能卡写得系统化后来发现真正有用的往往是那些简单到有点粗糙的操作路径。第二最好的写卡时机是刚刚解决完问题的三十分钟内。这时候你对过程中的坑点记得最清楚大脑还没来得及把失败美化成“按部就班”。拖到下周再写你只会留下“我好像处理过这个问题”的感觉但具体细节早就丢了。第三没有调用场景的技能是负债不是资产。每张卡都占用你的注意力和维护精力与其囤一堆“未来可能会用”的技能不如只保留已经反复调用过三次以上的技能。新想法可以放在探索清单里等它真正在你工作里反复出现再转正成为正式技能卡。最后再分享一个小技巧我会给每张技能卡设置一个“废弃日期”到期后如果没有被调用就直接归档。归档不是删除而是把它移到一个单独的旧文件夹里。这样做的好处是你既能保持当前技能库干净又不担心错过未来某一天需要用到的内容。整理技能库这件事本质上是在整理你和未来自己的协作方式。技能从来不是越多越好而是越顺手上手越好。