1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到skills、Claude Code、Codex、agents、plugin、前端开发skills、superpower skills、agent skills测试、codex skills、claude agent skills……这些词几乎都围绕同一个核心概念在转。很多人第一次看到“skills”会以为是某种新框架或者新工具其实它更像是一种能力封装与复用机制——把一组指令、工具调用逻辑、上下文约束打包成一个可被智能体agent直接加载的模块让模型在特定任务上表现得像“受过专项训练”一样。我最早接触这个概念是在折腾 Claude Code 和 Codex 的时候。当时想让模型帮我做前端代码审查每次都要重复写一大段提示词什么“你是一个资深前端工程师”“请检查以下代码的可访问性、性能、状态管理”……写多了就烦。后来发现有人把这类提示词做成了 skills直接挂载到 agent 上调用时只需要说“用前端审查 skill 跑一遍”模型就自动按预设逻辑执行。这就是 skills 最朴素的价值把重复的提示工程变成可插拔的能力模块。它适合谁如果你是那种经常用 Claude Code、Codex、Cursor 或者自己搭 LangChain deep agents 的人skills 能帮你省掉大量重复劳动。如果你只是偶尔用聊天窗口问问题那可能感知不强。但只要你开始做多步骤任务、需要模型稳定输出特定格式、或者想让不同 agent 共享同一套行为规范skills 就是绕不开的东西。下面我会从设计思路、核心细节、实操过程、常见问题四个维度把我在实际项目里踩过的坑和总结的方法完整拆开讲。2. 内容整体设计与思路拆解2.1 为什么是“技能包”而不是“提示词模板”很多人会问skills 和普通的 prompt template 有什么区别我一开始也这么想直到我在一个多 agent 协作的项目里被坑了一次。当时我们有三个 agent一个负责写代码一个负责审查一个负责写测试。每个 agent 都有自己的提示词模板但问题是——当审查 agent 发现代码问题时它不知道怎么调用写代码 agent 的修复逻辑因为提示词模板之间是孤立的。后来我们把每个 agent 的能力拆成独立的 skill每个 skill 包含触发条件、输入输出格式、可调用的工具列表、失败回退策略。这样审查 agent 可以直接加载“代码修复 skill”把问题描述传进去修复 agent 就能按统一格式处理。所以 skills 的设计核心是可组合性。它不只是提示词还包括工具绑定、上下文管理、错误处理。你可以把它理解成给 agent 用的“函数库”每个 skill 是一个函数有明确的入参和出参内部实现可以很复杂但对外接口稳定。这样做的好处是当你要换模型、换工具链、甚至换整个 agent 框架时只要 skill 的接口不变上层逻辑就不用大改。另一个考量是权限与安全边界。直接给 agent 一个万能提示词它可能会调用不该调用的工具或者访问不该访问的数据。把能力拆成 skill 后你可以在 skill 级别做权限控制比如“数据库查询 skill”只允许读“部署 skill”需要二次确认。这在企业环境里特别重要我见过太多因为 agent 误操作导致的事故。2.2 选型背后的逻辑Claude Code、Codex 还是自建现在市面上支持 skills 的平台不少Claude Code、Codex、Cursor、还有各种自建的 LangChain deep agents。怎么选我的经验是看你的主要工作场景。如果你主要写代码而且已经在用 Claude Code 或 Codex那直接用它们内置的 skill 机制最省事。Claude Code 的 skill 系统比较成熟支持从官方市场安装也支持本地自定义。Codex 的 skill 更偏向代码生成和补全适合快速迭代。但这两个平台在国内安装和配置都有一些门槛后面实操部分我会详细讲。如果你需要跨平台、跨模型或者要把 skill 嵌入到自己的产品里那自建是唯一选择。LangChain deep agents 提供了一套比较完整的 skill 抽象你可以用 Python 定义 skill绑定任意工具然后挂到任意支持的模型上。缺点是前期投入大需要自己处理上下文窗口、工具调用协议、错误重试这些细节。我个人的建议是先用平台内置的 skill 跑通流程再根据需求决定是否自建。不要一上来就造轮子除非你确定平台的能力边界满足不了你。2.3 一个容易被忽略的设计点skill 的粒度skill 的粒度怎么定太粗了一个 skill 干太多事复用性差太细了skill 数量爆炸管理成本高。我试过几种粒度最后总结出一个原则一个 skill 只做一件可独立验证的事。比如“前端代码审查”这个 skill它内部可以包含可访问性检查、性能检查、状态管理检查但对外只暴露一个入口输入代码输出问题列表。这样你可以在不同项目里复用这个 skill而不需要关心它内部怎么实现。如果你把可访问性检查单独拆成一个 skill那每次审查都要手动组合多个 skill反而麻烦。但有些场景必须拆细。比如“数据库操作”这个领域读和写必须分开因为权限不同。这时候粒度就要细到操作级别。所以粒度不是固定的取决于你的权限模型和复用场景。3. 核心细节解析与实操要点3.1 skill 的文件结构与元数据不管哪个平台skill 通常都是一个目录或一个文件里面包含元数据和实现逻辑。以 Claude Code 为例一个典型的 skill 目录长这样my-skill/ ├── skill.json # 元数据名称、描述、触发词、权限 ├── prompt.md # 核心提示词模板 ├── tools.json # 可调用的工具列表及参数 schema └── handlers/ # 自定义处理逻辑可选 └── post_process.pyskill.json是最关键的它决定了 skill 什么时候被激活、能做什么、不能做什么。我见过很多人只写 prompt.md不写元数据结果 skill 要么不触发要么乱触发。元数据里我一般会重点配置这几个字段trigger触发词或触发条件。可以是关键词也可以是正则表达式。比如“审查代码”“review”都触发同一个 skill。priority优先级。当多个 skill 同时匹配时优先级高的先执行。permissions权限列表。比如read:file、write:file、execute:shell。没有权限的工具调用会被直接拒绝。input_schema输入格式定义。用 JSON Schema 描述方便模型理解该传什么参数。output_schema输出格式定义。这个特别重要因为后续 skill 可能依赖前一个 skill 的输出。注意input_schema 和 output_schema 一定要写清楚不要偷懒。我踩过的坑是输出格式不固定导致下游 skill 解析失败整个链路断掉。后来我强制要求所有 skill 的输出必须是合法 JSON并且用 schema 校验。3.2 提示词模板的编写技巧prompt.md 是 skill 的灵魂。写得好模型表现稳定写得差模型自由发挥。我总结了几条实战经验第一角色定义要具体到场景。不要写“你是一个 helpful assistant”要写“你是一个有五年经验的前端工程师专门审查 React 项目的代码质量重点关注可访问性、性能瓶颈和状态管理反模式”。越具体模型越不容易跑偏。第二输出格式用示例约束。与其描述“请输出 JSON”不如直接给一个示例{ issues: [ { type: accessibility, severity: high, line: 42, message: 缺少 alt 属性, suggestion: 为 img 标签添加描述性 alt } ] }模型看到示例后输出格式的准确率会大幅提升。第三边界条件要明确。比如“如果代码中没有发现问题返回空数组不要编造问题”。我遇到过模型为了“表现积极”硬生生编出几个不存在的问题导致后续修复流程白跑。第四工具调用要给出决策树。如果 skill 绑定了多个工具要告诉模型什么情况下用哪个工具。比如“如果需要查询数据库调用 query_db如果需要写文件调用 write_file如果两者都不需要直接返回结果”。3.3 工具绑定的参数计算与选择工具绑定是 skills 里最容易出问题的环节。我拿一个实际案例来说明我们有一个“日志分析 skill”需要调用 shell 工具执行 grep 命令。参数怎么定首先命令模板要参数化。不要硬编码路径用占位符grep -r {{keyword}} {{log_dir}} --include*.log | tail -n {{max_lines}}然后在 tools.json 里定义每个参数的 schema{ name: grep_logs, parameters: { keyword: {type: string, required: true}, log_dir: {type: string, default: /var/log/app}, max_lines: {type: integer, default: 100, max: 1000} } }这里max_lines我设了上限 1000因为曾经有一次模型传了 100000直接把上下文撑爆了。所有数值参数都要设上下限这是血泪教训。另外工具调用的超时时间要单独配置。默认超时往往太长一个卡住的命令会让整个 agent 挂起。我一般设 30 秒超过就中断并返回错误让模型决定是否重试。3.4 上下文管理与 token 预算skills 执行过程中会产生大量中间结果如果不加控制上下文窗口很快就会被占满。我的做法是每个 skill 的输出只保留摘要和关键字段原始数据写到临时文件需要时再读。设置 token 预算比如每个 skill 最多消耗 2000 token超过就截断并标记。用引用代替复制比如输出文件路径而不是文件内容。这些策略在单 skill 场景下可能看不出效果但在多 skill 链式调用时能决定整个流程能不能跑完。4. 实操过程与核心环节实现4.1 环境准备Claude Code 与 Codex 的安装配置国内安装 Claude Code 和 Codex 确实有一些坑我分别说一下我的实操记录。Claude Code 的安装官方推荐用 npmnpm install -g anthropic-ai/claude-code但国内网络环境下npm 源可能很慢。我一般先切到国内镜像源npm config set registry https://registry.npmmirror.com然后再安装。安装完成后需要配置 API 密钥。Claude Code 支持从环境变量读取export ANTHROPIC_API_KEYyour-key-here如果你用的是 VS Code可以安装 Claude Code for VS Code 插件然后在设置里填入密钥。注意有些组织账号会禁用 Claude Code 的订阅访问报错信息类似“your organization has disabled claude subscription access for claude code”。遇到这种情况要么换个人账号要么联系管理员开通权限。Codex 的安装类似官方提供安装包和 npm 两种方式。我建议用 npm方便后续更新npm install -g openai/codexCodex 登录时如果遇到网络问题可以尝试配置代理环境变量但注意这里说的代理是指正常的 HTTP 代理用于解决网络连通性不涉及任何特殊工具。配置方法export HTTPS_PROXYhttp://your-proxy:port export HTTP_PROXYhttp://your-proxy:port登录成功后可以用codex login验证状态。4.2 创建第一个自定义 skill前端代码审查我拿一个真实项目里的 skill 来演示。目标输入一个 React 组件文件路径输出审查报告。第一步创建目录结构mkdir -p ~/.claude/skills/frontend-review cd ~/.claude/skills/frontend-review第二步写 skill.json{ name: frontend-review, description: 审查 React 组件代码质量, trigger: [审查前端, review frontend, 检查组件], priority: 10, permissions: [read:file], input_schema: { type: object, properties: { file_path: {type: string} }, required: [file_path] }, output_schema: { type: object, properties: { issues: {type: array}, summary: {type: string} } } }第三步写 prompt.md你是一个有五年经验的 React 前端工程师。请审查以下代码重点关注 1. 可访问性是否有 alt 属性、aria 标签、键盘导航支持 2. 性能是否有不必要的重渲染、大列表是否虚拟化、是否滥用 useEffect 3. 状态管理状态是否提升合理、是否有冗余状态、是否使用不可变更新 输出格式必须是合法 JSON包含 issues 数组和 summary 字符串。 如果没有问题issues 返回空数组。 不要编造问题。第四步测试 skill。在 Claude Code 里输入/frontend-review src/components/UserList.tsx如果配置正确模型会读取文件并返回审查结果。我第一次测试时模型返回了非 JSON 格式原因是 prompt 里没有强调“只输出 JSON不要有其他文字”。后来我在 prompt 末尾加了一句“直接输出 JSON不要包含 markdown 代码块标记”问题解决。4.3 多 skill 链式调用从审查到修复单个 skill 跑通后我尝试把审查和修复串起来。修复 skill 的输入是审查 skill 的输出所以 output_schema 必须严格匹配。修复 skill 的 prompt 核心逻辑你是一个 React 代码修复专家。输入是一个 JSON 格式的审查报告包含 issues 数组。 请针对每个 issue生成修复后的代码片段。 输出格式 { fixes: [ { issue_type: accessibility, original_line: 42, fixed_code: ..., explanation: ... } ] }然后在 Claude Code 里用管道串联/frontend-review src/components/UserList.tsx | /frontend-fix实测下来链式调用最大的问题是上下文传递。审查报告可能很长直接传给修复 skill 会占用大量 token。我的优化方案是审查 skill 只输出关键字段issue_type、line、message修复 skill 根据 line 重新读取原文件对应位置。这样上下文占用减少了 70%。4.4 在 LangChain deep agents 中集成 skill如果你用 LangChainskill 的集成方式更灵活。我用 Python 写了一个简单的 skill 加载器from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain.tools import tool import json tool def frontend_review(file_path: str) - str: 审查 React 组件代码质量 with open(file_path, r) as f: code f.read() # 这里调用模型进行审查 prompt load_skill_prompt(frontend-review) result llm.invoke(prompt.format(codecode)) return json.dumps(result) tools [frontend_review] agent create_openai_tools_agent(llm, tools, prompt) executor AgentExecutor(agentagent, toolstools) executor.invoke({input: 审查 src/components/UserList.tsx})这种方式的好处是你可以把 skill 注册成标准的 LangChain tool然后挂到任意 agent 上。缺点是失去了平台内置的权限控制和触发词匹配需要自己实现。4.5 性能优化skill 缓存与并发当 skill 数量多了之后每次调用都重新加载 prompt 和工具定义会很慢。我加了一层缓存from functools import lru_cache lru_cache(maxsize128) def load_skill(skill_name: str): with open(fskills/{skill_name}/skill.json) as f: metadata json.load(f) with open(fskills/{skill_name}/prompt.md) as f: prompt f.read() return metadata, prompt另外如果多个 skill 之间没有依赖关系可以并发执行。我用asyncio.gather把独立的审查任务并行跑整体耗时从 12 秒降到 4 秒。但要注意并发调用模型 API 可能会触发速率限制需要加信号量控制并发数。5. 常见问题与排查技巧实录5.1 skill 不触发或触发错误这是最常见的问题。表现是你输入了触发词但 skill 没反应或者你不想触发某个 skill它却跑出来了。排查思路检查 trigger 配置。触发词是否拼写正确是否区分大小写有些平台对中文触发词支持不好建议同时配置英文触发词。检查 priority。如果多个 skill 的触发词重叠优先级低的会被忽略。把最具体的 skill 优先级调高。检查权限。如果 skill 需要 read:file 权限但没配置它可能静默失败。查看日志确认。我遇到过一次trigger 里写了“审查代码”但用户输入的是“审查一下代码”中间多了“一下”导致不匹配。后来我把 trigger 改成正则审查.*代码问题解决。5.2 输出格式不符合预期模型返回了非 JSON、缺少字段、或者字段类型错误。排查步骤在 prompt 里增加格式示例越具体越好。在 skill.json 里启用严格模式如果平台支持强制 schema 校验。加一个后处理步骤用代码解析并修复格式。比如import json import re def extract_json(text): match re.search(r\{.*\}, text, re.DOTALL) if match: return json.loads(match.group()) raise ValueError(No JSON found)这个函数能处理模型在 JSON 前后加解释文字的情况。5.3 工具调用失败工具调用失败的原因很多我整理了一个速查表问题现象可能原因解决方法权限拒绝skill 未配置对应权限在 skill.json 的 permissions 里添加参数缺失模型没传必填参数在 prompt 里强调必填参数或设默认值超时命令执行时间过长设置超时时间优化命令路径错误相对路径解析问题统一用绝对路径编码问题文件编码不是 UTF-8在命令里指定编码如iconv提示工具调用失败时一定要让 skill 返回明确的错误信息而不是静默失败。这样模型才能根据错误信息决定是否重试或换方案。5.4 上下文溢出多 skill 链式调用时上下文很容易爆。我的应对策略每个 skill 输出前先做摘要只保留关键信息。用文件系统做中间存储skill 之间通过文件路径传递数据。设置全局 token 预算超过就中断并提示用户。有一次我跑一个五步链到第三步就溢出了。后来把第二步的输出从完整代码改成 diff 摘要问题解决。5.5 模型“幻觉”编造结果模型为了完成任务会编造不存在的问题或修复方案。这在审查类 skill 里特别常见。我的解法在 prompt 里明确“如果没发现问题返回空数组”。要求模型引用具体行号和代码片段编造的内容往往对不上。加一个验证步骤用代码检查模型输出的行号是否在文件范围内。5.6 跨平台兼容性问题如果你在 Claude Code 里写的 skill 想拿到 Codex 里用可能会遇到格式不兼容。我的经验是尽量用平台无关的格式。比如 prompt 用纯 Markdown工具定义用 JSON Schema输出用标准 JSON。这样迁移成本最低。如果平台有特殊要求写一个适配层做转换。6. 一些实战心得与扩展思路6.1 从“能用”到“好用”的关键细节我一开始写的 skill 只能算“能用”经常出小问题。后来做了几件事稳定性大幅提升第一给每个 skill 写测试用例。就像单元测试一样准备几个输入检查输出是否符合预期。我写了一个简单的测试脚本每次修改 skill 后跑一遍避免回归。第二版本化管理。skill 也会迭代我用 git 管理 skill 目录每次修改都提交方便回滚。第三日志记录。每个 skill 的调用时间、输入、输出、错误都记到日志里。出问题时日志是最快的排查入口。6.2 skill 的复用与分享skill 最大的价值在于复用。我把自己常用的 skill 整理成一个本地仓库按领域分类前端、后端、数据分析、文档写作。新项目直接挂载需要的 skill不用重新写。如果你在团队里可以搭一个内部 skill 市场。我们团队用简单的文件服务器做共享每个人都可以上传和下载 skill。关键是统一元数据格式否则别人下载后跑不起来。6.3 未来可以扩展的方向skill 目前主要用在代码和文本任务上但它的思路可以扩展到更多场景。比如自动化运维把常见的运维操作封装成 skillagent 根据告警自动执行。数据分析流水线每个数据处理步骤是一个 skill串起来就是完整流水线。客户支持把常见问题的回答逻辑做成 skillagent 根据用户问题自动匹配。我最近在尝试把 skill 和定时任务结合让 agent 每天自动跑一遍代码质量检查生成报告发到群里。实测下来只要 skill 写得稳这种自动化非常省心。6.4 一个容易踩的坑skill 之间的命名冲突当 skill 数量超过 20 个时命名冲突的概率大幅上升。我有一次定义了两个 skill一个叫review一个叫code-review触发词都是“审查”结果每次调用都随机命中一个。后来我定了命名规范领域-动作-对象比如frontend-review-component、backend-test-api。这样既避免冲突也方便查找。6.5 关于 skill 的调试技巧调试 skill 最痛苦的是不知道模型内部怎么想的。我的做法是在 prompt 里加一个“思考过程”字段让模型输出决策依据。比如{ reasoning: 用户要求审查代码我检测到文件路径参数调用 read_file 工具读取内容..., issues: [...] }这样出问题时我能看到模型是在哪一步跑偏的。虽然会多消耗一些 token但调试效率提升明显。6.6 最后分享一个提高 skill 触发准确率的小技巧如果你发现 skill 经常不触发可以在系统提示词里加一句“当用户输入包含以下关键词时优先加载对应 skill审查、review、检查、分析”。这相当于给模型一个显式的路由提示。我实测下来触发准确率从 70% 提升到 95% 以上。当然前提是你的触发词设计得合理不要互相冲突。这个方向后续还可以继续挖比如把 skill 和 RAG 结合让 skill 能动态检索知识库或者做 skill 的自动生成根据用户的操作历史自动提取常用模式。我现在还在折腾这些等跑通了再整理出来分享。