Agent Skill 原理解析与使用：从 Prompt 到可复用的 Agent 能力

简介最近在 AI 编程、Agent、Claude Code、Cursor 等工具中一个越来越常见的概念是Agent Skill。很多人第一次看到 Skill会把它理解成“高级 Prompt”。其实并不准确。如果 Prompt 是“告诉 AI 应该怎么做。”那么 Skill 更像把一套稳定的专业经验、执行流程、工具和资源封装成 Agent 可以按需加载和复用的能力模块。Anthropic 官方将 Skill 定义为一个包含SKILL.md、指令、脚本和资源的目录并通过**渐进式加载Progressive Disclosure**让 Agent 在需要时获取对应能力。一、为什么需要 Skill传统 AI 编程通常是用户 ↓ Prompt ↓ LLM ↓ 代码例如每次让 AI 排查 Flink 问题都需要重新告诉它先看 JobManager 日志 再看 TaskManager 日志 再看 YARN Application 然后判断是不是 checkpoint 如果是内存问题检查 JVM / RocksDB 最后定位 Flink 源码问题是这些经验无法很好地沉淀。于是出现了 Skill┌──────────────┐ │ Agent │ └──────┬───────┘ │ 按需加载 Skill │ ┌─────────────┴─────────────┐ ↓ ↓ Flink Skill Kafka Skill ↓ ↓ 排障流程/规范 排障流程/规范 ↓ ↓ scripts/ references/Skill 的核心价值不是“让模型知道更多知识”而是把人的专业经验转化成 Agent 可以复用的执行规范。二、Skill 到底是什么一个标准 Skill本质上是一个目录flink-diagnosis/ ├── SKILL.md ├── scripts/ │ ├── collect_logs.sh │ └── check_checkpoint.py ├── references/ │ ├── flink-memory.md │ ├── flink-network.md │ └── flink-source.md └── assets/其中SKILL.md 核心规则 scripts/ 可执行程序 references/ 专业资料 assets/ 模板、配置等资源最核心的是SKILL.md它通常包含 YAML Front Matter--- name: flink-diagnosis description: Diagnose Flink jobs, YARN deployments, memory issues and runtime failures. ---下面则是具体的执行规范# Flink Diagnosis ## 适用场景 用于排查 Flink JobManager、TaskManager、YARN 以及 Checkpoint 等问题。 ## 执行流程 1. 收集日志 2. 提取异常 3. 判断问题类型 4. 定位源码 5. 给出修复方案因此可以把 Skill 理解成SOP 专业知识 工具 资源。Anthropic 官方也采用类似的文件夹模型并要求SKILL.md至少包含name和description元数据。三、Skill 最重要的设计渐进式加载Skill 真正有价值的地方并不是“把更多 Prompt 塞给模型”。而是只在需要的时候加载需要的信息。假设有 100 个 SkillFlink Kafka MySQL Redis Java Spring Kubernetes Docker ...如果启动 Agent 时把所有内容全部塞进 Context100 个 Skill ↓ 大量 Markdown ↓ 大量 Token ↓ Context 膨胀显然不可行。Skill 使用的是Progressive Disclosure也就是渐进式加载。可以简单理解成三层L1Metadata ↓ 知道“我有哪些 Skill” L2SKILL.md ↓ 知道“这个 Skill 怎么工作” L3references / scripts ↓ 需要的时候才读取具体资料和执行代码例如Agent 启动 ↓ 加载 flink-diagnosis kafka-diagnosis mysql-diagnosis 只加载 name description用户问Flink Checkpoint 为什么失败Agent 判断flink-diagnosis匹配。于是读取 SKILL.md ↓ 发现需要 checkpoint 资料 ↓ 读取 references/flink-checkpoint.md ↓ 必要时执行 scripts/check_checkpoint.py而不是一开始就把所有内容加载进 Context。这也是 Skill 能够规模化的重要原因。Anthropic 官方明确将 Progressive Disclosure 作为 Skills 的核心设计原则。四、Skill 和 Prompt、Tool、MCP、Agent 有什么区别这是最容易混淆的地方。1. Skill vs PromptPromptSkill本质一次性指令可复用能力模块生命周期临时长期结构一段文本文件夹知识通常混在 Prompt 中可拆分工具通常需要额外描述可以包含 scripts复用复制粘贴安装/共享版本管理较弱Git 等方式管理一句话Prompt 告诉 Agent 一次怎么做Skill 把“怎么做”沉淀下来。五、Skill vs Tool两者解决的是完全不同的问题。Tool 解决Agent 能做什么例如query_mysql() get_yarn_log() search_github() execute_shell()Skill 解决Agent 应该怎么做例如排查 Flink 内存问题 1. 先看 process memory 2. 再看 JVM heap 3. 再看 managed memory 4. 再判断 RocksDB 5. 最后检查 OOM 日志所以Tool 能力 Skill 方法六、Skill vs MCPMCP 更像是Agent 与外部世界连接的协议。例如通过 MCPAgent ↓ MCP ├── MySQL ├── GitHub ├── Kubernetes ├── Jira └── 企业内部系统但是 MCP 只解决“怎么访问”并不天然解决“应该怎么使用这些工具完成一个复杂任务”这正是 Skill 的价值。例如MCP ↓ 提供 get_yarn_log() get_flink_job() query_metrics()SkillFlink Diagnosis Skill ↓ 1. 获取 Job 2. 获取日志 3. 获取 Metrics 4. 判断异常 5. 定位源码 6. 给出修复方案所以最合理的组合是Agent │ ┌───────┴───────┐ ↓ ↓ Skill MCP │ │ 告诉怎么做 提供怎么访问 │ │ └───────┬───────┘ ↓ 完成任务Anthropic 对这一关系的概括也非常接近Skills 是工作流和专业知识层而 MCP 等工具机制负责提供外部系统能力。七、Skill 的运行原理把整个过程串起来User Request │ ↓ Agent / LLM │ ┌───────┴───────┐ ↓ ↓ Skill Metadata Tools/MCP │ ↓ 意图匹配 │ ↓ Load SKILL.md │ ↓ 判断是否需要额外资源 │ ┌────────┴────────┐ ↓ ↓ references/ scripts/ │ │ ↓ ↓ 获取知识 执行代码 │ │ └────────┬────────┘ ↓ Agent ↓ 最终结果这里有一个非常重要的认识Skill 不是模型本身变聪明了而是给模型增加了一套可以动态获取的专业上下文和执行方法。八、实战创建一个 Flink Diagnosis Skill假设我们希望 Agent 自动排查 Flink 问题。目录flink-diagnosis/ ├── SKILL.md ├── references/ │ ├── memory.md │ ├── checkpoint.md │ ├── kafka.md │ └── yarn.md └── scripts/ ├── collect_logs.sh └── check_memory.pySKILL.md--- name: flink-diagnosis description: Diagnose Flink job failures, memory problems, checkpoint failures, Kafka issues and YARN deployment problems. --- # Flink Diagnosis ## 目标 帮助开发人员定位 Flink 运行问题。 ## 标准流程 ### 1. 收集证据 获取 - Job ID - Application ID - JobManager 日志 - TaskManager 日志 - YARN 日志 - Checkpoint 信息 ### 2. 分类 判断问题属于 - JVM / Memory - Checkpoint - Kafka - Network - YARN - ClassLoader - State ### 3. 深入分析 根据问题类型读取 references。 ### 4. 源码定位 如果是 Flink 框架问题 1. 确认 Flink 版本 2. 定位源码 3. 分析调用链 4. 给出具体源码位置 ### 5. 输出 最终输出 - 现象 - 证据 - 根因 - 源码位置 - 修复方案然后用户只需要说Flink 任务为什么一直 checkpoint timeoutAgent 就可以匹配 flink-diagnosis ↓ 读取 SKILL.md ↓ 发现需要 checkpoint 规则 ↓ 读取 checkpoint.md ↓ 调用日志/监控工具 ↓ 分析 ↓ 输出结论九、Skill 真正适合解决什么问题Skill 最适合的不是“回答知识问题”。而是重复、专业、流程比较稳定的复杂任务。例如代码审查 Skill Flink 诊断 Skill SQL 优化 Skill 数据质量 Skill 数据治理 Skill 故障复盘 Skill 接口设计 Skill 架构设计 Skill例如企业内部可以沉淀企业 Agent │ ┌───────────────┼───────────────┐ ↓ ↓ ↓ Flink Skill Data Skill Java Skill │ │ │ ↓ ↓ ↓ 运维经验 数据治理 编码规范这时候 AI 就不再只是“一个会写代码的大模型。”而逐渐变成掌握企业工作方法的 Agent。十、Skill 的工程化关键不要把它写成“大 Prompt”这是实际使用 Skill 最容易犯的错误。错误方式SKILL.md ↓ 5000 行 Prompt ↓ 所有知识全部塞进去最终 Skill 会变成新的 Context 污染源。更合理的方式SKILL.md │ ├── 核心流程 ├── 判断条件 ├── 输出规范 │ ├── references/ │ ├── 场景A │ ├── 场景B │ └── 场景C │ └── scripts/ ├── 工具A └── 工具B核心原则SKILL.md 负责“导航”references 负责“知识”scripts 负责“执行”。十一、Skill MCP才是完整的 Agent 能力单独使用 SkillSkill ↓ 知识 流程单独使用 MCPMCP ↓ 工具 数据组合以后Agent │ ┌─────────┴─────────┐ ↓ ↓ Skill MCP │ │ 怎么做 能做什么 │ │ └─────────┬─────────┘ ↓ Workflow ↓ Result例如你的 Flink 平台Flink Diagnosis Skill │ ├── Flink 排障流程 ├── Flink 源码知识 ├── 故障判断规则 │ ↓ MCP │ ├── 查询 Flink Job ├── 查询 YARN ├── 查询日志 ├── 查询 Metrics └── 查询配置这时 Agent 才真正具备“知道怎么排查 有能力执行排查”。十二、最后Skill 的本质是什么如果只记住一句话Agent Skill 可复用、可组合、按需加载的 Agent 专业能力模块。它不是 Prompt 的简单升级也不是 MCP 的替代品。更准确的关系是Agent │ ┌────────┼────────┐ ↓ ↓ ↓ Model Skill Tools │ │ │ MCP │ │ └────┬───┘ ↓ Workflow ↓ Result其中Model → 思考 Skill → 方法 Tool → 能力 MCP → 连接 Agent → 编排而 Skill 最重要的价值是把过去存在于人的经验 聊天记录 Prompt Wiki 代码脚本 故障手册中的“做事方法”逐渐沉淀成Skill │ ┌─────────┼─────────┐ ↓ ↓ ↓ 指令流程 专业知识 可执行代码 │ │ │ └─────────┼─────────┘ ↓ Agent ↓ 可复用能力这可能才是 Skills 真正值得关注的地方当 Prompt 开始被文件化、标准化、版本化并与 Tool、MCP、代码执行结合以后Agent 的“经验”开始从一次性对话变成可以被团队复用和持续迭代的软件资产。