Agent Skills

知识库简介

Agent Skills 是一种用文件夹、SKILL.md、脚本和资源为 AI agent 提供可复用专业能力的开放格式。它把“完成一类任务所需的程序性知识”放进可发现、按需加载、可测试的包中。本课程先建立格式、client 与授权边界，再学习触发、渐进式披露、安全和评测；任务开始前已有的 8 篇官方资料保留为参考层。

来源与范围

官方文档索引为 https://agentskills.io/llms.txt，规范与创作指南在 2026-07-22 复核。name 与 description 仍为必填；license、compatibility、metadata 为可选，allowed-tools 仍明确标为实验字段。安装位置、触发实现、工具授权和权限提示仍取决于具体 client；不要把某个产品行为误写成通用规范。尤其是 Skill 的存在、加载或 allowed-tools 字段都不等于用户授权、身份认证或脚本安全。

许可边界于 2026-07-20 重新核验：上游仓库代码使用 Apache-2.0，但 docs/ 目录及网站文档使用 CC BY 4.0。两者不能互换。参考层在公开发布前必须逐页保留 Agent Skills 项目署名、原始链接，并说明中文翻译、整理与格式变更；缺少这些字段时继续只发布来源跳转页。示例 Skill 若单独声明 CC0-1.0，则按该示例自己的声明处理。

在总路线中的位置

它位于“单 Agent 与工具”阶段。掌握 Agent 核心 的任务循环与 Tool Calling 的动作契约后，再把稳定工作流封装为 Skill；需要连接外部工具或数据时，可与 MCP 组合。Skill 不是 Tool Calling、MCP 或权限系统的替代品：它为 agent 提供流程上下文，实际授权仍由 host、工具服务端和业务系统强制。这里描述的是选择本分支后的能力衔接，不表示所有角色都必须先完成这些完整课程；没有可复用流程时可以暂不学习 Agent Skills。

学习目标

• 解释开放格式与具体 agent client 的边界。
• 区分 Skill、常驻指令、Tool Calling、MCP 与实际授权的职责。
• 创建符合规范的目录与 SKILL.md YAML frontmatter。
• 利用 metadata→instructions→resources 三层渐进式披露控制上下文成本。
• 写出既能覆盖真实意图、又不会过度触发的 description。
• 设计无交互、安全默认、结构化输出的脚本，并按需组织 references/assets。
• 对第三方 Skill、资源与更新建立来源、版本、差异审查和隔离试运行边界。
• 用格式校验、触发测试、有/无 Skill 基线和断言迭代质量。

前置知识

• 能读写 Markdown 和简单 YAML frontmatter。
• 会在 PowerShell 7 运行 Python 3 脚本并查看退出码。
• 理解 agent 的上下文窗口、工具调用和“最小权限”概念。
• 不要求先熟悉某个 client；实际安装前再读该 client 的官方文档。

推荐学习顺序

1. 定位、客户端差异与权限边界：先划清格式、工具协议和授权的责任线。
2. 开放格式与目录结构：分清规范核心和 client 自己的实现选择。
3. SKILL.md 前置元数据与渐进式披露：准确写 frontmatter，并把上下文按需拆分。
4. 触发描述与范围边界：用真实正反例校准 description。
5. 脚本、资源与安全：设计可执行资源、供应链审查和最小权限边界。
6. 测试、评测与迭代：比较“有 Skill”和基线，并以证据改进。
7. 项目：创建并验证技能：运行一个不联网的完整示例。

动手实践或项目入口

• 主项目：创建并验证 text-statistics Skill。
• 触发练习：先为你的 Skill 写正反各 8～10 条真实请求，负例优先选择容易误触发的相邻任务；再留出未参与调参的验证集。
• 评测练习：为一个机械可验证结果写断言，并比较不加载 Skill 时的基线。

掌握标准

• 能从零建立含 SKILL.md 的合法目录，并解释 name 必须匹配父目录。
• 能说明目标 client 是如何发现、选择或预加载 Skill 的，而不把渐进式披露当成所有 host 的保证。
• 能写出同时包含“做什么”和“何时使用”的 description，并用近似负例检验范围。
• 能审查脚本的网络、文件、命令、凭据和输出边界，并审阅第三方 Skill 的来源、revision 与更新差异。
• 能解释为什么 Skill、allowed-tools 和 MCP resource 都不构成用户意图或权限证明。
• 能运行本地示例验证器与脚本，理解它们的覆盖范围和局限。
• 能用有 Skill/无 Skill 基线、具体断言和人工复核共同决定是否改版。

与其他知识库的关系

• 提示词工程 关注单次或模板化指令；Skill 将稳定流程、脚本和参考资料打包，并通过描述触发。
• 上下文工程 解释为何要按需加载；渐进式披露是其具体工程应用。
• Tool Calling 定义一次动作的参数、结果与错误契约；Skill 提供何时调用、如何验证和何时停下的流程上下文。
• MCP 暴露工具、资源和 prompts；Skill 可以教 agent 何时、如何安全使用这些能力，但不授予访问权或替代服务端验证。
• 评测体系知识库提供更完整的实验设计、指标与误差分析方法；总库完成后可从主路线进入。

主要参考资料

以下均为第一方来源，获取/复核日期为 2026-07-22：

• Agent Skills Specification
• Agent Skills 官方仓库
• Best practices for skill creators
• Optimizing skill descriptions
• Evaluating skill output quality
• Using scripts in skills
• GitHub Copilot: About agent skills（用于说明 client 行为差异）
• GitHub Copilot: Adding agent skills（用于目录与预授权工具的实现边界）

官方文档参考层

以下文件是任务开始前已有的官方文档中文整理。本轮保留正文、来源信息和分层不改；其中客户端清单和 client 专属操作只代表其抓取快照，实际安装、命令、权限与支持范围须以目标 client 的当前官方文档和本机验证为准。上面的学习路线补充了这一工程边界。

01-概览

• Agent Skills Overview：开放格式的概念、价值和工作方式。
• Specification：目录、frontmatter、资源和校验规则。
• Client Showcase：支持该格式的 client 生态；支持情况会变化。

02-技能创建者

• Quickstart：用最小样例创建第一个 Skill。
• Best practices：从真实经验提炼流程并控制上下文。
• Optimizing descriptions：优化 should-trigger / should-not-trigger 表现。
• Evaluating skills：设计测试、断言、基线和迭代。
• Using scripts：编写 agent 友好的脚本接口。