Agent Skill 的工程化落地：从“提示词堆砌“到“能力模块化“

一、问题的本质为什么 Prompt 工程不够用了大模型有一个被长期忽视的结构性缺陷每轮对话都是一次失忆重启。无论之前聊过多少轮模型都必须从零开始重建上下文。这催生了 Prompt 工程把团队规范、技术选型、架构约束写成一份CLAUDE.md每次会话启动时自动注入。但这条路走到深处会遇到三个天花板上下文通胀项目越复杂Prompt 越臃肿。所有领域知识一股脑塞进系统提示词上下文窗口被撑满关键信息反而被稀释。这就像把整本员工手册塞给新同事让他一次性读完真正重要的安全红线反而淹没在细节里。零复用性知识和项目深度耦合换个场景就得重写。A 项目的实验管理流程到了 B 项目无法直接复用团队陷入重复造轮子的泥潭。注意力稀释模型注意力是有限的。当无关信息持续占用 token真正需要聚焦的任务指令反而被噪声淹没。Agent Skill 的出现本质上是对上述问题的模块化回应。二、Skill 的核心设计哲学渐进性披露Anthropic 给 Skill 下了一个精准定义Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.翻译成人话Skill 是给 AI Agent 的「入职指南」把特定领域的专业能力打包成可发现、可复用的模块Agent 按需加载。但 Skill 体系真正的设计精髓不是模块化本身而是渐进性披露Progressive Disclosure只在需要时才加载需要的知识。这个机制分三个阶段运转阶段加载内容资源消耗Discovery发现仅namedescription常驻注入极低成本Activation激活完整SKILL.md 路由表 全局规则命中时加载中等成本Execution执行按路由表加载对应模块文件 参考文档按需读取精准投放这就是按需投放知识的经济学用最小的上下文成本换取最大的知识覆盖范围。绝大部分请求只需要部分资源上下文窗口永远留给当下真正重要的信息。三、Skill 与 System Prompt 不是替代关系是协同关系很多团队容易混淆两者的定位。一句话区分System Prompt 是这个项目的规矩Skill 是一种可复用的能力。维度System PromptSkill定位项目级全局规则、编码规范特定领域能力封装加载策略会话启动时全量加载渐进式按需加载生效范围当前项目可跨项目、跨会话上下文成本恒定占用与任务无关也消耗仅命中时加载未命中零成本组织结构单文件扁平多文件模块化支持脚本和资源适用场景编码风格、项目约定、通用约束完整工作流、多步骤流程、领域专家知识最佳实践是两者协同System Prompt 定义全局编码规范对所有 Skill 生效Skill 封装特定领域工作流激活时叠加内部规则。四、Skill 的物理结构一个文件夹就是一个能力包Skill 的核心是一个包含 SKILL.md 的文件夹已被 Claude Code、Cursor、GitHub Copilot、Gemini CLI 等 40 主流 Agent 产品采纳成为事实上的开放标准。my-skill/ # Skill 名称短横线分隔 ├── SKILL.md # 唯一入口也是唯一触发器 ├── scripts/ # 可执行脚本突破 LLM 能力边界 ├── references/ # 参考文档低频查阅知识 ├── assets/ # 模板、资源 └── ... # 任意额外文件SKILL.md 的两层结构1. Frontmatter元信息决定 Skill 的身份和权限最核心的两个字段nameSkill 的唯一标识符也是文件夹名。最长 64 字符只能用小写字母、数字和连字符。description这是 Skill 能否被正确触发的生命线。Agent 靠这段描述来判断当前任务该不该调用这个 Skill。必须同时回答 WHAT做什么和 WHEN什么时候用。其他关键字段包括权限控制allowed-tools、disable-model-invocation、运行时环境context、agent、生命周期钩子hooks等。2. 正文指令应该是路由器不是仓库SKILL.md 正文的职责是分发任务到正确的模块而非包含所有业务细节。控制在 500 行以内约 2000-3000 token是单个 Skill 激活后比较合理的上下文开销。五、触发机制description 是 Skill 的门面Skill 的触发机制比内容本身更重要再好的 Skill如果无法被正确激活就是废代码。两种触发方式自动触发语义匹配Agent 根据 description 判断这个任务我有现成的专业流程可以用然后主动加载。用户无感像老员工听到需求自动翻出 SOP。手动触发斜杠命令用户通过 /skill-name 显式调用。适合老用户精确控制。description 的书写公式Claude Code 推荐功能定义 触发场景 核心能力写好它需要四个原则同时回答 WHAT 和 WHEN不能只说处理文档要明确做什么、在什么场景下调用。枚举具体触发词Agent 做语义匹配时关键词越具体命中率越高。不仅要写术语还要写口语化说法。比如创建实验、新建、做个实验、建个 AB全都要写进去。用第三人称description 会被注入系统提示词要写成客观描述。✅Generates API documentation from source code❌I can help you generate docs划定排除边界可选明确标注不适用场景降低误触发概率。六、知识分层如何决定这段知识该放哪Skill 设计的核心挑战是知识分层。一条经验法则文件超过 300 行或某个 Step 的规则超过 100 行就是拆分信号。分层决策树如下这段知识是否每次激活 Skill 都需要 ├── 是 → 放 SKILL.md入口文件每次必读 └── 否 → 是否每次进入该模块时都需要 ├── 是 → 放模块主文件如 creator.md └── 否 → 是否仅在某个特定 Step 才需要 ├── 是 → 放对应 phase 文件如 collect-phase.md └── 否 → 是否只在特定条件下查阅 ├── 是 → 放参考文件tools.md / safety.md └── 否 → 考虑是否需要保留实战案例trade-skill 的分层实践trade-ab-skill/ ├── SKILL.md ← 意图路由表、全局安全红线每次激活必读 ├── modules/creator/creator.md ← 创建流程 Step 编排、scenarioId 对照表 ├── modules/creator/collect-phase.md ← 参数填充的 11 项执行清单仅 Step 2 读 ├── modules/creator/validate-phase.md ← 校验规则仅 Step 3 读 ├── modules/creator/tools.md ← MCP 工具接口列表调接口时按需查阅 └── modules/creator/safety.md ← 安全约束详细规则validate 阶段按需加载核心原则越频繁用到的知识离入口越近越偶尔查阅的知识越往深处放。七、安全实践模块级工具隔离当 Skill 涉及多个模块、调用多个 MCP 接口时必须实施模块级工具隔离每个模块只能调用白名单中的接口遵循权限最小化原则。设计原则白名单制每个模块的 tools.md 明确列出可用接口白名单外一律禁止。危险接口显式禁用万能工具如直接 HTTP 调用全局禁止。工具隔离不同模块使用不同接口集合防止误调用。trade-skill 的隔离实践实验创建接口仅在 creator 白名单中modifier 只能用实验修改接口审批/发布接口在所有模块中均禁止调用modifier 模块明确标注易混淆接口的禁止规则八、脚本增强让 Skill 突破 LLM 的能力边界核心理念确定性计算逻辑封装为脚本由 Agent 调用执行而非自行推导。什么时候该写成脚本如果这件事让 LLM 做有概率出错但脚本能 100% 确定性完成那就该封装。场景LLM 的局限脚本的优势配置文件读写可能写入格式错误的 JSON保证格式正确原子写入环境检测无法可靠检测系统状态直接查询返回结构化结果日志采集不应直接处理网络请求封装 HTTP 调用异常自处理复杂计算算术不可靠精确计算脚本设计四原则自愈性内部处理所有异常始终正常退出绝不阻断 Skill 主流程结构化输出统一输出 JSON方便 Agent 解析和流转幂等性多次执行结果一致预检脚本只追加缺失项不覆盖已有配置安全边界只操作指定文件不触碰其他系统资源trade-skill 实战MCP 预检脚本Skill 启动前自动检测 MCP 依赖是否就绪日志采集脚本采集实验操作日志Agent 只需调用脚本、读取返回的 JSON不用自己猜环境状态九、参数传递与状态持久化Skill 不是静态指令支持运行时参数传递和上下文预注入。参数传递三原则显式参数来源和去向清晰可追溯可校验每个阶段有门卡检查参数完整性防丢失关键参数在快照中持久化trade-skill 的快照机制每个阶段将产出写入快照下一阶段从快照读取。阶段门卡确保参数完整性。用户偏好持久化成功操作后将关键参数写入 user-prefs.json下次执行时自动注入{ defaultScenarioId: 场景ID, defaultMetricTemplateId: 模板ID, recentExperimentIds: [实验ID1, 实验ID2], lastUsed: 2026-06-17, usageCount: 2 }十、测试与迭代Skill 也是软件需要工程化测试Claude Code 官方推荐三类核心测试1. 触发测试准备 10 个左右的自然语言变体去触发 Skill检查是否都能正确激活。同时验证不相关输入是否会误触发。2. 功能走查用自然语言驱动完整流程检查每个阶段输出是否符合预期。重点验证路由是否准确分发渐进加载是否按时序工作红线规则是否被遵守异常场景是否正确熔断关键别只跑 happy path。故意输入边界值、模拟工具不可用、尝试让 Agent 调用禁止接口才是真正暴露问题的场景。3. 性能对比针对同一任务分别用无 Skill和有 Skill两种方式各跑 5 次对比 Token 用量和完成质量。迭代方法论与传统软件 bug 修复逻辑一致发现问题 → 定位原因 → 修复文档 → 验证效果。最高效的方式是观测驱动迭代通过日志埋点收集每次执行的状态结果成功/失败/取消、耗时、调用的工具列表用数据定位薄弱环节。trade-skill 的日志采集机制采用了两阶段 traceId 配对追踪保障了全链路可观测。十一、从 0 到 1用 skill-creator 创建你的第一个 Skillskill-creator 本身也是一个 Skill用来创建和打包 Skill。整个流程可以浓缩为下载 skill-creator ↓ 告诉 AI初始化目录 ↓ 告诉 AI编写 SKILL.md references ↓ 告诉 AI打包验证自动校验 frontmatter、name、description、非法文件 ↓ 告诉 AIgit 提交并推送 ↓ 告诉 AI迭代修改并推送从头到尾你没有手动执行过任何命令。只负责描述意图AI 负责执行这就是 Vibe Coding 的魅力。十二、写在最后Skill 体系的价值不只是把 Prompt 拆成文件这么简单。它本质上是在解决一个更深层的问题如何让 AI Agent 在复杂业务场景中像资深工程师一样知道什么时候该用什么能力。从 Prompt 工程到 Skill 工程不是技术的升级而是思维方式的升级从给模型喂更多知识转向让模型更聪明地选择知识。当你的团队开始规模化使用 AI Agent 时Skill 体系就是那张能力地图。学习资源推荐如果你想更深入地学习大模型以下是一些非常有价值的学习资源这些资源将帮助你从不同角度学习大模型提升你的实践能力。一、全套AGI大模型学习路线AI大模型时代的学习之旅从基础到前沿掌握人工智能的核心技能​因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取二、640套AI大模型报告合集这套包含640份报告的合集涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师还是对AI大模型感兴趣的爱好者这套报告合集都将为您提供宝贵的信息和启示​因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取三、AI大模型经典PDF籍随着人工智能技术的飞速发展AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型如GPT-3、BERT、XLNet等以其强大的语言理解和生成能力正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取四、AI大模型商业化落地方案作为普通人入局大模型时代需要持续学习和实践不断提高自己的技能和认知水平同时也需要有责任感和伦理意识为人工智能的健康发展贡献力量。