Skill 核心概念、原理与实践指南引言为什么我们需要讨论 Skill在当前的 AI 浪潮中我们常常惊叹大模型强大的对话和推理能力。然而当我们将 Agent 从“玩具”推向“工具”尝试让它在真实、复杂的业务场景中稳定、可靠地完成任务时它就很容易暴露出稳定性、流程一致性和领域知识不足的问题。如何将我们已有的业务流程、最佳实践和领域知识高效地“传授”给 Agent让它从一个泛泛而谈的“通才”成长为能够独当一面的“专家”Skill 正是解决这一问题的核心概念。一、概念解析什么是 Skill二、核心价值Skill 解决了什么问题三、原理分析Skill 是如何工作的四、实践应用Skill 的落地场景五、问题与解答问题 1Agent 中的 Skill 和传统的函数/API 有什么本质区别问题 2PE、Rule、Skill 和 MCP 是如何协同工作的一个用户请求从输入到输出这四者可能参与的完整过程。问题 3当一个 Skill 执行失败时如何设计其失败处理和兜底机制问题 4什么样的任务适合被沉淀为 Skill什么样的不适合问题 5Skill 的when_to_use应该如何设计才能最大化意图识别的准确率问题 6当两个 Skill 的when_to_use发生重叠时Agent 应该如何决策问题 7在 Skill 的一个步骤中如果需要进行复杂的逻辑判断if / else, for loop应该如何实现一、概念解析什么是 Skill1. Skill 的准确定义一句话定义Skill 是一种结构化的、可复用的能力单元它将完成特定任务的“标准作业流程”SOP封装起来指导 Agent 如何一步步地执行复杂工作。如果把 Skill 看成一份可复用的“标准作业流程”Standard Operating Procedure那么 Agent 就是在运行这份 SOP 的执行者。真实的 Claude Skill 实现里“何时该用”通常不是一个独立的when_to_use字段而是直接写在 frontmatter 的description里而“怎么做”则主要写在正文的步骤说明中。与零散的提示词Prompt不同Skill 是一个更加完备、独立的“能力包”。它不仅包含指导模型思考的指令还集成了必要的工具调用、逻辑判断和结果处理构成了一个端到端End-to-end的任务解决方案。2. Skill 与 Agent 的关系在一个成熟的 Agent 系统中Skill 扮演着“能力库”或“技能树”的角色。Agent 本身是一个调度和执行引擎而 Skill 则是其可以调用的、解决具体问题的“函数库”。Agent 是“调用方”当 Agent 接收到用户意图后它的首要任务之一就是理解意图并在自己的“技能库”中寻找最匹配的 Skill 来执行。Skill 是“执行方”一旦被选中Skill 便接管任务按照预设的流程开始执行直至任务完成或遇到需要 Agent 进一步决策的节点。这种“引擎 技能”的架构使得 Agent 的能力可以被持续扩展、迭代和治理就像我们可以随时为操作系统安装新的应用程序一样。每个 Skill 的沉淀都意味着 Agent 在特定领域的专业能力得到了一次“固化”和“增强”。二、核心价值Skill 解决了什么问题引入 Skill 机制并非简单地将任务流程“代码化”其背后解决的是将 LLM 从“通用模型”转化为“可靠生产力工具”过程中的一系列核心痛点。1. 稳定性与确定性问题LLM 的输出具有不确定性Non-deterministic。对于同一个复杂任务即使输入相同两次运行的结果也可能大相径庭。这种“自由发挥”在创意场景下是优点但在需要精确、可靠的业务流程中却是致命缺陷。Skill 的解法通过预定义的步骤StepsSkill 为任务执行提供了一个“确定性框架”。它将一个大任务拆解为一系列更小、更明确的子任务并在关键节点上约束模型的行为。流程的确定性无论模型版本如何迭代任务的执行流程都始终遵循 Skill 定义的 SOP。例如“生成销售周报”的 Skill 会确保 Agent 总是先拉取数据再进行汇总分析最后生成图表这个顺序不会改变。结果的确定性通过在流程中加入明确的指令和工具调用Skill 显著提升了最终产出的一致性。例如通过调用固定的数据 API 并使用模板化的语言生成报告可以保证报告格式和关键指标的准确无误。2. 知识的沉淀与复用问题团队的业务知识和最佳实践往往以文档、代码片段、甚至“口口相传”的形式散落在各处难以形成合力。新员工需要花费大量时间学习而 Agent 更无从下手。Skill 的解法Skill 成为了一个承载和复用“领域知识”的绝佳容器。业务流程沉淀将一个成熟的业务流程如“新员工入职 IT 配置”、“用户反馈分类与打标”封装为 Skill相当于将团队的集体智慧程序化使其可被 Agent 直接调用。最佳实践固化在 PE提示工程探索中发现的高效 Prompt 模式、效果最好的工具组合都可以固化到 Skill 中避免重复造轮子让好的经验规模化复用。3. 模块化与可治理性问题随着 Agent 能力的增加一个“万能”的、包含所有逻辑的庞大系统会迅速变得难以维护、迭代和审计。“牵一发而动全身”的困境会严重制约其发展。Skill 的解法Skill 将 Agent 的能力体系解耦为一个个独立的、高内聚的模块。独立版本化每个 Skill 都可以独立开发、测试、上线和回滚。对“A 技能”的修改不会影响到“B 技能”的稳定性使得敏捷迭代成为可能。权限与审计可以对 Skill 进行细粒度的权限控制例如只有财务团队的 Agent 才能调用“财务报销审批”技能。同时每个 Skill 的调用记录都清晰可查便于问题追溯和安全审计。跨团队共享一个设计良好的 Skill可以被发布到企业或团队的“技能市场”供其他业务线的 Agent 按需“安装”和使用极大地促进了能力的跨团队共享与协作。三、原理分析Skill 是如何工作的理解了 Skill 的价值之后我们继续深入探究其技术实现和核心原理。1. Skill 的核心构成一个 Skill 通常以一个文件夹的形式存在其核心是一个名为SKILL.md的清单文件它定义了 Skill 的全部信息。示例一个典型的 Skill 文件结构一个 Skill 通常包含清单文件SKILL.md以及可选的scripts和assets目录如下方结构所示my_report_skill/ ├── SKILL.md # 必须定义 Skill 的元信息和执行流程SOP ├── scripts/ # 可选存放 Skill 执行中可能用到的 Python/Shell 脚本 │ └── analyze.py └── assets/ # 可选存放报告模板、配置文件、示例数据等资源 └── report_template.docx真实的SKILL.md通常由两层构成FrontmatterYAML 元信息name技能的唯一标识符如WeeklyReportGenerator。description对技能用途和触发场景的自然语言描述。这是 Skill 能否被正确调用的关键入口。BodyMarkdown 正文正文并不是可执行配置文件而是写给 Claude 的操作说明。它通常包含步骤、注意事项、工具使用约束、脚本位置、参考文件导航等内容。可以把很多文章里抽象出来的when_to_use理解为真实实现里写进description的那部分触发描述。换句话说在 Claude Skill 体系里触发条件不是一套独立 DSL而是 frontmatter 里的自然语言。2. 触发机制的真实工作方式Skill 的触发并非魔法而是一个两阶段的上下文注入过程第一阶段元数据常驻上下文所有已安装 Skill 的name和description会以available_skills之类的列表形式常驻在系统上下文中。Claude 每次响应前都能看到这份“技能菜单”。第二阶段正文按需加载只有当 Claude 判断某个 Skill 与当前请求匹配时才会去读取完整的SKILL.md正文并把它注入当前上下文然后再按照正文里的说明执行任务。这意味着description是真实实现里的核心触发入口。正文再好、脚本再完善如果description写得模糊Skill 也可能永远不会被启用。3. 三层加载为什么这样设计这个设计的核心动机是上下文窗口Context Window的经济性。第一层元数据namedescription常驻成本最低。第二层SKILL.md正文只在命中后才加载避免把所有技能说明都塞进上下文。第三层scripts/、references/、assets/等资源按需读取或执行不必默认占用上下文。这样设计的好处是让“技能菜单”始终可见同时把大体积说明、脚本和资源推迟到真正需要时再读从而把有限的上下文预算留给当前任务。4. 与工具Tool / MCP和协议的衔接Skill 本身定义了“做什么”What和“按什么顺序做”When但具体“怎么做”How的技术细节则通过与工具Tool的衔接来完成。Skill 是流程编排者Skill 的步骤中会包含对工具的调用指令。例如Step 2使用 get_weather_api 工具并将提取到的“城市名称”作为参数传入。MCP 是工具的“驱动程序”get_weather_api这个工具本身是通过模型上下文协议Model Context ProtocolMCP注册到 Agent 系统中的。MCP 定义了工具的名称、功能描述、输入输出参数和调用方式。它像一个标准化的“插座”让任何外部 API 或服务都能安全、规范地被 Agent 调用。因此Skill 负责业务流程MCP 负责技术实现。Skill 将业务逻辑与具体的工具实现解耦使得二者可以独立演进。5. 与 PE、MCP、Rule 的分工与边界在 Agent 的架构中PE、Skill、MCP、Rule 是四个不同层次、不同职责的组件。混淆它们的定位是常见的误区。下面我们通过一个架构分层图和对比表格来厘清它们的边界。架构分层PEPrompt Engineering处于最灵活的“交互层”。它主要优化 Agent 与用户之间的单轮对话质量通过精心设计的提示词引导模型更好地思考和表达。它关注的是“对话的艺术”。MCP模型上下文协议作为“连接器”负责将外部世界的能力API、数据库、脚本安全、标准地接入 Agent。它关注的是“能力的接入标准”。Skill技能构成了 Agent 的“能力核心”。它将多步骤的复杂任务流程化、结构化形成可复用的能力资产。它关注的是“如何成事”。Rule规则负责在执行前后增加约束、审计和兜底。它关注的是“什么不能做”以及“结果是否合规”。详细对比与快速决策为了在实际工作中快速决策下表从多个维度对这四个概念进行了详细对比。对比维度技能Skill提示工程PE模型上下文协议MCP规则Rule核心作用封装并沉淀可复用的、多步骤任务流程提升单次推理与表达质量标准化工具接入约束行为边界与合规关注点任务完整步骤如何提问、如何引导模型思考能力如何暴露什么不能做、结果是否合规典型形态SKILL.md的 frontmatter Markdown 正文 可选脚本/资源Prompt、Few-shot、CoTTool Schema、接口定义、鉴权与调用规范前置检查、后置审计、权限与策略配置执行时机意图匹配并触发 Skill 后几乎每次推理时都可能参与调用工具时前置检查 后置审计与 Agent 的关系是 Agent 的“能力库”定义它会“做什么事”是 Agent“思考表达”的燃料是 Agent 与外部世界交互的“桥梁”和“插座”是 Agent 行为边界的“护栏”四、实践应用Skill 的落地场景理论的价值在于指导实践。下面我们通过三个具体的落地场景来展示 Skill 在不同领域中的实际应用。这些例子经过简化和泛化旨在说明核心思想不涉及内部保密实现。1. 场景一研发运维 - “服务异常根因分析” Skill背景线上服务出现告警后SRE站点可靠性工程师同学通常需要执行一系列标准化的排查动作查看告警详情、拉取服务日志、分析关键指标QPS、Latency、Error Rate、检查最近的发布变更等。这个过程耗时且高度依赖个人经验。Skill 设计思路ServiceAnomaliesAnalysisSkill元信息description中的触发描述用户询问“服务 xx 为什么告警了”收到来自监控系统的告警通知用户要求分析某个服务的异常表现执行流程Steps[思考]从用户输入或告警信息中提取“服务名称”和“时间范围”。若信息不足则向用户追问。[工具]调用argos.get_alerts工具获取指定服务的告警详情。[工具]调用sls.query_logs工具拉取异常时间点前后的ERROR和WARN级别的日志。[工具]调用monitoring.get_metrics工具获取服务的核心指标图表QPS、Latency、Error Rate。[工具]调用bits.get_deploy_history工具查询该服务在异常发生前的发布记录。[思考]关键步骤综合以上所有信息告警、日志、指标、变更进行关联分析并生成初步的根因推测。这一步会使用一个精心设计的 CoTChain of ThoughtPrompt引导模型像一个资深 SRE 一样思考。[产出]将分析过程、关键证据日志片段、指标图和初步结论结构化地回复给用户并提供深入排查的建议。2. 场景二运营分析 - “用户负反馈洞察” Skill背景产品运营团队需要定期整理来自用户群、应用商店、工单系统等渠道的用户负反馈进行归类、打标、统计并提炼出高价值的洞察作为产品迭代的输入。这个过程繁琐、重复性高。Skill 设计思路UserFeedbackInsightSkill元信息description中的触发描述用户要求“分析一下本周的用户负反馈”每周一自动触发执行流程Steps[工具]并行调用多个工具从不同渠道拉取数据lark.im.get_messages获取指定用户群中包含“吐槽”、“建议”、“不好用”等关键词的聊天记录。app_store.get_reviews拉取应用商店的最新评论。zendesk.get_tickets获取客服工单系统中被标记为“产品问题”的工单。[思考]将所有来源的文本数据进行清洗和预处理。[思考]设计一个分类和打标的 Prompt对每一条反馈进行多维度分类如功能 Bug、体验问题、新功能建议和情感判断如强烈不满、一般抱怨。[工具]调用bytedance_base.write_records工具将处理后的数据写入一个多维表格方便追溯和二次分析。[思考]对多维表格中的数据进行聚合统计识别出本周 Top 3 的高频问题和值得关注的新增长问题。[产出]生成一份简报包含核心数据图表、典型用户原声和关键词摘要并自动发送给运营团队的 Lark 群。3. 场景三人力资源 - “面试安排协调” Skill背景为候选人安排多轮面试需要协调面试官、候选人和 HR 三方的时间预订会议室并发送日历邀请。这个过程沟通成本极高来回拉扯效率低下。Skill 设计思路InterviewCoordinatorSkill元信息description中的触发描述HR 在招聘系统中点击“安排面试”按钮用户在群里 Agent 说“帮 XX 候选人的一下面”执行流程Steps[思考]提取“候选人”、“面试官列表”、“面试轮次”等关键信息。[工具]调用lark.calendar.get_free_busy工具分别查询所有面试官和候选人在未来 3 个工作日的空闲时段。[思考]找出所有人都有空的共同时间片Time Slots。[交互产出]如果找到共同时间片向 HR 或用户展示可选时间并询问选择哪一个。如果未找到则建议将面试官分组或提供更晚的时间选项。[工具]用户确认时间后调用lark.calendar.create_event工具创建日历事件自动添加所有参与人。[工具]在日历事件的描述中附上面试官的姓名、候选人的简历链接并自动预订一个空闲会议室。[产出]在群里或通过 IM 告知 HR“面试已安排在 [时间]日历邀请已发送。”4. GitHub 上值得重点关注的 8 个 Skill / 技能仓如果把前面的内容看成“原理篇”那么这一小节就是“选型篇”。下面这 8 个仓库并不是机械意义上的严格星数排行榜而是截至目前在 GitHub 上热度较高、社区可见度高、且对理解SKILL.md生态最有代表性的项目。阅读顺序建议是先看官方再看工程化仓库最后看社区技能集和自定义 Skill。1.anthropics/skillsAnthropic 官方 Skills 仓库是理解 Claude 原生 Skill 机制的第一手材料。它最适合用来回答三个基础问题Skill 长什么样、frontmatter 怎么写、正文步骤应该怎么组织。适合用途理解官方 Skill 结构、触发方式、文档类 Skill 的真实写法。推荐原因官方定义最权威尤其适合用来校正“什么是真实实现、什么只是框架抽象”。GitHubhttps://github.com/anthropics/skills2.openai/skillsOpenAI 官方 Skills Catalog更适合用来观察 Codex 生态里的 Skill 组织方式。它可以帮助你把“Claude 风格的 Skill”和“Codex 风格的 Skill”放在同一张图里对比理解。适合用途做 Claude / Codex 技能体系对照理解官方目录化组织方式。推荐原因如果你的文章面向“后端 AI Agent 工程实践”这个仓库能补足 OpenAI 侧的视角。GitHubhttps://github.com/openai/skills3.vercel-labs/skills这是 Vercel 推动的开放技能工具链工程味很重适合看“技能如何跨 Agent 复用”“技能如何接近 npm 化分发”这类问题。适合用途理解技能市场化、跨代理复用、工程安装与分发。推荐原因它不是单纯的示例合集而是在推动 Skill 走向标准化工具链。GitHubhttps://github.com/vercel-labs/skills4.ast-grep/claude-skill这是一个非常典型的“强工具型 Skill”。它的价值不在于内容多而在于它清楚展示了 Skill 如何把结构化代码搜索能力包装成 Agent 可调用的专业技能。适合用途代码检索、结构化重构、规则匹配、静态分析辅助。推荐原因对于后端工程师来说它特别适合拿来理解“Skill 专用工具”的协作模式。GitHubhttps://github.com/ast-grep/claude-skill5.levnikolaevich/claude-code-skills这个仓库偏完整研发流程覆盖研究、拆解、实现、测试、review、质量门禁是“工程化工作流 Skill”很好的样本。适合用途看一整套研发交付链路如何被拆成多个可复用 Skill。推荐原因相比单点能力型 Skill它更适合用来讲“技能树”和“多 Skill 协作”。GitHubhttps://github.com/levnikolaevich/claude-code-skills6.alirezarezvani/claude-skills这是社区里比较典型的大而全技能集合覆盖内容创作、分析、开发、业务等多个方向适合拿来感受“技能仓库”作为知识资产库的形态。适合用途观察社区如何组织多领域 Skill、脚本和模板。推荐原因示例丰富便于理解 Skill 不只服务编码也能覆盖运营、营销和业务分析。GitHubhttps://github.com/alirezarezvani/claude-skills7.zechenzhangAGI/claude-ai-research-skills这个仓库更偏 AI 研究与工程适合想把 Agent 打造成“研究助理”或“论文工程助手”的场景。适合用途文献调研、AI 研究流程、模型实验与工程工作流辅助。推荐原因它代表了 Skill 从“软件开发助手”走向“研究型 Agent”的另一条路线。GitHubhttps://github.com/zechenzhangAGI/claude-ai-research-skills8. 自己写一个skill-article-fact-check-cn真正能体现你理解了 Skill 的不只是“会用别人写的 Skill”而是“能按真实机制写出一个自己的 Skill”。比如当前文章主题是 Skill 面试题与原理讲解那么最适合定制的 Skill其实就是一个“中文技能文档事实校对 Skill”。--- name: skill-article-fact-check-cn description: Use when the user is writing, revising, or fact-checking Chinese articles, notes, interview QA, or tutorials about Claude Code skills, Codex skills, SKILL.md structure, skill triggering, description/frontmatter semantics, bash_tool script execution, or MCP/tool boundaries. Especially use when the user asks to 核对、校对、事实检查、基于真实 skill 修改文档、补充真实实现、或对照 GitHub skill 仓库修正文档。 --- # Skill Article Fact Check CN ## Goal 基于真实 SKILL.md、真实 GitHub skill 仓库和真实工具调用方式校对中文技能文档避免把“框架设计建议”写成“Claude/Codex 的真实实现”。 ## Steps ### Step 1收集真实素材 优先读取本地已有 skill如果不足再去 GitHub 查 2 到 5 个真实 skill 仓库。 ### Step 2抽取真实实现要点 重点确认 - frontmatter 是否只有 name / description - 正文是否为自然语言 SOP - 是否通过脚本目录 bash_tool 执行复杂逻辑 - 是否存在显式优先级、置信度、结构化 when_to_use 字段 ### Step 3对照待修改文档 把文档里的说法分成三类 - 真实实现 - 通用框架设计建议 - 明显不准确或容易误导的说法 ### Step 4输出修改建议 按“必须改 / 建议改 / 可保留”三档输出并给出替换文案。 ### Step 5直接改文档 如果用户要求落地修改则直接把相关章节改成 Markdown 成稿不只停留在建议层。 ## Rules - 不要臆测 Claude 原生行为。 - 不要把自研 Agent 框架的设计写成 Claude 的真实机制。 - 优先用真实 SKILL.md 例子说话。 - 输出中文保留必要英文术语。个人推荐skillanthropics/skills用来建立“官方正确概念”。openai/skills用来建立“跨平台对比视角”。ast-grep/claude-skill用来理解“Skill 专业工具”的模式。skill-article-fact-check-cn用来体现你已经具备“自己设计 Skill”的能力。五、问题与解答问题 1Agent 中的 Skill 和传统的函数/API 有什么本质区别核心定位不同函数/API 是纯粹的技术实现。它封装了一段确定的代码逻辑忠实地执行输入到输出的转换不关心“为什么”调用它。Skill 是一个业务解决方案。它封装了一个完整的、解决特定业务问题的“流程”SOP。它不仅包含对函数/API 的调用还包含了业务逻辑、决策判断和上下文理解。组成部分不同一个函数通常只有代码实现。一个 Skill 除了可以调用代码工具还包含元信息主要是description用于意图识别以及正文步骤Steps用于流程编排。这使得 Skill 具备了“被 Agent 发现并调度”的能力。抽象层次不同函数/API 位于技术实现层。Skill 位于业务逻辑层更贴近最终用户的需求。一个 Skill 的执行过程可能会调用多个不同的函数/API。问题 2PE、Rule、Skill 和 MCP 是如何协同工作的一个用户请求从输入到输出这四者可能参与的完整过程。用户输入与意图识别PE / Skill 的description发挥作用用户发出请求例如“帮我分析一下上周销售额暴跌的原因”。Agent 首先使用 PE 技巧如 CoT Prompt来更好地理解用户意图拆解其需求包含“上周”、“销售额”、“暴跌原因”等关键点。同时Agent 会将这个意图与“技能库”中所有 Skill 的description描述进行匹配发现SalesDataAnalysisSkill 的触发描述“分析销售数据异动”高度相关于是决定激活 Skill。前置检查Rule 发挥作用在执行任何操作前Rule 引擎介入。它会检查当前用户是否有权限访问销售数据数据安全 Rule以及请求内容是否包含敏感词合规 Rule。如果违反规则流程将被中止并提示。任务执行Skill 与 MCP 发挥作用Rule 检查通过后SalesDataAnalysisSkill 开始按其Steps执行。Step 1调用get_sales_data工具。此时MCP 介入它提供了该工具的 schema告诉 Agent 如何调用、需要什么参数如start_date、end_date并负责把实际的 API 请求和鉴权。Step 2调用get_marketing_events工具再次通过 MCP 获取同期的市场活动数据。Step 3Skill 内部的 PE 指令相当于一个复杂的 Prompt指导模型对销售数据和市场活动数据进行关联分析寻找可能的因果关系。Step 4生成分析报告。后置处理与输出Rule 发挥作用报告生成后Rule 再次介入检查报告内容是否符合预设的格式规范以及是否意外泄露了不该展示的细节信息如具体到个人的销售业绩。最终格式化、合规的报告被呈现给用户。问题 3当一个 Skill 执行失败时如何设计其失败处理和兜底机制步骤级重试Step-level Retry对于网络波动、偶发性服务超时等可能导致的工具调用失败应在 Skill 的步骤中支持配置重试机制如重试 3 次间隔 1 秒。这是最基础的容错。明确的错误处理分支Explicit Error Handling在 Skill 的Steps设计中可以定义条件分支。例如“如果get_user_profile工具返回‘用户不存在’则执行 B 流程如果返回‘查询超时’则执行 C 流程”。这使得失败处理本身也成为流程的一部分。状态降级与用户引导Graceful Degradation User Guidance如果某个关键工具彻底不可用Skill 不应直接崩溃而应提供一个“降级”的服务。例如“数据分析”Skill 在无法获取实时数据时可以退而求其次使用上一次的缓存数据并明确告知用户“当前结果基于缓存数据可能不是最新的”。当 Skill 无法自动处理失败时最好的兜底是向用户清晰地解释问题并提供可行的下一步建议。例如“抱歉我无法连接数据库。请检查网络连接或联系系统管理员。需要我帮您创建一条报障工单吗”全局捕获与日志记录Global Catch LoggingAgent 的执行引擎应该有一个全局的异常捕获机制。任何未被 Skill 内部处理的失败都应被捕获、详细记录包括 Skill 名称、失败步骤、输入参数、错误信息并向用户展示一个友好的通用错误提示。这些日志是后续迭代优化 Skill 的关键依据。问题 4什么样的任务适合被沉淀为 Skill什么样的不适合适合沉淀为 Skill 的任务特征a. 流程相对固定任务包含多个步骤且执行顺序有较强的逻辑性。如“代码发布流程”、“周报生成”。b. 需要高稳定性和一致性任务结果的准确性、格式等有明确要求不能容忍模型的“自由发挥”。如“财务对账”、“合同生成”。c. 高频复用任务被频繁执行自动化能带来显著的效率提升。如“查询订单状态”、“创建会议纪要”。d. 知识密集任务的执行依赖大量领域知识和最佳实践通过 Skill 可以将这些知识固化下来。如“医疗影像初步诊断辅助”、“法律文书草拟”。不适合或需要谨慎沉淀为 Skill 的任务特征a. 纯粹的创意或开放式对话对于没有固定流程、完全依赖灵感和发散性思维的任务强行用 Skill 会限制其效果。如“和我聊聊天”、“帮我想个团队口号”。这类任务更适合纯 PE。b. 流程极度不稳定或多变如果一个业务流程本身还在快速探索阶段每天都在变过早地将其固化为 Skill 会带来巨大的维护成本。c. 单一步骤的简单查询如果任务只是调用一个 API 并直接返回结果没有复杂的流程那么直接将其定义为一个工具Tool / MCP就足够了没必要“杀鸡用牛刀”再包一层 Skill。问题 5Skill 的when_to_use应该如何设计才能最大化意图识别的准确率如果讨论真实的 Claude Skill那么这里所谓的when_to_use本质上就是 frontmatter 里的description该怎么写。它不是一套结构化 DSL而是一段普通的自然语言字符串。5.1 真实系统里的设计原则description是唯一的触发入口Claude 首先看到的是技能列表里的name和description而不是正文步骤。用自然语言把触发场景写具体不要只写“分析销售数据”要把指标名、业务场景、用户常见问法都写进去。同时写正例和反例既说明“什么时候该触发”也说明“什么时候不要触发”。兼顾召回和精度描述过短会漏召回描述过泛会误触发。明确角色和边界如果某个 Skill 只适用于特定角色、特定系统或特定数据域应直接写进description。5.2 真实的description写法对比弱触发写法---name:sales-data-analysisdescription:分析销售数据---强触发写法---name:sales-data-analysisdescription:当用户需要分析销售数据、业绩趋势、GMV/AOV/复购率等电商核心指标时使用。适用场景包括月度或周度销售复盘、销售额异动分析、分渠道业绩对比。当用户询问“销售为什么下滑”“帮我出周报”“看看上周数据”时触发。不要在用户仅询问指标定义、概念解释或销售技巧时触发。即使用户没有明确说“分析”只要话题明显是在看销售表现也应该使用此 Skill。---这个例子反映了一个很重要的工程经验Claude 在实际使用中往往对 Skill 触发偏保守更容易直接回答而不是主动加载 Skill。因此description应该写得稍微强势一点把触发条件描述得具体且覆盖常见表达。5.3 从“多信号”到“自然语言描述”虽然真实实现里没有and、not、user_role这种结构化字段但这些信号依然重要只是要被翻译成自然语言写进description里。信号维度应该如何体现在description中作用正例关键词直接写用户常见问法如“分析报告”“帮我出周报”“看一下趋势”快速召回覆盖明确意图领域特征写清核心术语如“GMV”“AOV”“复购率”“QPS”“Latency”缩小范围提高领域相关性上下文线索用自然语言写出场景如“月度复盘”“异常波动分析”“收到报警时”精细化场景排除歧义用户画像与权限直接写“仅适用于财务管理员”或“适用于销售经理”个性化触发保障安全负触发条件明确写“不要在用户只问定义/概念/技巧时触发”降低误报率5.4 建立度量与迭代闭环description的优化是一个持续迭代的过程必须依赖数据驱动。核心度量指标准确率Precision/ 召回率Recall触发的 Skill 是否正确以及应该触发的 Skill 是否都被触发了。F1-Score准确率和召回率的调和平均综合评估。澄清率Agent 主动发起澄清的比例。过高说明description设计模糊过低则可能意味着误触发被隐藏。误触发率False Positive Rate错误触发 Skill 的比例这是影响用户体验的关键。description设计要点回顾一个设计良好的description应该把正例、反例、领域特征、上下文和角色边界全部写成自然语言而不是依赖虚构的结构化语法。真实系统里Skill 能否被发现首先取决于这段文字写得是否具体、清晰、可召回。问题 6当两个 Skill 的when_to_use发生重叠时Agent 应该如何决策Skill 重叠是 Agent 能力扩展过程中的必然现象处理不好会导致意图路由混乱甚至执行错误的任务。这需要一套健全的路由策略Routing Strategy和治理机制。先说明边界以下“置信度打分”“优先级矩阵”“Tie-breaking”更适用于自研 Agent 框架的路由层设计。在 Claude 原生 Skill 体系中并没有显式暴露出来的置信度分数或优先级字段冲突解决主要依赖 Skill 的description是否写得足够有区分度以及 Claude 自身的自然语言判断。路由决策策略当多个 Skill 同时被激活时Agent 需要一个决策模型来选择最合适的一个。静态优先级矩阵Static Priority Matrix为每个 Skill 预设一个优先级如 1-100。高优先级的 Skill 在发生冲突时总是被优先选择。适用场景当业务关键性、风险、合规要求有明确高低之分时。例如“删除数据库” Skill 的优先级必须高于“查询数据” Skill。置信度打分与阈值Confidence Scoring ThresholdAgent 的意图识别模型为每个匹配到的 Skill 计算一个置信度分数0-1。决策逻辑如果最高分超过阈值如 0.9且与其他候选项拉开足够差距如超过 0.2则直接选择最高分。如果最高分低于阈值或多个候选项分数接近则进入澄清环节。Tie-breaking 规则平局决胜当多个 Skill 置信度分数极其接近时使用预设的规则来打破僵局。常见规则最近使用Most Recently Used优先选择用户最近调用过的 Skill。角色偏好Role Preference根据用户角色选择与其工作最相关的 Skill。上下文限定Contextual Fit选择与当前对话上下文最贴合的 Skill。多轮澄清与候选呈现Clarification Candidate Presentation这是最重要也是最友好的策略。当 Agent 不确定时把决策权交还给用户。方式“检测到您可能想做以下几件事请选择一个\n1. 分析销售数据\n2. 查询销售指标定义\n或者都不是。”组合执行与降级回退Composition Fallback在某些高级场景下Agent 可以判断出需要依次执行多个 Skill 来完成任务。或者当前选 Skill 执行失败时自动尝试执行次选的、功能上有所降级的 Skill。伪代码示例决策逻辑defroute_skill(user_intent,matched_skills):# matched_skills 是一个列表包含skill, confidence_score, priorityifnotmatched_skills:returnSorry, I cant help with that.# 按优先级和置信度排序sorted_skillssorted(matched_skills,keylambdax:(x.priority,x.confidence_score),reverseTrue)top_skillsorted_skills[0]# 规则 1高置信度直接推荐iftop_skill.confidence_score0.9:returnfExecuting{top_skill.name}# 规则 2分数接近需要澄清iflen(sorted_skills)1:second_skillsorted_skills[1]if(top_skill.confidence_score-second_skill.confidence_score)0.1:returnfWhich one do you mean? 1.{top_skill.name}or 2.{second_skill.name}# 规则 3默认选择最高分但提示用户returnfIm guessing you mean{top_skill.name}. Lets proceed. (If not, say stop)问题 7在 Skill 的一个步骤中如果需要进行复杂的逻辑判断if / else, for loop应该如何实现这是 Skill 设计中“表达能力”与“可维护性”的权衡问题。真实的 Claude Skill 里Steps本质上是写给 Claude 的自然语言 SOP而不是可执行的 YAML 配置文件。因此复杂逻辑的正确做法不是发明一套script.run之类的抽象而是把逻辑下沉到外部脚本再在正文里明确告诉 Claude 如何调用。推荐做法与原则保持正文步骤是“声明式”的写清楚要做什么、调用什么工具、产出什么结果。把复杂的if / else / for loop放进scripts/目录中的 Python/Shell 脚本里。在SKILL.md的步骤里用自然语言指示 Claude 使用bash_tool执行脚本。让脚本负责确定性逻辑让 Skill 正文负责业务流程编排。这样做有四个直接好处关注点分离Skill 专注于业务流程脚本专注于技术实现。可测试性脚本可以独立单测和集成测试。真实贴近实现符合 Claude Skill 正文是 Markdown 指令、不是 DSL 配置的实际形态。可维护性复杂控制流放在脚本里比塞进 Skill 正文更稳定。示例真实的SKILL.md步骤写法## Steps ### Step 1获取原始数据 调用 data_api.fetch 工具获取指定时间范围的数据保存结果备用。 ### Step 2执行数据处理 使用 bash_tool 运行以下命令 bash python scripts/process_data.py --input {{上一步的输出}} 将脚本输出的 JSON 结果保存供下一步使用。 ### Step 3生成报告 基于处理后的数据生成结构化报告。对应的scripts/process_data.py可以写成普通脚本importargparseimportjsonimportsysdefmain():parserargparse.ArgumentParser()parser.add_argument(--input,requiredTrue)argsparser.parse_args()input_datajson.loads(args.input)processed_results[]foritemininput_data.get(items,[]):ifitem.get(value,0)100anditem.get(category)A:processed_results.append({id:item[id],highlight:True,message:fHigh value item found:{item[id]},})print(json.dumps({results:processed_results}))if__name____main__:try:main()exceptExceptionase:print(json.dumps({error:str(e)}),filesys.stderr)sys.exit(1)一句话总结Skill 的Steps应该描述“让 Claude 去做什么”而不是把复杂控制流直接写成一套伪配置语言真正的复杂逻辑应通过bash_tool调脚本来完成。