Agent Skills (Claude Skills) 深度解析与实操指南

一、 【核心理念与宏观背景】

1.1 核心痛点：提示词膨胀与 Token 焦虑

在 AI Agent 开发与应用中，开发者常面临“既要又要”的困境：既希望模型具备复杂的业务逻辑处理能力（需要长 Prompt），又希望降低响应延迟与 Token 成本（需要短 Prompt）。

  • Prompt 冗余：全量加载系统指令导致模型注意力稀释，易产生指令幻觉。
  • 逻辑耦合：特定业务规则（如财务标准、写作风格）与对话过程高度耦合，难以复用。

1.2 底层思维模型：渐进式披露（Progressive Disclosure）

Agent Skills 的本质是将“指令”从“对话”中解耦，构建一套结构化的能力模块系统。其核心逻辑是渐进式披露：AI 在初始阶段仅感知技能的“存在”，只有在任务匹配时才加载“细节”。

  • 解耦思维：将 Agent 的能力拆解为独立、可插拔的模块。
  • 按需加载：类似于计算机内存管理中的“换页机制”，只在运行时调取必要数据。

二/ 【核心模型与方法论详解】

2.1 Agent Skills 三层分层架构

  • 顶层（宽）：元数据层 (Metadata) —— 始终在线，用于初次匹配。
  • 中层（中）：指令层 (Instruction) —— 选中后激活，定义执行逻辑。
  • 底层（窄）：资源层 (Resources) —— 包含 Reference（读）和 Script（跑），极度精准。

2.1.1 元数据层 (Metadata) —— “技能名片”

  • 定义：Skill 的身份标识，通常由六个横杠包裹。
  • 核心字段：
    • name: 唯一标识符（需与文件夹名一致）。
    • description: 关键字段。描述该技能的适用场景，AI 根据此字段判断何时“激活”该技能。

2.1.2 指令层 (Instruction) —— “操作手册”

  • 内容：存放在 skill.md 中的具体规则。
  • 作用：定义角色设定（System Role）、任务约束、输出格式及 Few-shot 案例。

2.1.3 资源层 (Resources) —— “外挂装备”

这是 Agent Skills 实现复杂任务的核心：

  • Reference (参考资料)：存放于 references/ 目录。模型仅在需要特定知识（如法律条文、范文）时才通过 read 方法读取。
  • Script (执行脚本)：存放于 scripts/ 目录。核心逻辑：模型仅触发执行并接收结果，不读取脚本源码，从而实现“万行逻辑，零 Token 占用”。

2.2 实操步骤：从 0 到 1 构建 Skill

  1. 环境定义：在项目根目录创建 .cloud/skills/（或 .codex/skills/）文件夹。
  2. 创建技能单元：新建子文件夹（如 subtitle_processor）。
  3. 编写定义文件：创建 skill.MD（必须大写），结构如下： 
    ---
name: subtitle_processor
description: 当用户上传 SRT 字幕文件并要求整理笔记时调用。
---
# 指令
1. 提取时间轴文字...
2. 保持原文禁止总结...
3. 在 [screenshot] 标记处调用脚本进行截图...
  4. 配置辅助资源：根据需求在 references/ 放入参考文档，或在 scripts/ 放入 Python/Shell 脚本。
  5. 全局化配置（进阶）：将技能包放入用户配置目录（如 C:\Users\Name\.cloud\skills），使其在所有项目中生效。

三、 【案例深度复盘】

案例 1：自动化视频转笔记（技术与动作的闭环）

  • 场景：将 SRT 字幕转换为带截图的 Markdown 笔记。
  • 逻辑拆解：
    • 元数据：定义“识别 SRT 文件”为触发条件。
    • 指令层：规定 Markdown 格式，并在关键位置预留截图占位符。
    • 资源层 (Script)：提供一个 Python 脚本，调用 FFmpeg 根据时间戳截取视频。
  • 执行结果：AI 先生成文案，随后主动申请运行脚本，最终输出图文并茂的笔记。
  • 启示：通过 Script 避开了 AI 无法直接处理视频流的短板，实现了“逻辑推理”与“物理执行”的分离。

案例 2：合规性会议总结（知识与规则的按需加载）

  • 场景：处理会议录音转文字，并进行财务合规检查。
  • 逻辑拆解：
    • 指令层：定义会议总结的标准化模板（参会人、议题、结论）。
    • 资源层 (Reference)：存放《集团财务报销手册.md》。
  • 执行逻辑：只有当会议内容提及“预算”、“报销”等关键词时，AI 才会调用 read 方法读取手册。
  • 启示：避免了在所有会议总结中都塞入冗长的财务手册，显著提升了非财务会议的处理效率。

四、 【实操/应用场景：Agent Skills vs. MCP】

作为产品经理，在设计 Agent 架构时必须分清两者的边界：

维度Agent SkillsMCP (Model Context Protocol)
本质定义结构化的说明文档/逻辑包独立运行的通信程序/工具箱
核心功能教会模型“如何处理数据”（逻辑控制）为模型“供给外部数据”（数据连接）
加载机制渐进式披露（省 Token）静态加载或工具调用（消耗取决于返回量）
编写门槛低（Markdown 编写为主）高（需要 Node.js/Python 开发环境）
适用场景写作风格、业务准则、轻量化本地脚本数据库连接、实时 API 调用、跨平台集成

PM 避坑与最佳实践：

  1. 不要在 Skills 里写复杂逻辑：涉及数据库写入、复杂 API 交互应封装为 MCP Server，确保稳定性。
  2. 不要在 MCP 里写 Prompt：MCP 应保持纯净的数据接口，具体的输出格式、语气约束应放在 Skills 的指令层。
  3. 协同模式：MCP 负责“取回数据”，Skills 负责“定义如何加工这些数据”。

五、 【学习总结】

  1. 从“写 Prompt”向“定义能力模块”转变：Agent Skills 标志着 Prompt 工程进入了模块化、标准化的新阶段。
  2. 极致的 Token 优化逻辑：通过“元数据 -> 指令 -> 资源”的漏斗模型，解决了长上下文带来的成本与幻觉问题。
  3. “读”与“跑”的完美解耦：Reference 负责提供背景（读内容），Script 负责执行动作（跑结果），构建了 Agent 的完整闭环。
  4. 核心金句：
    • “Agent Skills 是带目录的说明书，让 AI 只在需要时翻开特定的一页。”
    • “MCP 连接数据，Skills 赋予灵魂。”
    • “优秀的 Agent 设计，在于让模型在最干净的上下文中做最复杂的推理。”