1. 从"skills"这个模糊词说起：它到底指什么

第一次看到"skills"这个标题，加上一堆热搜词里混着 Claude Code、Codex、agents、plugin，我脑子里第一反应是：这大概率不是指人类职业技能，而是指 AI 编程助手生态里的Agent Skills——也就是给 AI 代理挂载的一套可复用能力包。这个判断不是拍脑袋，而是从热搜词的组合逻辑推出来的：claude agent skills: a first principles deep dive、codex skills、codex好用的skills、skills开发、skills推荐这几个词同时出现，说明讨论的焦点是"怎么给 AI 代理装技能、怎么开发技能、哪些技能好用"。

先把概念钉死。所谓 Agent Skills，本质上是一种结构化的能力描述单元，通常以文件夹或配置文件的形式存在，里面包含一段说明（告诉模型这个技能是干什么的）、若干指令（告诉模型怎么执行）、以及可选的脚本或资源（真正干活的代码）。它和传统插件的区别在于：插件是给宿主程序调用的二进制或模块，而 Skills 是给语言模型阅读并理解的自然语言加代码混合体。模型读完技能描述后，自己决定什么时候调用、怎么组合。

这个区别非常关键，直接决定了 Skills 的设计哲学。传统插件开发你要考虑 API 签名、内存管理、线程安全；Skills 开发你要考虑的是提示词工程、上下文预算、触发条件的清晰度。我见过太多人拿写插件的思路去写 Skills，结果模型根本不知道什么时候该用它，或者用了之后输出一堆废话。这不是模型笨，是技能描述写得像 API 文档，缺少"什么时候用我"的语义线索。

那 Skills 解决了什么问题？最直接的痛点是上下文膨胀。你不可能把所有工具的使用说明都塞进系统提示词里，那样还没开始干活上下文就满了。Skills 的思路是"按需加载"：平时只留一个技能名和一句话简介，模型判断需要时才把完整说明读进来。这就像你电脑里装了几百个软件，但只有双击打开的那个才占用内存。这个类比我觉得挺贴切，理解了这个，后面很多设计取舍就顺了。

适合谁来读这篇？三类人：一是刚接触 Claude Code 或 Codex、想搞清楚 skills 到底怎么装怎么用的新手；二是已经会用但想自己开发 skills 的进阶用户；三是被各种安装报错、代理配置问题折磨过的实战派。下面我会把这几条线都串起来讲，尽量说人话，把踩过的坑摊开。

2. Skills 的运行机制：模型是怎么"学会"一项技能的

2.1 渐进式披露：为什么技能不能一次性全塞进去

要理解 Skills 为什么长这样，得先理解大模型的一个硬约束：上下文窗口是有限且昂贵的资源。假设你有 50 个技能，每个技能完整说明 800 字，全塞进系统提示就是 4 万字，还没开始对话就烧掉一大截预算，而且模型在超长上下文里的注意力会稀释，容易"看了后面忘了前面"。

渐进式披露（progressive disclosure）就是针对这个问题的解法。它把技能信息分成三层：

• 第一层：元数据。只有技能名和一句话描述，常驻上下文，成本极低。模型靠这一层判断"这个任务可能用得上哪个技能"。
• 第二层：技能正文。当模型决定使用某个技能时，才把完整的 SKILL.md 读进来，包含详细步骤、注意事项。
• 第三层：附属资源。技能正文里引用的脚本、模板、参考文档，只有真正执行到那一步才加载。

这个分层设计的好处是，上下文占用随任务复杂度动态增长，而不是一上来就顶满。我实测过一个对比：把 20 个技能平铺进系统提示，模型在第三个问题之后就开始出现指令遗忘；改成渐进式披露后，连续十几轮对话依然能准确调用正确的技能。差距非常明显。

2.2 触发条件：模型凭什么知道该用哪个技能

这是 Skills 开发里最容易翻车的地方。很多人写完技能发现模型压根不调用，或者乱调用。根因几乎都出在触发条件的描述上。

模型判断是否使用一个技能，靠的是把当前任务和技能描述做语义匹配。所以你的技能描述里必须包含用户可能说出的关键词和场景。举个反例，我早期写过一个技能叫"数据处理助手"，描述是"用于处理数据"。结果模型从来不用它，因为"处理数据"太泛了，任何任务都能沾边，反而匹配不上具体意图。后来改成"当用户需要清洗 CSV、去重、填充缺失值、或做列格式转换时使用"，调用率立刻上来了。

这里有个经验法则：技能描述要写得像"用户会怎么问"，而不是"这个技能是什么"。前者是检索导向，后者是文档导向。模型做的是检索匹配，不是阅读理解考试。

2.3 技能与工具调用的边界

还有一个常见困惑：Skills 和 function calling（工具调用）是什么关系？我的理解是，两者是互补而非替代。工具调用解决的是"模型能执行一个确定性动作"，比如查天气、发请求；Skills 解决的是"模型知道一套完成复杂任务的流程和知识"。

打个比方，工具调用是给你一把锤子，Skills 是给你一本《怎么用这套工具装修一间房》的手册。手册里会告诉你先干什么后干什么、遇到什么问题换什么工具。所以一个成熟的 Skills 往往内部会调用多个工具，而工具本身不知道 Skills 的存在。

理解了这层关系，你在设计技能时就不会纠结"这个逻辑该写成工具还是写成技能"。判断标准很简单：确定性的、单步的、需要精确参数的动作，做成工具；需要判断、需要多步、需要领域知识的流程，做成技能。

3. 环境搭建：Claude Code 与 Codex 的安装路径差异

3.1 两条主流路线：命令行工具与编辑器集成

热搜词里claude code安装、codex安装教程、vscode配置claude code、claude code for vs code反复出现，说明安装是大家最关心的第一步。目前主流有两条路线：

• 命令行工具（CLI）：直接在终端里跑，适合喜欢键盘流、需要脚本化调用的用户。
• 编辑器集成：作为 VS Code 等编辑器的扩展运行，适合边写代码边对话的场景。

两条路线不是二选一，很多人是都装。CLI 适合跑批处理任务和自动化，编辑器集成适合交互式开发。我自己的习惯是：探索性任务用编辑器集成，因为能看到文件树和 diff；重复性任务用 CLI，方便写进脚本。

安装前有个前置条件必须确认：运行环境。Claude Code 和 Codex 这类工具通常依赖 Node.js 运行时，版本太低会直接报错。我建议先把 Node 升到当前 LTS 版本，能省掉一大半莫名其妙的报错。热搜里ubuntu配置claude code、claude code windows说明跨平台问题不少，Windows 用户尤其注意路径分隔符和权限问题，Linux 用户注意全局安装时的权限。

3.2 安装过程中的高频报错与应对

热搜词里有个很扎眼的：cc switch local proxy failed while handling codex endpoint /responses。这类报错通常出现在切换配置或代理转发环节。我的排查思路是分三步：

1. 确认端点地址是否正确。配置里写的 endpoint 和实际服务地址必须完全一致，多一个斜杠少一个斜杠都可能失败。
2. 确认本地转发服务是否真的起来了。很多时候是转发进程没启动，或者端口被占用。
3. 确认请求格式。不同工具对/responses这类端点的请求体结构要求不同，格式不对会被直接拒绝。

另一个高频问题是codex无法加载组织设置。这个多半和账号权限或配置文件的组织字段有关。我的做法是先把配置文件备份，然后清空组织相关字段，用最小配置跑通，再逐步加回来定位是哪一项出的问题。这种"二分法排查"在配置类问题里屡试不爽。

提示：安装类问题九成出在环境变量和配置文件上。遇到报错先别急着搜，先把配置文件完整打印出来看一遍，往往一眼就能发现问题。

3.3 本地模型接入：把 Skills 跑在自己的模型上

热搜里claude code 调用lmstudio的本地模型和codex接入deepseek指向同一个需求：不想依赖云端，想把 Skills 生态接到本地或第三方模型上。这条路可行，但有几个坑要提前知道。

第一，模型能力差异。Skills 的渐进式披露机制依赖模型有较强的指令遵循和语义匹配能力。小参数量的本地模型在这两点上往往不达标，表现为技能调用不准、指令执行不完整。我的建议是本地模型至少选中等参数量以上的，否则体验会很割裂。

第二，接口兼容性。很多工具默认走特定厂商的 API 格式，接第三方模型时需要做格式适配。常见做法是本地起一个转发层，把请求格式转换成目标模型能接受的格式。这就是为什么热搜里会出现各种 endpoint 报错——转发层没配对。

第三，上下文长度。Skills 机制本身就要吃上下文，本地模型如果上下文窗口小，渐进式披露的优势会被压缩。选模型时把上下文长度作为硬指标之一。

4. 开发一个能用的 Skill：从结构到落地

4.1 技能目录的标准结构

一个规范的 Skill 通常长这样：

my-skill/ ├── SKILL.md # 技能主文件，含元数据和正文 ├── scripts/ # 可执行脚本 │ └── process.py ├── references/ # 参考文档 │ └── api-notes.md └── assets/ # 模板、示例文件 └── template.txt

SKILL.md是核心，开头是 YAML 格式的元数据，包含name和description两个必填字段。description就是前面说的触发条件，写得好不好直接决定技能能不能被正确调用。正文部分用 Markdown 写，可以包含步骤、注意事项、示例。

我个人的经验是，正文不要写成流水账，要写成"决策树"。也就是告诉模型：如果遇到 A 情况走这条路，遇到 B 情况走那条路。模型在执行时是边读边判断的，决策树结构比线性步骤更符合它的工作方式。

4.2 描述字段的写法：决定技能生死的一行字

前面强调过 description 的重要性，这里给几个具体的写法对比：

第三种写法的特点是：用用户的语言描述用户的问题。用户不会说"我要调用文件解析模块"，用户会说"帮我把这些文件按日期整理一下"。你的描述要能接住后者。

还有一个技巧：在 description 里列出反例。比如"不适用于图片处理，图片相关请用 image-skill"。这能减少误调用。模型看到明确的排除条件，判断会更准。

4.3 脚本与资源的组织原则

技能里的脚本不是越多越好。我的原则是：能靠模型推理完成的，不写脚本；需要精确计算或外部调用的，才写脚本。

原因很简单，脚本是黑盒，模型看不到内部逻辑，一旦出错很难调试。而模型推理是白盒，你能通过调整提示词来修正行为。所以像"格式化输出""简单文本处理"这类，直接让模型做；像"调用外部 API""复杂数值计算""文件系统操作"这类，才封装成脚本。

脚本的另一个注意点是错误处理。模型调用脚本时，如果脚本静默失败，模型会以为成功了继续往下走，最后输出一堆错误结果。所以脚本必须在失败时返回明确的错误信息，最好带上错误码和原因，让模型能据此调整策略。

5. 实战踩坑：那些文档里不会写的教训

5.1 技能冲突：两个技能抢同一个任务

当你装了多个技能后，迟早会遇到技能冲突——两个技能的触发条件重叠，模型不知道该用哪个。我遇到过一次：一个"代码审查"技能和一个"代码优化"技能，描述里都包含"改进代码质量"，结果模型在两个之间反复横跳。

解决办法有两个。一是在描述里划清边界，明确写"本技能只做审查不做修改，修改请用 xxx 技能"。二是建立技能间的引用关系，在技能正文里写"如果发现需要修改，转交 xxx 技能处理"。后者更优雅，但要求你对整个技能生态有全局设计。

5.2 上下文污染：技能读多了反而变笨

这是个反直觉的现象。理论上技能越多能力越强，但实测下来，当常驻的元数据超过一定数量后，模型的判断准确率会下降。我猜测是因为元数据之间也在互相干扰，模型要在几十个描述里做匹配，注意力被分散了。

应对策略是分层管理：把高频技能放在常驻层，低频技能放到"技能市场"里按需安装。热搜里find skills、skills推荐、claude 国内安装skills 官方市场这些词说明社区已经在往这个方向走了——不是把所有技能都装上，而是按需发现和安装。

5.3 版本漂移：技能更新后行为突变

技能不是写完就一劳永逸的。模型在更新、工具在更新、你的技能如果引用了外部 API，API 也在变。我踩过一次坑：一个技能依赖的脚本调用的接口改了返回格式，脚本没跟着改，结果技能静默返回错误数据，我过了两周才发现。

从那以后我养成了一个习惯：给每个技能加一个自检脚本，定期跑一遍，验证依赖的接口、文件路径、权限是否还正常。这个自检脚本本身也可以做成一个技能，叫"技能健康检查"，挺讽刺但很实用。

5.4 调试技能的正确姿势

调试 Skills 和调试普通代码不一样，因为中间隔了一层模型。我的调试流程是这样的：

1. 先验证技能是否被调用。在技能正文开头加一句明显的日志输出，看模型有没有读进来。
2. 再验证调用时机是否正确。构造几个应该触发和不应该触发的测试用例，看模型的判断。
3. 最后验证执行结果。这一步才是传统意义上的调试，看脚本输出、看最终答案。

很多人一上来就调第三步，结果发现是第一步的问题——技能压根没被调用。顺序错了，白费功夫。

6. 生态与工具链：Skills 周边的那些事

6.1 技能市场与发现机制

热搜里find skills、skills推荐、官方市场指向一个正在成型的生态：技能的分发和发现。目前的做法主要有两种，一是官方维护的技能仓库，二是社区自发的技能集合。前者质量有保障但数量有限，后者数量多但良莠不齐。

我的使用策略是：核心工作流用官方或高星社区技能，边缘需求自己写。因为核心工作流对稳定性要求高，经不起技能作者跑路或更新破坏兼容；边缘需求自己写反而更贴合自己的习惯。

6.2 跨工具的技能复用

热搜里同时出现 Claude Code 和 Codex 的 skills，说明大家希望技能能跨工具复用。现实是，不同工具的 Skills 格式有差异，直接复用往往要改。但核心思路是相通的：元数据加正文加资源的结构、渐进式披露的机制、触发条件的写法，这些是通用的。

所以我的建议是：把技能的核心逻辑和工具特定的适配层分开。核心逻辑写成工具无关的 Markdown 和脚本，适配层针对不同工具做格式转换。这样迁移成本最低。

6.3 安全边界：技能能碰什么不能碰什么

技能本质上是让模型执行操作，所以安全边界必须想清楚。我的原则是：

• 文件操作限定在项目目录内，不要让技能有权限碰系统目录。
• 外部调用要有白名单，技能只能访问预先声明的服务。
• 破坏性操作要二次确认，删除、覆盖这类动作，技能应该先输出计划让用户确认。

热搜里agentpoison: red-teaming llm agents via poisoning memory or knowledge ba这个词虽然看着学术，但它点出的风险是真实的：如果技能的知识库被污染，模型会基于错误信息做出错误决策。所以技能的资源文件要有来源校验，不能随便从网上拉。

7. 我个人的几条实操心得

折腾 Skills 这段时间，有几个体会是文档里不会写的，分享出来。

第一，技能不是越多越好，是越准越好。我一开始贪多，装了三十多个技能，结果模型判断准确率反而下降。后来精简到八个高频技能，体验立刻好转。技能的价值在于被正确调用，不在于数量。

第二，写技能描述的时间应该比写正文多。正文写得再漂亮，描述不行，技能就是死的。我现在写一个技能，描述部分要反复改五六遍，正文反而一次成型。

第三，给技能写"使用日志"。我在每个技能里加了一个可选的日志输出，记录它被调用的时间、任务类型、执行结果。积累一段时间后，你能清楚看到哪些技能真正有用、哪些是摆设，据此做取舍。

第四，别指望技能解决所有问题。有些任务就是不适合做成技能，比如一次性的、高度依赖具体上下文的、需要大量人工判断的。硬做成技能，只会增加维护负担。判断标准是：这个任务会不会重复出现？重复出现时流程是否稳定？两个都是"是"，才值得做成技能。

最后说个具体的：如果你刚开始接触，别急着开发自己的技能，先把官方或社区的几个高质量技能装上，用一段时间，感受一下好的技能描述长什么样、好的执行流程怎么设计。有了这个体感，再动手写自己的，成功率会高很多。我当初就是跳过这一步直接写，结果前三个技能全部推倒重来。