2026/9/11 21:34:00
FEATURED · 精选文章 
最近想避开 Skill 这个词已经很难了。Claude Code 的 Agent Skills、Codex 的 Skill 目录再加上冒出来的各种 Skill 插件和录制工具几乎一夜之间把“给 AI 写长篇提示词”这件事升级成了“给 AI 打包一套完整工作方法”。但我观察到的问题是大多数人拿到 Skill 编辑器之后是懵的。有人把它当成超大号 Prompt有人抄了一份 SKILL.md 却发现 Agent 根本不触发更少有人认真想过——不同岗位、不同工作流要用到的 Skill定制思路其实完全不一样。这篇文章我会用一套自己项目里沉淀下来的“技术 / 产品 / 管理 / AI 四大类 Skill 定制模板”完整讲清楚每类 Skill 的设计侧重点、SKILL.md 的底层结构以及怎么放到 Claude Code、Codex 这类 Agent 环境里跑起来。适合正在用 AI 编程工具、想让 Agent 更懂团队流程的人也适合刚接触 Skill 但不知道从哪下手的开发者。如果你已经会写基础 Prompt全文可以直接当成一套可复用的工程框架来抄。1. Skill 定制的本质不是“写提示词”是“打包工作方法”1.1 把 Skill 当成“给新员工的 SOP 手册”先说一个最普遍的误解Skill 不是一次性的提示词它更像一个独立的小型能力包。提示词是“我临时找同事帮个忙把需求说清楚就行”Skill 是“入职第一天递到你手上的岗位 SOP”里面规定了什么情况下触发这个流程、按什么步骤执行、最终要交付什么格式的结果、哪些事情绝对不要做。放在 Agent 的视角里Skill 的承载形式通常是一个目录核心文件叫 SKILL.md。Claude Code 会扫描.claude/skills/下的技能目录Codex 也有类似机制。目录里除了解释“这个技能是什么、怎么用”的 SKILL.md还能放脚本、模板、参考资料。普通 Prompt 是“一次性对话的输入”Skill 是“对话过程中 Agent 能感知到、并按需自动加载的一个独立模块”。我习惯用“给新员工的 SOP 手册”来跟团队解释这个概念因为两者的本质一致把脑子里的经验、检查清单、输出标准外化成一份别人或别的模型照着就能执行的文件。所以定制 Skill 的第一性问题不是“怎么写指令”而是“我要把哪种反复出现的工作方法沉淀下来”。1.2 为什么先沉淀技术、产品、管理、AI 这四类不是所有工作都适合做成 Skill。如果一件事每天只出现一次、每次情况都完全不一样那用普通 Prompt 反而更灵活。但研发团队里绝大多数高价值工作恰恰是“高频重复 流程相对固定”的比如代码审查、需求分析、项目复盘、AI 方案评审。这类工作每做一次都从零开始想是巨大的隐性浪费。我自己的路径是先从技术类 Skill 做起的比如代码审查和架构评审。后来发现产品类和管理类 Skill 带来的团队效率提升甚至更明显因为这两类工作过去几乎没有工具能帮着“结构化”。再往后做 AI 应用项目时才发现 AI 类 Skill 是最难做、但也最值得做的——它服务的对象变成了“正在做 AI 系统的人”输入是模糊的架构问题输出必须是可决策的评审结论。四类 Skill 的定位差别可以用下面这张表直观表达类别核心目标服务人群典型场景沉淀对象技术类把工程红线变成自动检查开发、测试、运维代码审查、架构评审、安全审计、Bug 排查工程规范与检查清单产品类把需求思维变成产出模板产品经理、业务分析PRD、竞品分析、埋点设计、版本规划思考框架与输出模板管理类把项目推进变成结构化动作项目经理、技术负责人复盘、OKR、周报、会议纪要、风险预警追问机制与行动项提取AI 类把模型与 Agent 设计经验变成评审清单AI 应用开发团队Prompt 优化、模型选型、RAG 设计、Agent 架构评审评估维度与方案对比逻辑有了这张定位表再去设计每个 Skill 的内部结构思路会清晰很多。2. 四大类 Skill 的角色分工技术重规范、产品重思维、管理重推进、AI 重系统2.1 技术类 Skill把工程经验固化成可执行的规范技术类 Skill 的适用范围很广代码审查、架构设计评审、单元测试生成、Bug 排查、安全审计、技术方案评审甚至专利交底书初稿辅助。它们共同的特点是检查逻辑基本是确定的。比如让 Agent 审查一段代码我希望它按什么顺序看先看命名和可读性再看边界条件和异常处理接着看性能与安全隐患最后给出测试建议。这个顺序一旦定下来就可以固化成 Skill。设计技术类 Skill 时最忌讳的一句描述是“你会是一个资深技术专家请帮我分析这段代码”。这种描述没有给 Agent 任何可执行的抓手它只能凭通用知识自由发挥。真正有用的技术 Skill要像一份带“硬约束”的检查单必须检查哪些项目、每个检查项的判定标准是什么、输出必须分成几个等级严重 / 建议 / 可忽略、每个等级必须给出对应代码行号与修改建议。我在技术 Skill 里通常会内置一段“先检查后输出”的指令强制 Agent 在给出结论前先逐项对照清单。这跟人工 review 时的习惯一致先按流程走完再下结论而不是上来就凭感觉说“看起来不错”。2.2 产品类 Skill让 AI 按产品经理的思维方式工作产品类工作的特点是“输出物有固定模板但思考过程高度非线性”。比如写 PRD不同公司有不同模板但背后的思考链条是类似的目标用户是谁、业务背景是什么、这次要解决什么问题、怎么度量成功、有哪些边界情况、需要什么资源。产品类 Skill 的核心价值就是把这根思考链条封装进去让 AI 不是“直接生成一份报告”而是按产品经理的方式先提出问题、再组织信息、最后输出结构化文档。我做得比较成功的一个 PRD Skill开头就定义了一条硬性规则如果用户没有提供目标用户、业务背景和成功指标这三类信息必须先把这三个问题抛回去而不是自己编造答案继续写。这一步非常关键。普通 Prompt 常见的翻车方式是AI 为了显得专业会在信息不足时脑补一堆“可能存在的用户场景”结果做出一份看起来很完整、实际到处是假设的 PRD。产品类 Skill 要做的是逼着 AI 把“事实”和“假设”分开陈列所有未经确认的信息必须在文档里明确标注为“待确认假设”。这个机制一旦跑起来产品团队拿到的初稿质量会明显提升。2.3 管理类 Skill把复盘、OKR、会议变成固定动作管理类工作可能是最容易被 AI 工具忽略、但收益最大的领域。项目复盘、OKR 制定、周报、会议纪要、风险预警这些动作在团队里反复出现却很少有人为它们建立标准化流程。管理类 Skill 的设计目标是让 AI 从“写总结的工具”变成“推进项目的助手”。做项目复盘 Skill 时我一开始也踩过坑让 AI 直接生成复盘报告结果它把流水账重写了一遍没有任何洞察。后来我重新设计了指令把复盘拆成四个强制步骤还原事实、对比目标、根因分析、提取行动项。每一步都必须单独输出且没有走完前一步、AI 不得进入下一步。管理类 Skill 最该强化的是“追问机制”。人做复盘时之所以能挖出根因是因为会不断追问“为什么”。AI 天生更倾向于讨好式地回答而不是挑战用户。所以我在管理类 Skill 里明确写了一句特殊指令当用户提供的信息不足以支撑分析时必须连续追问每次只问一个最关键的缺口直到信息足够再开始输出结论。这句话配合结构化的分析步骤效果立竿见影。2.4 AI 类 Skill面向 Agent 开发者的元技能AI 类 Skill 是四类里最特殊的它用来服务“正在做 AI 应用的人”。典型场景包括 Prompt 优化、模型选型、RAG 方案设计、Agent 工作流编排、AI 应用架构评审。这类问题的特点是没有标准答案方案好坏取决于约束条件——成本、延迟、准确性、可维护性。所以 AI 类 Skill 的设计重心不是“告诉 Agent 正确答案”而是“逼着它做方案对比和权衡”。比如我写过一个 AI 应用架构评审 Skill它要求 Agent 对任何候选方案必须给出至少两个备选项并从上下文管理、工具调用可靠性、错误恢复、成本与延迟、可观测性五个维度逐一打分最后才给结论。如果讨论的是 Spring AI 这类框架的集成方案它还会额外要求列出框架本身的能力边界和社区维护情况。为什么一定要对比因为做 AI 应用的人十有八九会被“热门方案”带偏。直接问“帮我设计一个知识库问答系统”AI 默认就会往 RAG 上靠但如果 Skill 强制它先比较 RAG、Fine-tuning、长上下文三种路线再结合数据量、更新频率、成本预算来选产出的方案才真正可用。这个“先对比后结论”的纪律是 AI 类 Skill 区别于普通咨询式回答的核心。3. 定制模板的核心骨架SKILL.md 的元信息、指令与资源如何各司其职3.1 元信息name 和 description 决定了 Agent 什么时候“想起”这个 Skill很多人的 Skill 不生效问题往往出在最不起眼的元信息上。Agent 不会像人一样主动翻你的技能目录它是通过“当前对话内容”与 SKILL.md 里 description 的语义匹配度来判断要不要加载这个 Skill 的。所以 description 不是为了给人看而是为了给模型看。一段合格的 description需要包含四个要素什么时候用、输入是什么、输出是什么、相关的关键词。我见过最典型的失败案例是有人把 description 写成“代码审查相关”结果 Agent 在对话里看到“帮我 review 一下这段代码”时完全不觉得这跟“代码审查相关”有足够强的关联于是 Skill 永远不被触发。对比一下两种写法# 差的描述 description: 技术审查 # 可以用的描述 description: 当用户希望进行代码审查、合并请求评审、安全审计、技术债务评估或代码质量改进时使用。 输入为代码片段或文件路径输出为按严重程度分级的审查报告包含具体行号、问题说明与改进建议。后者把触发场景拓宽到了“合并请求评审”“安全审计”“技术债务评估”Agent 在不同语境下都能对上号。定制模板的第一步就是把 description 当成搜索引擎的索引词来写宁可多列几个同义场景也不要写得太抽象。3.2 指令正文分步骤、给范例、定边界Instruction 部分是 SKILL.md 的主体设计原则可以浓缩成三句话分步骤、给范例、定边界。分步骤很好理解把工作流拆成 5 到 10 个强制执行的步骤每一步说明输入、处理动作和中间产物。给范例则是很多模板里最容易漏的环节。大模型在没有示例时会按它对“正常输出”的统计偏好走给了一个 mini 示例后输出风格和结构都会被显著拉向示例的样子。定边界则是告诉 AI 不要做什么比如 PRD Skill 里写“不得编造用户访谈数据”、代码审查 Skill 里写“不要在没有复现的情况下断言存在死锁”这些负向约束能有效抑制幻觉。还要注意长度。Skill 一旦被触发SKILL.md 的内容都会进入上下文太长会挤占对话窗口、增加 token 成本。我的经验是单个 Skill 的指令正文控制在 200 到 500 行 Markdown 比较合适再多的细节放到 references 目录里按需加载。控制篇幅本身就是一种设计约束逼着你只保留最核心的检查项和步骤。3.3 资源目录从“纯文字指导”到“可执行工具”一个成熟的 Skill 不只是 SKILL.md它还可以带一套资源文件。我的标准目录结构长这样.claude/skills/code-review/ ├── SKILL.md # 触发元信息 执行步骤 输出格式 ├── scripts/ │ └── check_pr.py # 可选的静态检查 / 分析脚本 ├── templates/ │ └── review_template.md # 输出报告的 Markdown 模板 └── references/ ├── checklist.md # 详细的审查检查清单 └── security_rules.md # 安全与合规检查项这里有一个很重要的工作划分文本指令负责“怎么想”脚本负责“怎么算”。比如要快速定位某段代码里所有未捕获的异常与其让 AI 用眼睛一行行找不如在 scripts 里放一个脚本去扫描把结果喂回给 Agent 做分析。Skill 一旦能调用脚本它就从“一套说辞”升级成了“一个工具”。我在实际项目里最常用脚本的场景是统计代码行数、扫描 TODO 标记、解析 Git 提交记录、检查 API 调用点。这些确定性操作交给脚本文本指令专注于逻辑判断和报告生成两者各干各擅长的事效果最好。4. 从骨架到血肉技术/产品/管理/AI 四套 Skill 模板逐项拆解4.1 技术类模板代码审查 Skill 的完整骨架下面是我在项目里实际在用的一个代码审查 Skill 精简版你可以直接拿这个骨架去改--- name: code-review description: 当用户希望进行代码审查、合并请求评审、安全审计或技术债务评估时使用。 输入为代码片段或文件路径输出为按严重程度分级的审查报告。 --- # 代码审查流程 1. 获取审查对象。如果是文件路径先读取文件内容如果是代码片段直接使用。 2. 先审查可读性命名是否清晰、函数是否过长、是否存在重复逻辑。 3. 再审查正确性边界条件、空值处理、并发安全、异常是否被合理捕获。 4. 接着审查性能循环内是否有不必要查询、大数据量下是否有 O(n^2) 风险。 5. 最后审查安全性外部输入校验、权限判断、注入风险、敏感信息泄露。 6. 输出审查报告必须包含以下字段 - 严重问题P0/P1/P2 分级附精确行号 - 改进建议按优先级排序 - 修改后的代码示例仅对严重问题提供 7. 边界约束不得讨论与本次审查无关的代码不得在没有充分证据时断言存在性bug。 ## 输出示例 ### P1第 32 行未校验用户输入长度 当前代码直接拼接用户输入到 SQL存在注入风险。 建议使用参数化查询示例如下 ...仔细看这个骨架你会发现它每一段指令背后都有对应目的。第 2 到 5 步的顺序不是随便排的先看可读性是让 Reviewer 先理解代码再深入逻辑把性能和安全放在后面是因为如果没有前面对代码结构的理解安全和性能判断容易脱离实际。第 6 条强制输出格式是为了让报告能直接粘贴到 PR 评论里不需要人工二次加工。如果你要扩展成安全审计专用 Skill把第 5 步展开成更细的检查清单再加一个 references/security_rules.md 引用即可。4.2 产品类模板PRD 生成 Skill 的关键设计PRD 生成类 Skill 的技术难度不高难点全在“防编造”。我的模板里固定包含这么几条规则1. 信息收集阶段如果输入缺少业务背景、目标用户或成功指标主动向用户提问一次只问一个问题。 2. 禁止编造用户访谈、市场数据、竞品数据。如果确需引用但未提供标注为“假设待验证”。 3. 输出结构固定为 - 背景与问题 - 目标与非目标 - 用户角色与场景 - 需求描述按优先级分组 - 埋点与指标设计 - 验收标准 - 风险与依赖 4. 收尾前必须执行自检逐条核对需求描述是否有验收标准每个用户场景是否有对应功能所有指标是否可量化。为什么“一次只问一个问题”很重要因为多问会让用户烦而且回答质量会下降。AI 要扮演的不是调查员而是懂节奏的产品搭档。这个 Skill 真正提升效率的点在于第 4 条自检逻辑它复刻了资深产品经理在发文档前心里默默过一遍的流程。用 AI 做 PRD 初稿最怕的不是写得差而是写得“太顺”让人看不出逻辑漏洞。自检步骤就是用来强行把漏洞暴露出来的。4.3 管理类模板项目复盘 Skill 的“提问-分析-行动”闭环项目复盘类 Skill 有一个别的工作没有的优势它天然适合结构化的追问式对话。我的管理类 Skill 模板把复盘执行过程分成了四条硬性步骤第一步还原事实要求用户列出项目目标、关键时间点、实际结果差距数据必须精确到数字。 第二步对比目标逐项列出“计划 vs 实际”找出偏差最大的三个点。 第三步根因分析对每个偏差点执行连续追问—— 为什么会出现这个偏差 这是直接原因还是深层原因 如果再往下追一层会发现什么 至少追问三轮才能给出根因结论。 第四步提取行动项输出一个 Markdown 表格 包含行动项、负责人、截止时间、验证方式。管理类 Skill 的评判标准很简单复盘会的产出是否能让团队两周后验证“改善动作是否生效”。很多复盘会开完就完了就是因为最后一步“行动项”没有做到可验证。所以我在模板里强制要求每个行动项必须带验证方式和时间。另一个值得说的是第二步“只找偏差最大的三个点”——复盘最怕贪多嚼不烂一次聚焦三个根因团队才能真正消化。4.4 AI 类模板AI 应用架构评审 Skill 的维度设计AI 应用架构评审 Skill 是我四类模板里“元味”最重的一个它服务的不是具体的业务任务而是“评估一个 AI 系统设计得好不好”。核心指令是把评审工作拆成一连串固定维度评审输入AI 应用的技术方案、候选模型、系统架构图或文字描述。 必须执行的对比流程 1. 任务分析确定这是分类、生成、检索还是多轮 Agent 任务 2. 方案生成对当前需求给出至少两条备选技术路线 例如 RAG vs 长上下文 vs Fine-tuning 3. 五维评估 - 上下文管理输入长度、多轮记忆策略、检索片段组织方式 - 工具调用可靠性是否处理了工具返回错误、超时、重试 - 错误恢复当模型输出不符合预期时系统如何兜底 - 成本与延迟预估 token 消耗、首字延迟、扩容路径 - 可观测性是否有日志、追踪、评估集、回归测试 4. 输出给出推荐方案与理由附一张方案对比表。这类 Skill 之所以值得单独封装是因为 AI 应用的问题往往要在“系统层面”找答案。单点 prompt 调得再好上下文管理一塌糊涂整个系统依然没法用。有了这套维度团队在方案评审时就能把注意力拉到架构层面而不是陷入“哪个模型更强”的无休止争论。实际用下来它对我做技术选型和架构评审的启发甚至比产出结论本身更大。5. 模板落地的完整链路目录放置、触发调试与高频翻车点5.1 目录放置与自动加载配置模板做出来后第一件事是放进对应 Agent 的扫描目录。以 Claude Code 为例项目级 Skill 放在项目根目录的.claude/skills/下# 项目级 Skill只对当前仓库生效 mkdir -p .claude/skills/code-review # 如果你用 Codex也可以放它的技能目录 mkdir -p .codex/skills/code-review目录名建议全部小写并用连字符分隔因为目录名会作为 Skill 的标识之一被模型引用。除了项目级还可以放在用户级目录下让所有项目共用。我的建议是团队公共规范比如代码审查、PRD 模板放项目级跟随仓库走个人偏好型 Skill比如写作风格、日常工具脚本放用户级避免污染团队仓库。5.2 如何判断 Skill 是否真的被触发Skill 这玩意最反直觉的地方在于你放进目录后没有任何反馈告诉你“我加载了”。它不像插件有图标也不像工具调用有明确的请求日志。所以一定要养成“主动验证触发”的习惯。我的验证方法分三步。第一步在描述里设置一个明确的触发动作比如“请对这个文件做代码审查”第二步给 Agent 一段明显包含关键信息的输入比如带隐患的代码片段看它的输出结构是不是遵从了 SKILL.md 里规定的报告格式第三步如果输出完全不按模板走用调试模式或 verbose 模式跑一遍确认是否加载了对应的 Skill 文件。有些 Agent 的调试输出里能看到“loaded skill: code-review”之类的信息看不到这部分就说明路径或描述出了问题。5.3 三个高频翻车点现象、原因与修复我收集过团队里 Skill 不生效的常见原因排在前面的是这三类翻车点典型现象根因修复方法description 太泛明明发起了“代码审查”但 Agent 完全按普通对话回答描述没有覆盖触发场景的词表按 3.1 的方法重写描述列出所有变体场景指令太长且前后矛盾Agent 执行到一半开始自由发挥或回答特别生硬步骤过多、约束过满上下文被占满精简指令到核心 10 步内把细节挪到 references缺输出模板分析内容挺好但格式五花八门每次都要人工整理没有在 SKILL.md 里给固定输出结构在指令末尾追加“输出必须包含以下字段”及示例这三类问题我全踩过。尤其是“指令太长”这条我早期总想在 Skill 里塞进所有团队规范结果是模型被压得完全失去了判断力只会机械式复述规则。后来才意识到Skill 的价值是把高水平的工作方法变成流程而不是代替人做所有判断。给 Agent 留一点自由度输出质量反而更高。6. 让 Skill 变成团队资产版本管理、经验录制与生态复用6.1 用 Git 管理 Skill 资产像管理代码一样管理“用法”既然 Skill 本质是团队工作方法论的数字化那它就值得享受代码同等待遇进 Git、走 Review、打版本。我推荐的团队仓库结构是这样team-skills/ ├── README.md ├── technical/ │ ├── code-review/ │ └── architecture-review/ ├── product/ │ └── prd-generator/ ├── management/ │ └── project-retrospective/ └── ai/ └── ai-architecture-review/每次修改 Skill 都跟改代码一样要有变更说明。尤其是指令部分任何一句措辞调整都可能改变 Agent 的输出行为所以在 PR 描述里写清楚“改了什么判断标准、加了哪个步骤”很重要。跑过一段时间后可以用 Git Tag 给稳定版本打标记团队内部按 Tag 固定使用版本避免“今天 Skill 还能用明天不知被谁改坏了”。6.2 用 Skill Recorder 沉淀专家操作流程我最近比较看好的方向是 Skill Recorder 这类工具。它的核心逻辑是专家在 Agent 里演示一遍操作流程系统把这次对话、调用的工具、步骤顺序记录下来自动整理成可复用的 Skill。这在团队里价值很大——资深工程师做演示时脑中的隐性知识会被显式化为标准流程。但使用录制类工具时要有一个清醒认知录出来的 Skill 是“专家在特定场景下的一次正确路径”不是普适真理。里面可能包含大量针对特定项目的分支判断直接给别人用会水土不服。所以录制完必须做一次人工清理去掉项目相关路径、删掉不必要的分支、抽象出真正通用的步骤。我的习惯是录制产物只当第一稿必须经过一次有经验的成员手工打磨再进团队仓库。6.3 从四个基础 Skill 开始再长出自己的技能树在这篇文章之外社区里已经出现很多垂直领域的 Skill比如数学建模、科研文献分析、特定语言和框架的辅助技能。不管用 Claude Code、Codex 还是其他 Agent定制逻辑都是同一套找高频场景、设计步骤、打磨描述、放进仓库、持续迭代。四个基础类目跑通之后你自然会发现更多值得封装的场景技能树会慢慢长出自己的形状。最后分享一点个人体会别一上来就搞十个 Skill。先挑技术类和产品类各做一个跑通一个完整周期——写好、放进去、触发、调格式、给同事用、按反馈改一版——再考虑扩展到管理类和 AI 类。Skill 的数量从来不是关键关键是你到底有没有把团队里最值钱的工作方法真正搬进 Agent 里。每多沉淀一个高质量 Skill团队在重复劳动上省下的时间都会在未来每一次触发时还回来。
从Prompt到Skill：技术/产品/管理/AI四大类Agent技能定制实战
最近想避开 Skill 这个词已经很难了。Claude Code 的 Agent Skills、Codex 的 Skill 目录再加上冒出来的各种 Skill 插件和录制工具几乎一夜之间把“给 AI 写长篇提示词”这件事升级成了“给 AI 打包一套完整工作方法”。但我观察到的问题是大多数人拿到 Skill 编辑器之后是懵的。有人把它当成超大号 Prompt有人抄了一份 SKILL.md 却发现 Agent 根本不触发更少有人认真想过——不同岗位、不同工作流要用到的 Skill定制思路其实完全不一样。这篇文章我会用一套自己项目里沉淀下来的“技术 / 产品 / 管理 / AI 四大类 Skill 定制模板”完整讲清楚每类 Skill 的设计侧重点、SKILL.md 的底层结构以及怎么放到 Claude Code、Codex 这类 Agent 环境里跑起来。适合正在用 AI 编程工具、想让 Agent 更懂团队流程的人也适合刚接触 Skill 但不知道从哪下手的开发者。如果你已经会写基础 Prompt全文可以直接当成一套可复用的工程框架来抄。1. Skill 定制的本质不是“写提示词”是“打包工作方法”1.1 把 Skill 当成“给新员工的 SOP 手册”先说一个最普遍的误解Skill 不是一次性的提示词它更像一个独立的小型能力包。提示词是“我临时找同事帮个忙把需求说清楚就行”Skill 是“入职第一天递到你手上的岗位 SOP”里面规定了什么情况下触发这个流程、按什么步骤执行、最终要交付什么格式的结果、哪些事情绝对不要做。放在 Agent 的视角里Skill 的承载形式通常是一个目录核心文件叫 SKILL.md。Claude Code 会扫描.claude/skills/下的技能目录Codex 也有类似机制。目录里除了解释“这个技能是什么、怎么用”的 SKILL.md还能放脚本、模板、参考资料。普通 Prompt 是“一次性对话的输入”Skill 是“对话过程中 Agent 能感知到、并按需自动加载的一个独立模块”。我习惯用“给新员工的 SOP 手册”来跟团队解释这个概念因为两者的本质一致把脑子里的经验、检查清单、输出标准外化成一份别人或别的模型照着就能执行的文件。所以定制 Skill 的第一性问题不是“怎么写指令”而是“我要把哪种反复出现的工作方法沉淀下来”。1.2 为什么先沉淀技术、产品、管理、AI 这四类不是所有工作都适合做成 Skill。如果一件事每天只出现一次、每次情况都完全不一样那用普通 Prompt 反而更灵活。但研发团队里绝大多数高价值工作恰恰是“高频重复 流程相对固定”的比如代码审查、需求分析、项目复盘、AI 方案评审。这类工作每做一次都从零开始想是巨大的隐性浪费。我自己的路径是先从技术类 Skill 做起的比如代码审查和架构评审。后来发现产品类和管理类 Skill 带来的团队效率提升甚至更明显因为这两类工作过去几乎没有工具能帮着“结构化”。再往后做 AI 应用项目时才发现 AI 类 Skill 是最难做、但也最值得做的——它服务的对象变成了“正在做 AI 系统的人”输入是模糊的架构问题输出必须是可决策的评审结论。四类 Skill 的定位差别可以用下面这张表直观表达类别核心目标服务人群典型场景沉淀对象技术类把工程红线变成自动检查开发、测试、运维代码审查、架构评审、安全审计、Bug 排查工程规范与检查清单产品类把需求思维变成产出模板产品经理、业务分析PRD、竞品分析、埋点设计、版本规划思考框架与输出模板管理类把项目推进变成结构化动作项目经理、技术负责人复盘、OKR、周报、会议纪要、风险预警追问机制与行动项提取AI 类把模型与 Agent 设计经验变成评审清单AI 应用开发团队Prompt 优化、模型选型、RAG 设计、Agent 架构评审评估维度与方案对比逻辑有了这张定位表再去设计每个 Skill 的内部结构思路会清晰很多。2. 四大类 Skill 的角色分工技术重规范、产品重思维、管理重推进、AI 重系统2.1 技术类 Skill把工程经验固化成可执行的规范技术类 Skill 的适用范围很广代码审查、架构设计评审、单元测试生成、Bug 排查、安全审计、技术方案评审甚至专利交底书初稿辅助。它们共同的特点是检查逻辑基本是确定的。比如让 Agent 审查一段代码我希望它按什么顺序看先看命名和可读性再看边界条件和异常处理接着看性能与安全隐患最后给出测试建议。这个顺序一旦定下来就可以固化成 Skill。设计技术类 Skill 时最忌讳的一句描述是“你会是一个资深技术专家请帮我分析这段代码”。这种描述没有给 Agent 任何可执行的抓手它只能凭通用知识自由发挥。真正有用的技术 Skill要像一份带“硬约束”的检查单必须检查哪些项目、每个检查项的判定标准是什么、输出必须分成几个等级严重 / 建议 / 可忽略、每个等级必须给出对应代码行号与修改建议。我在技术 Skill 里通常会内置一段“先检查后输出”的指令强制 Agent 在给出结论前先逐项对照清单。这跟人工 review 时的习惯一致先按流程走完再下结论而不是上来就凭感觉说“看起来不错”。2.2 产品类 Skill让 AI 按产品经理的思维方式工作产品类工作的特点是“输出物有固定模板但思考过程高度非线性”。比如写 PRD不同公司有不同模板但背后的思考链条是类似的目标用户是谁、业务背景是什么、这次要解决什么问题、怎么度量成功、有哪些边界情况、需要什么资源。产品类 Skill 的核心价值就是把这根思考链条封装进去让 AI 不是“直接生成一份报告”而是按产品经理的方式先提出问题、再组织信息、最后输出结构化文档。我做得比较成功的一个 PRD Skill开头就定义了一条硬性规则如果用户没有提供目标用户、业务背景和成功指标这三类信息必须先把这三个问题抛回去而不是自己编造答案继续写。这一步非常关键。普通 Prompt 常见的翻车方式是AI 为了显得专业会在信息不足时脑补一堆“可能存在的用户场景”结果做出一份看起来很完整、实际到处是假设的 PRD。产品类 Skill 要做的是逼着 AI 把“事实”和“假设”分开陈列所有未经确认的信息必须在文档里明确标注为“待确认假设”。这个机制一旦跑起来产品团队拿到的初稿质量会明显提升。2.3 管理类 Skill把复盘、OKR、会议变成固定动作管理类工作可能是最容易被 AI 工具忽略、但收益最大的领域。项目复盘、OKR 制定、周报、会议纪要、风险预警这些动作在团队里反复出现却很少有人为它们建立标准化流程。管理类 Skill 的设计目标是让 AI 从“写总结的工具”变成“推进项目的助手”。做项目复盘 Skill 时我一开始也踩过坑让 AI 直接生成复盘报告结果它把流水账重写了一遍没有任何洞察。后来我重新设计了指令把复盘拆成四个强制步骤还原事实、对比目标、根因分析、提取行动项。每一步都必须单独输出且没有走完前一步、AI 不得进入下一步。管理类 Skill 最该强化的是“追问机制”。人做复盘时之所以能挖出根因是因为会不断追问“为什么”。AI 天生更倾向于讨好式地回答而不是挑战用户。所以我在管理类 Skill 里明确写了一句特殊指令当用户提供的信息不足以支撑分析时必须连续追问每次只问一个最关键的缺口直到信息足够再开始输出结论。这句话配合结构化的分析步骤效果立竿见影。2.4 AI 类 Skill面向 Agent 开发者的元技能AI 类 Skill 是四类里最特殊的它用来服务“正在做 AI 应用的人”。典型场景包括 Prompt 优化、模型选型、RAG 方案设计、Agent 工作流编排、AI 应用架构评审。这类问题的特点是没有标准答案方案好坏取决于约束条件——成本、延迟、准确性、可维护性。所以 AI 类 Skill 的设计重心不是“告诉 Agent 正确答案”而是“逼着它做方案对比和权衡”。比如我写过一个 AI 应用架构评审 Skill它要求 Agent 对任何候选方案必须给出至少两个备选项并从上下文管理、工具调用可靠性、错误恢复、成本与延迟、可观测性五个维度逐一打分最后才给结论。如果讨论的是 Spring AI 这类框架的集成方案它还会额外要求列出框架本身的能力边界和社区维护情况。为什么一定要对比因为做 AI 应用的人十有八九会被“热门方案”带偏。直接问“帮我设计一个知识库问答系统”AI 默认就会往 RAG 上靠但如果 Skill 强制它先比较 RAG、Fine-tuning、长上下文三种路线再结合数据量、更新频率、成本预算来选产出的方案才真正可用。这个“先对比后结论”的纪律是 AI 类 Skill 区别于普通咨询式回答的核心。3. 定制模板的核心骨架SKILL.md 的元信息、指令与资源如何各司其职3.1 元信息name 和 description 决定了 Agent 什么时候“想起”这个 Skill很多人的 Skill 不生效问题往往出在最不起眼的元信息上。Agent 不会像人一样主动翻你的技能目录它是通过“当前对话内容”与 SKILL.md 里 description 的语义匹配度来判断要不要加载这个 Skill 的。所以 description 不是为了给人看而是为了给模型看。一段合格的 description需要包含四个要素什么时候用、输入是什么、输出是什么、相关的关键词。我见过最典型的失败案例是有人把 description 写成“代码审查相关”结果 Agent 在对话里看到“帮我 review 一下这段代码”时完全不觉得这跟“代码审查相关”有足够强的关联于是 Skill 永远不被触发。对比一下两种写法# 差的描述 description: 技术审查 # 可以用的描述 description: 当用户希望进行代码审查、合并请求评审、安全审计、技术债务评估或代码质量改进时使用。 输入为代码片段或文件路径输出为按严重程度分级的审查报告包含具体行号、问题说明与改进建议。后者把触发场景拓宽到了“合并请求评审”“安全审计”“技术债务评估”Agent 在不同语境下都能对上号。定制模板的第一步就是把 description 当成搜索引擎的索引词来写宁可多列几个同义场景也不要写得太抽象。3.2 指令正文分步骤、给范例、定边界Instruction 部分是 SKILL.md 的主体设计原则可以浓缩成三句话分步骤、给范例、定边界。分步骤很好理解把工作流拆成 5 到 10 个强制执行的步骤每一步说明输入、处理动作和中间产物。给范例则是很多模板里最容易漏的环节。大模型在没有示例时会按它对“正常输出”的统计偏好走给了一个 mini 示例后输出风格和结构都会被显著拉向示例的样子。定边界则是告诉 AI 不要做什么比如 PRD Skill 里写“不得编造用户访谈数据”、代码审查 Skill 里写“不要在没有复现的情况下断言存在死锁”这些负向约束能有效抑制幻觉。还要注意长度。Skill 一旦被触发SKILL.md 的内容都会进入上下文太长会挤占对话窗口、增加 token 成本。我的经验是单个 Skill 的指令正文控制在 200 到 500 行 Markdown 比较合适再多的细节放到 references 目录里按需加载。控制篇幅本身就是一种设计约束逼着你只保留最核心的检查项和步骤。3.3 资源目录从“纯文字指导”到“可执行工具”一个成熟的 Skill 不只是 SKILL.md它还可以带一套资源文件。我的标准目录结构长这样.claude/skills/code-review/ ├── SKILL.md # 触发元信息 执行步骤 输出格式 ├── scripts/ │ └── check_pr.py # 可选的静态检查 / 分析脚本 ├── templates/ │ └── review_template.md # 输出报告的 Markdown 模板 └── references/ ├── checklist.md # 详细的审查检查清单 └── security_rules.md # 安全与合规检查项这里有一个很重要的工作划分文本指令负责“怎么想”脚本负责“怎么算”。比如要快速定位某段代码里所有未捕获的异常与其让 AI 用眼睛一行行找不如在 scripts 里放一个脚本去扫描把结果喂回给 Agent 做分析。Skill 一旦能调用脚本它就从“一套说辞”升级成了“一个工具”。我在实际项目里最常用脚本的场景是统计代码行数、扫描 TODO 标记、解析 Git 提交记录、检查 API 调用点。这些确定性操作交给脚本文本指令专注于逻辑判断和报告生成两者各干各擅长的事效果最好。4. 从骨架到血肉技术/产品/管理/AI 四套 Skill 模板逐项拆解4.1 技术类模板代码审查 Skill 的完整骨架下面是我在项目里实际在用的一个代码审查 Skill 精简版你可以直接拿这个骨架去改--- name: code-review description: 当用户希望进行代码审查、合并请求评审、安全审计或技术债务评估时使用。 输入为代码片段或文件路径输出为按严重程度分级的审查报告。 --- # 代码审查流程 1. 获取审查对象。如果是文件路径先读取文件内容如果是代码片段直接使用。 2. 先审查可读性命名是否清晰、函数是否过长、是否存在重复逻辑。 3. 再审查正确性边界条件、空值处理、并发安全、异常是否被合理捕获。 4. 接着审查性能循环内是否有不必要查询、大数据量下是否有 O(n^2) 风险。 5. 最后审查安全性外部输入校验、权限判断、注入风险、敏感信息泄露。 6. 输出审查报告必须包含以下字段 - 严重问题P0/P1/P2 分级附精确行号 - 改进建议按优先级排序 - 修改后的代码示例仅对严重问题提供 7. 边界约束不得讨论与本次审查无关的代码不得在没有充分证据时断言存在性bug。 ## 输出示例 ### P1第 32 行未校验用户输入长度 当前代码直接拼接用户输入到 SQL存在注入风险。 建议使用参数化查询示例如下 ...仔细看这个骨架你会发现它每一段指令背后都有对应目的。第 2 到 5 步的顺序不是随便排的先看可读性是让 Reviewer 先理解代码再深入逻辑把性能和安全放在后面是因为如果没有前面对代码结构的理解安全和性能判断容易脱离实际。第 6 条强制输出格式是为了让报告能直接粘贴到 PR 评论里不需要人工二次加工。如果你要扩展成安全审计专用 Skill把第 5 步展开成更细的检查清单再加一个 references/security_rules.md 引用即可。4.2 产品类模板PRD 生成 Skill 的关键设计PRD 生成类 Skill 的技术难度不高难点全在“防编造”。我的模板里固定包含这么几条规则1. 信息收集阶段如果输入缺少业务背景、目标用户或成功指标主动向用户提问一次只问一个问题。 2. 禁止编造用户访谈、市场数据、竞品数据。如果确需引用但未提供标注为“假设待验证”。 3. 输出结构固定为 - 背景与问题 - 目标与非目标 - 用户角色与场景 - 需求描述按优先级分组 - 埋点与指标设计 - 验收标准 - 风险与依赖 4. 收尾前必须执行自检逐条核对需求描述是否有验收标准每个用户场景是否有对应功能所有指标是否可量化。为什么“一次只问一个问题”很重要因为多问会让用户烦而且回答质量会下降。AI 要扮演的不是调查员而是懂节奏的产品搭档。这个 Skill 真正提升效率的点在于第 4 条自检逻辑它复刻了资深产品经理在发文档前心里默默过一遍的流程。用 AI 做 PRD 初稿最怕的不是写得差而是写得“太顺”让人看不出逻辑漏洞。自检步骤就是用来强行把漏洞暴露出来的。4.3 管理类模板项目复盘 Skill 的“提问-分析-行动”闭环项目复盘类 Skill 有一个别的工作没有的优势它天然适合结构化的追问式对话。我的管理类 Skill 模板把复盘执行过程分成了四条硬性步骤第一步还原事实要求用户列出项目目标、关键时间点、实际结果差距数据必须精确到数字。 第二步对比目标逐项列出“计划 vs 实际”找出偏差最大的三个点。 第三步根因分析对每个偏差点执行连续追问—— 为什么会出现这个偏差 这是直接原因还是深层原因 如果再往下追一层会发现什么 至少追问三轮才能给出根因结论。 第四步提取行动项输出一个 Markdown 表格 包含行动项、负责人、截止时间、验证方式。管理类 Skill 的评判标准很简单复盘会的产出是否能让团队两周后验证“改善动作是否生效”。很多复盘会开完就完了就是因为最后一步“行动项”没有做到可验证。所以我在模板里强制要求每个行动项必须带验证方式和时间。另一个值得说的是第二步“只找偏差最大的三个点”——复盘最怕贪多嚼不烂一次聚焦三个根因团队才能真正消化。4.4 AI 类模板AI 应用架构评审 Skill 的维度设计AI 应用架构评审 Skill 是我四类模板里“元味”最重的一个它服务的不是具体的业务任务而是“评估一个 AI 系统设计得好不好”。核心指令是把评审工作拆成一连串固定维度评审输入AI 应用的技术方案、候选模型、系统架构图或文字描述。 必须执行的对比流程 1. 任务分析确定这是分类、生成、检索还是多轮 Agent 任务 2. 方案生成对当前需求给出至少两条备选技术路线 例如 RAG vs 长上下文 vs Fine-tuning 3. 五维评估 - 上下文管理输入长度、多轮记忆策略、检索片段组织方式 - 工具调用可靠性是否处理了工具返回错误、超时、重试 - 错误恢复当模型输出不符合预期时系统如何兜底 - 成本与延迟预估 token 消耗、首字延迟、扩容路径 - 可观测性是否有日志、追踪、评估集、回归测试 4. 输出给出推荐方案与理由附一张方案对比表。这类 Skill 之所以值得单独封装是因为 AI 应用的问题往往要在“系统层面”找答案。单点 prompt 调得再好上下文管理一塌糊涂整个系统依然没法用。有了这套维度团队在方案评审时就能把注意力拉到架构层面而不是陷入“哪个模型更强”的无休止争论。实际用下来它对我做技术选型和架构评审的启发甚至比产出结论本身更大。5. 模板落地的完整链路目录放置、触发调试与高频翻车点5.1 目录放置与自动加载配置模板做出来后第一件事是放进对应 Agent 的扫描目录。以 Claude Code 为例项目级 Skill 放在项目根目录的.claude/skills/下# 项目级 Skill只对当前仓库生效 mkdir -p .claude/skills/code-review # 如果你用 Codex也可以放它的技能目录 mkdir -p .codex/skills/code-review目录名建议全部小写并用连字符分隔因为目录名会作为 Skill 的标识之一被模型引用。除了项目级还可以放在用户级目录下让所有项目共用。我的建议是团队公共规范比如代码审查、PRD 模板放项目级跟随仓库走个人偏好型 Skill比如写作风格、日常工具脚本放用户级避免污染团队仓库。5.2 如何判断 Skill 是否真的被触发Skill 这玩意最反直觉的地方在于你放进目录后没有任何反馈告诉你“我加载了”。它不像插件有图标也不像工具调用有明确的请求日志。所以一定要养成“主动验证触发”的习惯。我的验证方法分三步。第一步在描述里设置一个明确的触发动作比如“请对这个文件做代码审查”第二步给 Agent 一段明显包含关键信息的输入比如带隐患的代码片段看它的输出结构是不是遵从了 SKILL.md 里规定的报告格式第三步如果输出完全不按模板走用调试模式或 verbose 模式跑一遍确认是否加载了对应的 Skill 文件。有些 Agent 的调试输出里能看到“loaded skill: code-review”之类的信息看不到这部分就说明路径或描述出了问题。5.3 三个高频翻车点现象、原因与修复我收集过团队里 Skill 不生效的常见原因排在前面的是这三类翻车点典型现象根因修复方法description 太泛明明发起了“代码审查”但 Agent 完全按普通对话回答描述没有覆盖触发场景的词表按 3.1 的方法重写描述列出所有变体场景指令太长且前后矛盾Agent 执行到一半开始自由发挥或回答特别生硬步骤过多、约束过满上下文被占满精简指令到核心 10 步内把细节挪到 references缺输出模板分析内容挺好但格式五花八门每次都要人工整理没有在 SKILL.md 里给固定输出结构在指令末尾追加“输出必须包含以下字段”及示例这三类问题我全踩过。尤其是“指令太长”这条我早期总想在 Skill 里塞进所有团队规范结果是模型被压得完全失去了判断力只会机械式复述规则。后来才意识到Skill 的价值是把高水平的工作方法变成流程而不是代替人做所有判断。给 Agent 留一点自由度输出质量反而更高。6. 让 Skill 变成团队资产版本管理、经验录制与生态复用6.1 用 Git 管理 Skill 资产像管理代码一样管理“用法”既然 Skill 本质是团队工作方法论的数字化那它就值得享受代码同等待遇进 Git、走 Review、打版本。我推荐的团队仓库结构是这样team-skills/ ├── README.md ├── technical/ │ ├── code-review/ │ └── architecture-review/ ├── product/ │ └── prd-generator/ ├── management/ │ └── project-retrospective/ └── ai/ └── ai-architecture-review/每次修改 Skill 都跟改代码一样要有变更说明。尤其是指令部分任何一句措辞调整都可能改变 Agent 的输出行为所以在 PR 描述里写清楚“改了什么判断标准、加了哪个步骤”很重要。跑过一段时间后可以用 Git Tag 给稳定版本打标记团队内部按 Tag 固定使用版本避免“今天 Skill 还能用明天不知被谁改坏了”。6.2 用 Skill Recorder 沉淀专家操作流程我最近比较看好的方向是 Skill Recorder 这类工具。它的核心逻辑是专家在 Agent 里演示一遍操作流程系统把这次对话、调用的工具、步骤顺序记录下来自动整理成可复用的 Skill。这在团队里价值很大——资深工程师做演示时脑中的隐性知识会被显式化为标准流程。但使用录制类工具时要有一个清醒认知录出来的 Skill 是“专家在特定场景下的一次正确路径”不是普适真理。里面可能包含大量针对特定项目的分支判断直接给别人用会水土不服。所以录制完必须做一次人工清理去掉项目相关路径、删掉不必要的分支、抽象出真正通用的步骤。我的习惯是录制产物只当第一稿必须经过一次有经验的成员手工打磨再进团队仓库。6.3 从四个基础 Skill 开始再长出自己的技能树在这篇文章之外社区里已经出现很多垂直领域的 Skill比如数学建模、科研文献分析、特定语言和框架的辅助技能。不管用 Claude Code、Codex 还是其他 Agent定制逻辑都是同一套找高频场景、设计步骤、打磨描述、放进仓库、持续迭代。四个基础类目跑通之后你自然会发现更多值得封装的场景技能树会慢慢长出自己的形状。最后分享一点个人体会别一上来就搞十个 Skill。先挑技术类和产品类各做一个跑通一个完整周期——写好、放进去、触发、调格式、给同事用、按反馈改一版——再考虑扩展到管理类和 AI 类。Skill 的数量从来不是关键关键是你到底有没有把团队里最值钱的工作方法真正搬进 Agent 里。每多沉淀一个高质量 Skill团队在重复劳动上省下的时间都会在未来每一次触发时还回来。 
