强烈推荐
【Agent Skill 从使用到原理，一次讲清】https://www.bilibili.com/video/BV1cGigBQE6n?vd_source=902ab50946cdc18cb283e68160fafb6d

Agent Skills 的一次工程实践

一、Agent Skills 介绍

1. 简介
   Create, manage, and share Skills to extend Claude’s capabilities in Claude Code.
   This guide shows you how to create, use, and manage Agent Skills in Claude Code. Skills are modular capabilities that extend Claude’s functionality through organized folders containing instructions, scripts, and resources.
   Claude Code 官方文档对 Agent Skills 的描述 ：技能 (Skill) 是由指令、脚本和资源组成的模块化功能包，能够扩展 Claude 智能体的能力。这些技能存放在特定目录下（每个技能一个文件夹），当 Claude 判断某个技能与当前用户请求相关时，便会自动加载相应技能来完成任务。这种触发是模型自主决策的，而非需用户手动指定调用

2. 特性 – 三层渐进式披露
   Agent Skills 的核心设计理念是渐进式披露（Progressive Disclosure） 。这意味着技能的信息分为三个层次，Claude 按需逐步加载，既确保必要时不遗漏细节，又避免一次性将过多内容塞入上下文：

• 元数据（Metadata） – 第一层：每个技能的 SKILL.md 文件开头都有 YAML 元信息，包括技能的名称和描述。例如，name: mysql-employees-nl2sql-analysis，description: …。在智能体启动时，Claude 会预加载所有已安装技能的元数据到系统提示中 。元数据提供了何时使用该技能的线索，让模型对技能用途有初步了解，但不包含具体实现细节。
• 技能主体（SKILL.md 内容） – 第二层：如果 Claude 判断某个技能与当前任务相关，它会进一步读取并加载该技能完整的 SKILL.md 内容作为上下文 。这个 Markdown 文件中包含对任务的详细指令、注意事项、示例等，指导模型如何利用该技能解决问题。
• 附加文件和脚本 – 第三层：对于更复杂或特定的场景，技能文件夹中可以包含脚本（如 .py 工具)或额外说明文档（如参考资料 reference.md 等）。SKILL.md 可以通过 Markdown 链接引用这些文件。当且仅当需要时，Claude 才会加载或运行这些附加内容 。例如，在 PDF 处理技能中，SKILL.md 引用了 forms.md 以提供额外的表单填充指南；Claude 只有在填表任务出现时才读取 forms.md 。又如技能中包含 Python 脚本供执行，当需要复杂计算或访问数据库时，Claude 可以选择运行脚本工具，而无需将脚本代码全部读入上下文 。

借助如上所述的三层结构，Agent Skills 可实现动态的上下文管理。无关任务时，Claude 仅加载技能元数据，几乎不占用上下文窗口；一旦识别出相关技能，再逐步加载详细内容和工具 。这种按需加载机制使技能能够包含海量信息却不怕超出上下文窗口限制，大幅减少了重复prompt 。

SKills 的创建方式如下：1. 在.claude文件夹内创建skills文件夹，里面再创建一个表示技能文件夹
2. 技能文件夹里创建名为SKILL.md的文档，里面写技能名称(name)、技能使用条件(description)和正式的技能用法（prompt）
3. 技能文件夹里还可以创建其他文件夹，里面存各种资料和程序脚本。下面是 Claude 官方给出的让 AI 创建 MCP 服务的技能结构（我翻译成中文了）：1. 根目录下的 SKILL.md文档详细阐述了什么时候、阅读什么文档、运行什哪个脚本
4. reference文件里是各种支持资料文档
5. scripts文件里是各种可以直接运行的 Python 代码程序
6.
Agent Skills 方案：

skill/employees/
├── SKILL.md
└── scripts/
├── execute_sql.py
└── pycache/
借助技能机制，Claude 能够在一次对话中自主规划并执行一系列操作，完成更复杂的闭环。例如，本次以 MySQL 官方示例数据库 employees（员工信息库）为测试数据, 定制agent skills，用于将中文业务问题转换为受控的 SQL 查询并输出结构化分析报告。

☞ Skills 核心运行机制：渐进式披露

Agent Skills 终极指南：入门、精通、预测

这节旨在讲解 Skills 运作的核心机制之一：渐进式披露。

整体更偏技术理解，如果只是想用 or 做 Skill，可以滑到下一部分

正如 有效的 Context 工程 所论证的，上下文过长容易导致模型能力下降。

由于 Skills 的本质就是 Context 工程，所以这个问题也需在 Skill Agent 中注意。

一个完整装载了 Skill 的 Agent 架构是这样的：

图片
Skill 包放在 Agent 文件系统（右侧）中，并非默认全量加载在 Context Window 中。

根据 Context 加载顺序、优先级的不同，Skill 被划分为了 3 种层级：

Skill 内容物的 3 种渐进披露优先级

渐进披露的流程图解

1）Level 1（元数据，始终加载）：

SKILL.md 文档内的元数据，包含名称与用途描述。长度约 100 tokens。

Agent 启动时，就在 Context Window 中加载 Skill 元数据，将其包含在系统提示中。

AI 通过理解用户消息与 Skills 元数据的匹配情况，判断是否需要自动使用技能。

---
name: pdf
description: 全面的 PDF 操作工具包，用于提取文本和表格、创建新 PDF、合并/拆分文档以及处理表单。当 Claude 需要填写 PDF 表单或大规模地程序化处理、生成或分析 PDF 文档时使用。
---

2）Level 2（指令，触发时加载）：

SKILL.md 文档内的正文内容，也就是主要技能指令，一般包含工作流程、最佳实践和指导。

建议少于 5000 tokens。

当用户发出的消息与Skill 元数据的描述匹配，需要调用 Skill 时，Agent 才会用 bash 读取文档正文 。读取时文档内容加载到 Context Window 中。

3）Level 3（子技能指令 / 资源 / 代码，按需动态加载）：

由子技能文档、代码脚本、参考文档、可用资源等文件构成。

也有 Agent Skill 规范文档将它们统称为「Resource」。相对来讲，Level 3 结构要求没那么严谨。

Sub-SKILL.md 子技能文档：相对独立、复杂的子技能指令，单独放在 Level3 拆分加载

Skill 的问题

误解的痛：一位网友重构 Agent Skills 的全过程