Hello·World
划水湾
问道台
卷王殿
藏经阁
目录
Skill从入门到出家

第一部分：初识 Skill

第 1 章：什么是 Skill？

在人工智能 Agent 领域，Skill 被定义为一组封装了特定指令、脚本和资源的模块化能力集合 [1]https://agentskills.io/home。这些模块旨在赋予 AI Agent 更高层次的理解与执行能力，使其能够更准确、高效地完成复杂任务。Skill 的核心在于将 Agent 的能力从通用性提升到专业性，使其能够根据具体场景按需加载和运用特定知识与工具。

Skill 的基本构成是一个包含 SKILL.md 文件的文件夹。SKILL.md 文件是 Skill 的核心，它不仅包含了 Skill 的元数据（如名称和描述），还提供了 Agent 执行任务所需的详细指令。此外，Skill 文件夹还可以包含可选的 scripts/ 目录用于存放可执行代码，references/ 目录用于存储参考文档，以及 assets/ 目录用于存放模板和资源 [2]https://agentskills.io/what-are-skills。这种结构使得 Skill 既能提供纯文本指令，也能集成复杂的程序逻辑和辅助材料。

1.1 定义与核心理念

Skill 的核心理念是渐进式披露 (Progressive Disclosure)，这是一种高效管理 Agent 上下文（context）的机制。传统的 AI Agent 在处理任务时，可能需要加载大量的背景知识和工具说明，这不仅会增加计算负担，也可能导致信息过载。渐进式披露机制通过分阶段加载信息，有效解决了这一问题 [2]https://agentskills.io/what-are-skills：

  1. 发现 (Discovery)：在 Agent 启动时，它只会加载所有可用 Skill 的名称和简短描述。这些元数据足以让 Agent 初步判断哪些 Skill 可能与当前任务相关。
  2. 激活 (Activation)：当 Agent 识别到某个任务与特定 Skill 的描述高度匹配时，它会按需加载该 Skill 的完整 SKILL.md 文件，将详细指令纳入其工作上下文。
  3. 执行 (Execution)：Agent 依据 SKILL.md 中的指令执行任务，并根据需要动态加载 scripts/、references/ 或 assets/ 目录中的文件，以完成更具体的子任务或获取额外信息。

这种机制确保了 Agent 仅在必要时才加载相关信息，从而保持了运行的敏捷性，并有效扩展了其处理复杂任务的能力。

1.2 为什么需要 Skill

AI Agent 尽管在通用智能方面取得了显著进展，但在处理特定领域或需要精确操作的实际工作时，往往会面临“上下文不足”的挑战。它们可能缺乏执行特定任务所需的程序性知识 (procedural knowledge)、公司或团队特有的工作流程，以及用户特定的偏好和限制。Skill 的出现正是为了弥补这一鸿沟 [1]https://agentskills.io/home。

通过将这些特定知识和操作流程封装成可复用的 Skill，Agent 能够按需加载这些“专业技能”，从而更可靠地完成实际工作。例如，一个通用的 Agent 可能知道如何“处理文档”，但通过加载一个“PDF 处理 Skill”，它就能掌握提取 PDF 文本、填写表单或合并文件的具体步骤和工具使用方法。这使得 Agent 的能力从模糊的“知道做什么”转变为精确的“知道如何做”。

1.3 Skill 的核心优势

Skill 机制为 AI Agent 带来了多方面的显著优势：

  • 模块化 (Modularity)：Skill 将复杂能力分解为独立的、可管理的模块。每个 Skill 专注于一个特定任务或领域，使得 Agent 的能力可以像乐高积木一样灵活组合和扩展。
  • 可移植性 (Portability)：Skill 本质上是文件和文件夹的集合，这意味着它们可以轻松地在不同的 Agent 产品和平台之间共享、部署和版本控制。Skill 作者只需构建一次能力，即可在多个 Agent 产品中复用 [1]https://agentskills.io/home。
  • 可审计性 (Auditability)：SKILL.md 文件的自文档化特性使得 Skill 的功能和执行逻辑清晰透明。无论是 Skill 作者还是最终用户，都可以通过阅读 SKILL.md 来理解 Skill 的作用，这极大地便利了 Skill 的审查、改进和故障排除。
  • 效率提升 (Efficiency)：渐进式披露机制确保 Agent 仅加载当前任务所需的信息，避免了不必要的上下文开销，从而提高了 Agent 的运行效率和响应速度。
  • 知识沉淀 (Knowledge Capture)：企业和团队可以将组织内部的专业知识、最佳实践和工作流程封装成 Skill，实现知识的标准化和自动化，有效防止知识流失，并加速新成员的上手速度。

第 2 章：Skill 的前世今生

2.1 历史背景

Agent Skills 格式最初由人工智能研究公司 Anthropic 开发 。Anthropic 在 AI 领域以其对 AI 安全和可解释性的关注而闻名，其在 Agent 能力构建方面的探索也自然地融入了这些理念。Skill 的诞生，可以追溯到 Anthropic 致力于解决大型语言模型 (LLM) 在实际应用中面临的挑战，特别是如何让 LLM 能够可靠地执行多步骤、需要外部工具和特定知识的任务 [9]https://medium.com/the-context-layer/anthropic-is-doing-with-agent-skills-what-it-did-with-mcp-7068a15e72da。

在 2025 年 10 月左右，Agent Skills 概念开始在社区中浮现，并于 2025 年 12 月 18 日正式作为开放标准发布。

这一举措旨在推动整个 AI Agent 生态系统的发展，鼓励不同厂商和开发者共同采纳和贡献这一标准，从而实现 Agent 能力的互操作性和标准化。Anthropic 期望通过开放标准，避免 Agent 能力碎片化，促进一个统一、协作的开发环境。

2.2 行业现状：为什么 Skill 成为 AI Agent 领域的重要标准

Skill 之所以迅速成为 AI Agent 领域的重要标准，主要原因在于它提供了一种优雅且实用的解决方案，以应对 Agent 发展的几个关键瓶颈：

  • 弥补通用性与专业性之间的鸿沟：大型语言模型虽然强大，但其通用性使其在面对特定、复杂或需要精确操作的任务时显得力不从心。Skill 允许开发者为 Agent 注入高度专业化的能力，使其能够处理从代码审查到数据分析等各种细分任务 [
  • 解决上下文窗口限制：LLM 的上下文窗口大小始终是一个限制因素。Skill 的渐进式披露机制巧妙地解决了这一问题，Agent 无需一次性加载所有可能的工具和知识，而是在需要时动态加载，极大地扩展了 Agent 的潜在能力范围，同时保持了效率
  • 促进互操作性与生态系统发展：作为一个开放标准，Skill 鼓励不同 AI Agent 产品和平台之间共享和复用能力。这不仅降低了开发成本，也加速了整个 AI Agent 生态系统的成熟。越来越多的主流 AI 开发工具和 Agent 产品开始支持 Agent Skills 格式，例如 VS Code (GitHub Copilot)、Claude Code、OpenAI Codex 等
  • 提升 Agent 的可靠性与可控性：通过结构化的 SKILL.md 文件和明确的指令，Skill 使得 Agent 的行为更具可预测性和可控性。开发者可以精确定义 Agent 在特定情境下的行为逻辑，并通过脚本集成外部工具，从而提高任务执行的可靠性

2.3 Skill 与 MCP 的关系

在理解 Skill 的重要性时，不得不提及 Anthropic 的另一个重要贡献——模型上下文协议 (Model Context Protocol, MCP)。MCP 旨在为 Agent 提供一种标准化的方式来“对话”和“理解”工具，它定义了 Agent 如何与外部工具进行交互的语言和规范

Skill 和 MCP 并非相互替代，而是互补的关系。可以这样理解：

  • MCP 解决了“如何对话”的问题：它提供了一套通用的接口和协议，让 Agent 能够理解工具的输入、输出以及如何调用工具。它关注的是 Agent 与工具之间的通信机制。
  • Skill 解决了“如何做”的问题：它封装了具体的任务逻辑、执行步骤和所需资源，告诉 Agent 在特定场景下应该使用哪些工具、如何组合它们，以及如何解释结果。它关注的是 Agent 的具体行动策略和能力实现。

因此，一个高效的 AI Agent 往往会同时利用 MCP 和 Skill。MCP 提供了 Agent 与工具交互的基础设施，而 Skill 则在此基础上构建了 Agent 的实际“技能树”。Skill 可以利用 MCP 定义的工具接口来调用外部服务或执行脚本，从而实现其内部的复杂逻辑。两者共同构成了 Agent 能够可靠、高效地完成任务的强大支撑体系。

参考文献

第二部分：核心原理与规范

第 3 章：Skill 的技术架构

要精通 Skill，首先需要深入了解其内部的技术架构和规范。Skill 的设计哲学是“简单而强大”，它通过标准化的目录结构和文件格式，实现了高度的灵活性和可扩展性。

3.1 目录结构详解

一个标准的 Skill 本质上是一个目录，其名称即为 Skill 的标识符。在这个目录下，包含了一个必需的核心文件和几个可选的子目录，用于组织不同类型的资源 [3]https://agentskills.io/specification。

目录/文件 状态 描述
SKILL.md 必需 Skill 的核心文件，包含 YAML 格式的元数据和 Markdown 格式的执行指令。
scripts/ 可选 存放可执行脚本（如 Python、Bash、JavaScript 等），用于实现复杂的自动化逻辑。
references/ 可选 存放供 Agent 查阅的参考文档（如 API 文档、领域知识库、表单模板等）。
assets/ 可选 存放静态资源（如配置文件模板、示例图片、数据模式等）。

这种结构清晰地分离了指令、逻辑和数据，使得 Skill 易于维护和扩展。

3.2 渐进式披露机制

如前所述，渐进式披露 (Progressive Disclosure) 是 Skill 高效管理上下文的关键机制。这一机制确保了 Agent 能够在拥有海量 Skill 的情况下，依然保持敏捷的响应速度 [2]https://agentskills.io/what-are-skills。

  1. 发现阶段 (Discovery)：当 Agent 启动或初始化时，它会扫描配置的 Skill 目录。在这个阶段，Agent 仅读取每个 SKILL.md 文件顶部的 YAML 元数据（主要是 name 和 description）。这部分信息通常只有约 100 个 Token，Agent 可以轻松加载成百上千个 Skill 的元数据，而不会耗尽上下文窗口。
  2. 激活阶段 (Activation)：当用户提出请求或 Agent 遇到特定任务时，它会将当前任务的上下文与已加载的 Skill 描述进行匹配。如果发现某个 Skill 的描述高度契合当前任务，Agent 就会“激活”该 Skill，并将 SKILL.md 文件中的完整 Markdown 指令加载到当前上下文中（建议指令长度控制在 5000 Token 以内）。
  3. 执行阶段 (Execution)：在执行指令的过程中，如果 SKILL.md 中引用了 scripts/、references/ 或 assets/ 中的文件，Agent 会根据需要按需加载这些资源。例如，只有当指令明确要求运行某个 Python 脚本时，Agent 才会去读取并执行该脚本。

通过这种分层加载策略，Skill 机制在“能力广度”和“上下文效率”之间取得了完美的平衡。

3.3 运行环境与兼容性

为了确保 Skill 能够在不同的 Agent 产品和操作系统中稳定运行，Skill 规范提供了一些机制来处理环境依赖和兼容性问题。

在 SKILL.md 的元数据中，可以使用可选的 compatibility 字段来声明 Skill 的运行要求 [3]https://agentskills.io/specification。例如：

yaml
复制代码 
compatibility: Requires Python 3.14+ and uv

或者：

yaml
复制代码 
compatibility: Requires git, docker, jq, and access to the internet

这允许 Agent 在尝试执行 Skill 之前，预先检查环境是否满足条件。然而，最佳实践是尽量让 Skill 保持独立和自包含，减少对特定环境的硬性依赖。例如，在编写脚本时，推荐使用支持内联依赖声明的工具（如 Python 的 uv 或 Node.js 的 npx），这样 Agent 可以在运行时自动解决依赖，而无需用户手动配置环境 [6]https://agentskills.io/skill-creation/using-scripts。

第 4 章：编写你的第一个 Skill

理论结合实践是掌握 Skill 的最佳途径。本章将通过一个简单的“掷骰子 (Roll Dice)”案例，带你从零开始编写并运行你的第一个 Skill [5]https://agentskills.io/skill-creation/quickstart。

4.1 快速上手：掷骰子 Skill

假设我们希望赋予 Agent 一个新能力：当用户要求“掷骰子”时，Agent 能够生成一个指定面数的随机数。

步骤 1：创建目录结构

在你的项目或 Agent 配置的 Skill 目录下（例如 .agents/skills/），创建一个名为 roll-dice 的文件夹。

步骤 2：编写 SKILL.md

在 roll-dice 文件夹中，创建一个 SKILL.md 文件，并输入以下内容：

markdown
复制代码 
---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use the following command that generates a random number from 1
to the given number of sides:

```bash
echo $((RANDOM % <sides> + 1))
plaintext
复制代码 
Get-Random -Minimum 1 -Maximum (<sides> + 1)

Replace <sides> with the number of sides on the die (e.g., 6 for a standarddie, 20 for a d20).

步骤 3：测试运行

如果你使用的是支持 Skill 的平台（如配置了 GitHub Copilot 的 VS Code），你可以打开 Agent 聊天面板，输入 /skills 确认 roll-dice 已被加载。然后向 Agent 提问：“Roll a d20”。

Agent 会匹配到 roll-dice 的描述，加载指令，并尝试运行相应的 Bash 或 PowerShell 命令（将 <sides> 替换为 20），最终返回一个 1 到 20 之间的随机数。

4.2 SKILL.md 规范详解

SKILL.md 文件由两部分组成：顶部的 YAML 元数据（Frontmatter）和随后的 Markdown 主体内容 [3]https://agentskills.io/specification。

YAML 元数据 (Frontmatter)

元数据必须位于文件的最顶部，并用 --- 包围。

  • name (必需)：Skill 的唯一标识符。必须是 1-64 个字符，仅包含小写字母、数字和连字符（-），且必须与所在的文件夹名称完全一致。
  • description (必需)：描述 Skill 的功能以及何时应该使用它。这是 Agent 决定是否激活该 Skill 的关键依据。描述应包含具体的关键词（如上例中的 "d6", "d20", "random dice roll"）。长度限制为 1-1024 个字符。
  • license (可选)：声明 Skill 的开源协议（如 Apache-2.0）。
  • compatibility (可选)：声明运行环境要求。
  • metadata (可选)：键值对形式的自定义元数据，供特定客户端使用（如作者信息、版本号）。
  • allowed-tools (可选，实验性)：预先批准 Agent 运行的工具列表。

Markdown 主体内容

元数据下方是 Markdown 格式的指令主体。这里没有严格的格式限制，你可以自由编写任何有助于 Agent 完成任务的内容。推荐包含以下部分：

  • 使用场景说明：进一步明确何时触发此 Skill。
  • 分步执行指南：清晰、逻辑严密的操作步骤。
  • 输入输出示例：提供具体的例子，帮助 Agent 理解期望的数据格式。
  • 边缘情况处理：指导 Agent 在遇到错误或异常输入时该如何应对。

4.3 编写高质量指令的技巧

编写 Skill 指令就像是在给一个极其聪明但缺乏常识的实习生写操作手册。以下是一些提高指令质量的技巧：

  1. 清晰明确：避免模棱两可的表述。使用祈使句（如“使用 pdfplumber 提取文本”），而不是描述性语句。
  2. 结构化：充分利用 Markdown 的标题、列表和代码块来组织信息，使其易于 Agent 解析。
  3. 提供上下文：如果任务涉及特定的业务逻辑或术语，请在指令中简要解释。
  4. 控制长度：尽量将 SKILL.md 的主体内容控制在 500 行以内。如果指令过于复杂，应考虑将其拆分为多个脚本，或将详细的背景知识移至 references/ 目录中的独立文件 [3]https://agentskills.io/specification。

第三部分：进阶实战

第 5 章：脚本化与自动化

Skill 的强大之处不仅在于其能够提供清晰的文本指令，更在于它能够无缝集成可执行脚本，从而将 Agent 的能力从简单的信息处理扩展到复杂的自动化任务。通过脚本，Agent 可以调用外部工具、执行复杂的计算逻辑、与操作系统交互，甚至实现跨系统的自动化工作流。

5.1 在 Skill 中使用脚本

Skill 允许在 scripts/ 目录下存放各种可执行脚本，例如 Python 脚本 (.py)、Bash 脚本 (.sh)、JavaScript 脚本 (.js) 等。Agent 可以根据 SKILL.md 中的指令来执行这些脚本 [6]https://agentskills.io/skill-creation/using-scripts。

引用脚本的两种方式：

  1. 一次性命令 (One-off commands)：对于简单的、已存在于 Agent 环境中的命令行工具，可以直接在 SKILL.md 中引用。例如：

    要检查代码格式，请运行：

    bash
    复制代码 
    uvx ruff@0.8.0 check .

这种方式适用于调用那些 Agent 环境已预装的工具，并且命令本身不复杂的情况。为了确保命令行为的一致性，建议锁定工具版本（如 ruff@0.8.0）[6]https://agentskills.io/skill-creation/using-scripts。

  1. 引用 scripts/ 目录下的脚本：对于更复杂的逻辑或需要特定依赖的脚本，应将其放置在 scripts/ 目录下，并在 SKILL.md 中通过相对路径引用。例如：

    markdown
    复制代码 
    ## 可用脚本

- **`scripts/validate.sh`** — 验证配置文件
- **`scripts/process.py`** — 处理输入数据

## 工作流

1. 运行验证脚本：
   bash scripts/validate.sh "$INPUT_FILE"
2. 处理结果：
    python3 scripts/process.py --input results.json

Agent 会从 Skill 目录的根路径执行这些命令，因此脚本路径必须是相对于 Skill 根目录的相对路径 [6]。

5.2 脚本设计原则：为 Agent 优化

Agent 在执行脚本时，会读取脚本的标准输出 (stdout) 和标准错误 (stderr) 来判断执行结果和下一步行动。因此，为 Agent 设计脚本需要遵循一些特定的原则，以确保 Agent 能够高效、可靠地利用脚本 [6]https://agentskills.io/skill-creation/using-scripts：

  1. 避免交互式提示：Agent 在非交互式 Shell 环境中运行，无法响应 TTY 提示、密码对话框或确认菜单。任何需要交互式输入的脚本都会导致 Agent 挂起。所有输入都应通过命令行参数、环境变量或标准输入 (stdin) 提供。

    bash
    复制代码 
    # 错误示例：Agent 会挂起等待输入
$ python scripts/deploy.py
Target environment: _

# 正确示例：通过命令行参数提供输入
$ python scripts/deploy.py --env staging --tag v1.2.3

  2. 提供 --help 文档：--help 输出是 Agent 了解脚本接口的主要方式。脚本应包含简洁的描述、可用参数和使用示例。这部分内容会进入 Agent 的上下文窗口，因此应保持精炼。

    bash
    复制代码 
    Usage: scripts/process.py [OPTIONS] INPUT_FILE

Process input data and produce a summary report.

Options:
  --format FORMAT    Output format: json, csv, table (default: json)
  --output FILE      Write output to FILE instead of stdout
  --verbose          Print progress to stderr

  3. 编写有帮助的错误信息：当脚本出错时，清晰的错误信息能直接指导 Agent 进行下一步尝试。错误信息应说明哪里出了问题、预期是什么以及可以尝试的解决方案，而不是模糊的“错误：无效输入”。

    bash
    复制代码 
    Error: --format must be one of: json, csv, table.
       Received: "xml"

  4. 使用结构化输出：优先使用 JSON、CSV、TSV 等结构化格式输出结果，而不是自由文本。结构化数据更容易被 Agent 和其他工具（如 jq、awk）解析和处理，从而提高脚本的可组合性。

    json
    复制代码 
    {"name": "my-service", "status": "running", "created": "2025-01-15"}

    数据与诊断信息分离：将结构化数据发送到标准输出 (stdout)，将进度消息、警告和诊断信息发送到标准错误 (stderr)。这样 Agent 可以捕获干净、可解析的输出，同时在需要时仍能访问诊断信息。

5.3 依赖管理：自包含脚本

为了让脚本更具可移植性和鲁棒性，推荐使用自包含脚本（Self-contained scripts）的方式来管理依赖。这意味着脚本本身就声明了其所需的依赖，Agent 可以在运行时自动解决这些依赖，而无需额外的配置文件或安装步骤 [6]https://agentskills.io/skill-creation/using-scripts。

许多语言都支持内联依赖声明，例如 Python 的 PEP 723 规范。通过在脚本头部添加特定的注释块，可以声明 Python 包依赖：

scripts/extract.py

python
复制代码 
# /// script
# dependencies = [
#   "beautifulsoup4",
# ]
# ///

from bs4 import BeautifulSoup

html = '<html><body><h1>Welcome</h1><p class="info">This is a test.</p></body></html>'
print(BeautifulSoup(html, "html.parser").select_one("p.info").get_text())

然后，Agent 可以使用 uv run 或 pipx run 等工具来执行这些脚本。这些工具会自动创建一个隔离的环境，安装声明的依赖，然后运行脚本，确保了脚本在不同环境中的一致性 [6]https://agentskills.io/skill-creation/using-scripts。

第 6 章：复杂工作流与领域专家

Skill 的真正价值在于其能够封装复杂的业务逻辑和领域专业知识，将多步骤任务转化为可重复、可审计的工作流。本章将通过几个案例分析，展示如何利用 Skill 构建处理复杂工作流和领域专家知识的 Agent 能力。

6.1 案例分析：PDF 处理 Skill

设想一个需要频繁处理 PDF 文件的场景，例如从 PDF 中提取文本和表格、填写 PDF 表单或合并多个 PDF 文件。这些任务通常需要特定的库和工具。我们可以创建一个 pdf-processing Skill 来封装这些能力。

Skill 结构示例：

plaintext
复制代码 
pdf-processing/
├── SKILL.md
├── scripts/
│   ├── extract_text.py
│   ├── fill_form.py
│   └── merge_pdfs.py
└── references/
    └── pdf_schema.md

SKILL.md** 示例片段：**

markdown
复制代码 
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---

# PDF 处理

## 何时使用此 Skill
当用户需要从 PDF 文件中提取信息、填写表单或合并多个 PDF 时，请使用此 Skill。

## 提取文本和表格
要从 PDF 中提取文本和表格，请运行 `scripts/extract_text.py` 脚本。该脚本接受 PDF 文件路径作为输入，并输出 JSON 格式的提取结果。

```bash
python scripts/extract_text.py <pdf_file_path>

填写 PDF 表单

要填写 PDF 表单，请使用 scripts/fill_form.py 脚本。该脚本需要 PDF 模板路径和包含表单数据的 JSON 文件路径。

bash
复制代码 
python scripts/fill_form.py <template_pdf_path> <data_json_path>

合并多个 PDF

要合并多个 PDF 文件，请运行 scripts/merge_pdfs.py 脚本。该脚本接受一个包含所有待合并 PDF 路径的列表，并输出合并后的 PDF 文件。

bash
复制代码 
python scripts/merge_pdfs.py <pdf_list_json_path>

有关 PDF 结构和表单字段的详细信息，请参阅 references/pdf_schema.md。

plaintext
复制代码 

在这个案例中，`SKILL.md` 提供了高层次的指令，而具体的 PDF 操作逻辑则由 Python 脚本实现。`references/pdf_schema.md` 则可以提供关于 PDF 结构或表单字段的详细说明，供 Agent 在需要时查阅。Agent 可以根据用户的请求，选择性地调用这些脚本和参考资料，从而完成复杂的 PDF 处理任务。

#### 6.2 案例分析：代码审查 Skill

代码审查是一个高度依赖领域知识和最佳实践的任务。我们可以创建一个 `code-review` Skill 来封装特定编程语言或框架的代码审查规则。

**Skill 结构示例：**
code-review/
├── SKILL.md
├── scripts/
│ 
├── lint_python.py
│ └── check_security.sh
└── references/
├── python_best_practices.md
└── security_guidelines.md
plaintext
复制代码 

**`SKILL.md` 示例片段：**

```markdown
---
name: code-review
description: Perform code review based on best practices and security guidelines. Use when asked to review code or check code quality.
---

# 代码审查

## 何时使用此 Skill
当用户需要对代码进行审查、检查代码质量、发现潜在错误或安全漏洞时，请使用此 Skill。

## Python 代码审查
对于 Python 代码，请运行 `scripts/lint_python.py` 脚本进行静态代码分析和风格检查。该脚本将输出所有发现的问题。

```bash
python scripts/lint_python.py <python_file_path>

安全漏洞检查

要检查代码中的常见安全漏洞，请运行 scripts/check_security.sh 脚本。该脚本将对代码库进行扫描，并报告潜在的安全风险。

bash
复制代码 
bash scripts/check_security.sh <code_base_path>

有关 Python 编程的最佳实践，请参阅 references/python_best_practices.md。有关安全编码指南，请查阅 references/security_guidelines.md。

plaintext
复制代码 

这个 Skill 将代码审查的复杂性抽象化，Agent 只需要知道何时调用哪个脚本，以及如何解读脚本的输出。通过更新 `references/` 目录中的文档，可以轻松地更新审查规则，而无需修改 Agent 的核心逻辑。

#### 6.3 案例分析：数据分析流水线

数据分析往往涉及多个步骤，包括数据清洗、转换、分析和可视化。一个 `data-analysis` Skill 可以将这些步骤组织成一个可重复的流水线。

**Skill 结构示例：**

data-analysis/
├── SKILL.md
├── scripts/
│ 
├── clean_data.py
│ 
├── analyze_data.py
│ └── visualize_results.py
└── assets/
└── report_template.md
plaintext
复制代码 

**`SKILL.md` 示例片段：**

```markdown
---
name: data-analysis
description: Perform data cleaning, analysis, and visualization. Use when asked to analyze datasets or generate reports.
---

# 数据分析流水线

## 何时使用此 Skill
当用户提供数据集并要求进行分析、生成报告或可视化结果时，请使用此 Skill。

## 步骤 1：数据清洗
首先，运行 `scripts/clean_data.py` 脚本对原始数据进行清洗。该脚本接受原始数据文件路径作为输入，并输出清洗后的数据文件。

```bash
python scripts/clean_data.py --input <raw_data_path> --output <cleaned_data_path>

步骤 2：数据分析

接下来，使用 scripts/analyze_data.py 脚本对清洗后的数据进行统计分析。该脚本将生成关键指标和洞察。

bash
复制代码 
python scripts/analyze_data.py --input <cleaned_data_path> --output <analysis_results_json_path>

步骤 3：结果可视化与报告生成

最后，运行 scripts/visualize_results.py 脚本，根据分析结果生成图表，并结合 assets/report_template.md 模板生成最终报告。

bash
复制代码 
python scripts/visualize_results.py --data <analysis_results_json_path> --template assets/report_template.md --output <final_report_md_path>

这个 Skill 将整个数据分析流程封装起来，Agent 只需要按照 SKILL.md 中定义的步骤依次调用脚本即可。这不仅确保了分析过程的一致性，也使得 Agent 能够处理更复杂、多阶段的数据任务。

第四部分：多平台应用与生态

Skill 作为一种开放标准，其设计目标之一就是实现跨平台和跨 Agent 的互操作性。这意味着一个 Skill 可以在不同的 AI Agent 产品和开发环境中被发现、激活和执行。本章将探讨 Skill 在主流平台上的应用，并介绍一些最佳实践和评估方法。

第 7 章：主流平台使用指南

随着 Agent Skills 开放标准的推广，越来越多的 AI Agent 产品和开发工具开始原生支持或通过插件支持 Skill。以下是一些主流平台上的应用示例 [4]https://agentskills.io/clients：

7.1 VS Code (GitHub Copilot)

Visual Studio Code (VS Code) 是开发者最常用的代码编辑器之一，而 GitHub Copilot 则是其强大的 AI 编程助手。在配置了 GitHub Copilot 的 VS Code 环境中，Agent Skills 可以被无缝集成，极大地增强了开发者的工作效率。

配置与使用：

  1. Skill 目录：VS Code 通常会在项目根目录下的 .agents/skills/ 路径中查找 Skill。开发者只需将 Skill 文件夹放置在此目录下，Copilot Agent 即可自动发现。
  2. Copilot Chat：在 VS Code 的 Copilot Chat 面板中，用户可以通过自然语言与 Agent 交互。当用户的请求与某个 Skill 的 description 匹配时，Copilot Agent 会激活该 Skill，并根据 SKILL.md 中的指令执行任务。
  3. 示例：在“掷骰子 Skill”的案例中，当用户在 Copilot Chat 中输入“Roll a d20”时，Copilot Agent 会识别并调用 roll-dice Skill，执行其中的 Bash 命令，并将结果返回给用户。

这种集成方式使得开发者可以在熟悉的 IDE 环境中，通过自然语言调用复杂的自动化任务，极大地提升了开发体验。

7.2 Claude Code

Claude Code 是 Anthropic 推出的一款 Agentic 编码工具，它能够理解代码库、编辑文件、运行命令，并与开发工具集成。作为 Skill 开放标准的提出者，Claude Code 对 Skill 的支持自然是其核心功能之一。

终端 Agent 的 Skill 应用：

Claude Code 通常以终端应用的形式运行，它能够通过命令行界面与用户交互。当用户在终端中向 Claude Code 提出编码相关的请求时，Claude Code Agent 会利用其内置的 Skill 支持来完成任务。

例如，如果有一个 refactor-code Skill，当用户要求“重构这段代码以提高可读性”时，Claude Code Agent 会激活该 Skill，并执行其中定义的重构脚本或遵循重构指南，最终修改代码文件并向用户展示结果。

7.3 Cursor 与 Trae：AI IDE 中的 Skill 实践

Cursor 和 Trae 是新兴的 AI 驱动的集成开发环境 (IDE)，它们将 AI Agent 的能力深度融入到编码工作流中。在这些 AI IDE 中，Skill 的应用场景更加广泛和深入。

AI IDE 中的 Skill 实践：

  • 代码理解与生成：Skill 可以封装特定语言或框架的代码生成模板和最佳实践，帮助 Agent 更准确地生成符合规范的代码。
  • Bug 修复与测试：通过 Skill，Agent 可以执行自动化测试、分析错误日志，并根据预定义的修复策略尝试修复 Bug。
  • 项目管理与协作：Skill 甚至可以用于自动化项目中的重复性任务，如生成文档、更新任务状态或与版本控制系统交互。

在这些 AI IDE 中，Skill 不仅仅是工具的调用，更是 Agent 能够“思考”和“行动”的知识库和行动指南。

7.4 其他平台

除了上述平台，还有许多其他 AI Agent 产品和框架也正在积极采纳或支持 Agent Skills 标准，例如：

  • nanobot：一个轻量级的开源个人 AI Agent，支持 MCP 和 Skill 系统，可在多种平台（终端、Telegram、Discord、Slack、微信等）上运行。
  • OpenAI Codex：OpenAI 的编码 Agent，也支持通过 Skill 扩展其能力。
  • Google AI Edge Gallery：用于在移动设备上运行大型语言模型，未来也可能集成 Skill 以增强本地 Agent 的能力。

这种广泛的采纳表明，Skill 正在成为 AI Agent 领域事实上的标准，为 Agent 能力的互操作性和生态系统的繁荣奠定了基础。

第 8 章：最佳实践与评估

编写高效、可靠的 Skill 不仅仅是遵循规范，更需要掌握一系列最佳实践，并建立有效的评估机制。本章将提供一些指导原则，帮助你创建高质量的 Skill。

8.1 优化 Skill 描述：提高激活准确率

Skill 的 description 字段是 Agent 决定是否激活该 Skill 的首要依据。一个清晰、准确且包含关键词的描述至关重要 [3]https://agentskills.io/specification。

最佳实践：

  • 明确功能与用途：描述应清晰地说明 Skill 的作用以及何时应该使用它。
  • 包含关键词：思考用户在请求相关任务时可能使用的词汇，并将这些关键词融入描述中。例如，一个处理 PDF 的 Skill 应该包含“PDF”、“文档”、“表单”等关键词。
  • 避免模糊表述：避免使用过于宽泛或模糊的描述，如“帮助处理文件”。这会导致 Agent 难以准确判断何时激活。
  • 测试与迭代：通过实际测试，观察 Agent 在不同用户请求下的激活行为，并根据反馈不断优化描述。

示例：

  • 好的描述：description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
  • 差的描述：description: Helps with PDFs.

8.2 评估与调试：如何测试你的 Skill

Skill 的有效性需要通过严格的测试来验证。这包括确保 Skill 能够被正确激活，指令能够被 Agent 准确执行，以及脚本能够按预期工作。

测试方法：

  1. 手动测试：在支持 Skill 的 Agent 客户端中，通过输入不同的用户请求来测试 Skill 的激活和执行情况。观察 Agent 的响应，检查是否按预期调用了 Skill。

  2. 单元测试 (针对脚本)：为 scripts/ 目录下的脚本编写单元测试，确保其在独立运行时能够正确处理输入并产生预期输出。这有助于隔离和调试脚本逻辑。

  3. 集成测试 (针对 Skill 整体)：模拟 Agent 的行为，编写测试用例来验证 Skill 的端到端流程，包括激活、指令解析和脚本执行。

  4. 使用 skills-ref 工具：skills-ref 是一个官方提供的参考库，可以用于验证 SKILL.md 文件的格式是否符合规范，并检查命名约定等 [3]https://agentskills.io/specification。

    bash
    复制代码 
    skills-ref validate ./my-skill

8.3 安全性与合规性：脚本执行的安全边界

由于 Skill 允许 Agent 执行脚本，因此安全性是一个不容忽视的重要方面。恶意或存在漏洞的脚本可能会对系统造成损害。

安全实践：

  • 最小权限原则：确保 Agent 在执行脚本时，只拥有完成任务所需的最小权限。避免以 root 或高权限用户运行 Agent。
  • 代码审查：对所有 Skill 中的脚本进行严格的代码审查，特别是来自外部或不受信任来源的 Skill。
  • 沙箱环境：在隔离的沙箱环境中运行 Agent 和 Skill，以限制潜在的损害范围。
  • allowed-tools 字段：在 SKILL.md 的元数据中，可以使用 allowed-tools 字段来明确声明 Skill 允许调用的外部工具。这为 Agent 提供了额外的安全控制层 [3]https://agentskills.io/specification。
  • 输入验证：脚本应严格验证所有输入，防止命令注入等安全漏洞。
  • 版本控制：对 Skill 进行版本控制，确保可以追溯和回滚任何更改。

通过实施这些安全措施，可以最大限度地降低 Skill 带来的安全风险，确保 Agent 在执行自动化任务时的可靠性和安全性。

附录

A. 常用资源与链接

B. Skill 验证工具使用指南

skills-ref 工具是 Agent Skills 生态系统中的一个重要组成部分，它提供了一套命令行工具，用于验证 Skill 的格式是否符合规范，并可以生成用于 Agent 交互的提示 XML。以下是其基本使用方法：

  1. 安装 skills-ref：

    bash
    复制代码 
    pip install skills-ref

  2. 验证 Skill：
    要验证一个 Skill 目录（例如 my-skill）是否符合 Agent Skills 规范，可以运行：

    bash
    复制代码 
    skills-ref validate ./my-skill

    如果 Skill 存在任何格式错误或不符合命名约定，该命令将报告详细的错误信息。

  3. 生成提示 XML (Prompt XML)：
    skills-ref 还可以根据 SKILL.md 文件生成提示 XML，Agent 可以使用这些 XML 来更好地理解和调用 Skill。

    bash
    复制代码 
    skills-ref generate-prompt-xml ./my-skill

    生成的 XML 包含了 Skill 的元数据和指令，以 Agent 更易于解析的结构呈现。

C. 常见问题解答 (FAQ)

Q1: Skill 和传统工具（如函数调用）有什么区别？

A1: Skill 提供了一种更结构化、自文档化且可移植的方式来封装 Agent 的能力。与简单的函数调用相比，Skill 不仅包含执行逻辑，还包含了何时使用、如何使用以及相关背景知识的详细指令。它更侧重于 Agent 的自主决策和复杂任务的编排，而不仅仅是工具的调用。

Q2: 我可以将现有的脚本直接转换为 Skill 吗？

A2: 可以。将现有脚本集成到 Skill 中通常只需要将其放置在 scripts/ 目录下，并在 SKILL.md 中提供相应的指令和描述。但为了最大化 Skill 的效果，建议按照本手册中“脚本设计原则”进行优化，例如避免交互式提示、提供 --help 文档和结构化输出。

Q3: Skill 的安全性如何保障？

A3: Skill 的安全性需要多方面保障。首先，对 Skill 及其脚本进行严格的代码审查至关重要。其次，在沙箱环境中运行 Agent 和 Skill 可以限制潜在的损害。此外，SKILL.md 中的 allowed-tools 字段可以提供额外的安全控制，限制 Skill 能够调用的外部工具。遵循最小权限原则也是关键。

Q4: 如何让我的 Skill 更容易被 Agent 发现和激活？

A4: 优化 SKILL.md 中的 description 字段是关键。确保描述清晰、准确，并包含用户在请求相关任务时可能使用的关键词。通过实际测试和迭代，不断改进描述，以提高激活的准确率。

Q5: Skill 的未来发展方向是什么？

A5: Skill 的未来将继续朝着更标准化、更智能、更安全的 Agent 能力封装方向发展。随着 AI Agent 技术的成熟，Skill 可能会集成更高级的验证机制、更丰富的元数据标准，以及更强大的跨 Agent 协作能力。它将成为构建高度自主、可信赖 AI Agent 的基石。

"我视别人的钱财如粪土，但你的就不一样啦！"
本文由 程序员拉大锯 原创发布于 阳光沙滩 ， 未经作者授权，禁止转载
评论
0 / 1024
推荐文章
面向 Java 程序员的 MinIO 入门教程
本文为Java程序员提供了一份详细的MinIO入门教程，涵盖MinIO的部署方法和Java SDK的集成使用。通过本文，您将学习如何在Java项目中高效管理桶和对象，快速上手MinIO这一高性能对象存储服务。
拉大锯围观点赞
你知道：气和汽的区别吗？
了解‘气’和‘汽’的区别，掌握它们在不同语境下的含义与用法，帮助你更准确地使用中文。无论是日常交流还是写作，这对提升语言能力都大有裨益。
拉大锯围观1
wsl update 下载不下来怎么办呀？
遇到Docker Desktop提示需要更新但无法解决？本文教你如何通过GitHub下载并安装WSL，轻松解决更新问题，适合使用x64芯片的用户。
拉大锯围观点赞
今日经验：重置虚拟机的密码
本文详细记录了在KVM虚拟化环境中，如何通过virt-rescue工具重置遗忘的root密码。对于需要维护和管理虚拟机的IT人员来说，这是一份实用的排障指南，涵盖了从环境准备到密码修改的完整流程，帮助快速恢复系统访问权限。
拉大锯围观点赞
今日工作：Android Health Connect 接入记录
本文详细讲解了如何将 Android Health Connect 接入到健康或运动类应用中，涵盖从配置、代码实现到测试验收的完整流程。适合希望统一健康数据管理、提升用户隐私合规性的开发者阅读。
拉大锯围观点赞
Skill从入门到出家
探索AI Agent的核心能力——Skill，了解其模块化设计、渐进式披露机制和实际应用场景。从基础概念到高级实战，掌握如何构建可复用、可移植的AI技能，提升Agent处理复杂任务的能力。
拉大锯围观1
Docker,Docker Compose,kubectl最近遇到的版本问题
本文分享了在使用Docker、Docker Compose和kubectl时遇到的版本问题及解决方法，适合需要更新或管理Linux系统中相关工具的开发者参考。
拉大锯围观点赞
Google上架App退回
Google Play Console 抛出 16KB 内存页面大小合规性错误，导致应用无法上架。本文详细分析了错误原因，并提供了解决方案，帮助开发者适配 Android 15 的新要求。
拉大锯围观点赞
国内常用的 npm 镜像源整理
在使用 npm 安装依赖时，国内开发者常常遇到速度慢的问题。本文整理了多个稳定且常用的国内 npm 镜像源，帮助提升依赖安装效率。还介绍了如何通过 nrm 工具快速切换镜像，非常适合需要优化开发环境的开发者。
TrillGates围观点赞
列表项排序设计：分数索引思想与实践
本文介绍了分数索引思想在列表排序中的应用，通过实数轴上的插空方式实现高效插入与拖拽排序。适用于课程章节、导航菜单、看板列等多种场景，提供创建和更新时的业务规则及边界处理策略，帮助开发者优化排序性能并提升用户体验。
拉大锯围观点赞
2026苹果电脑芯片的性能排行榜
了解2026年前后苹果电脑芯片的性能排名和关键变化，帮助你更好地选择适合自己的设备。从M1到M5，每一款芯片都有其独特优势，无论是日常办公还是专业需求都能找到合适的推荐。
拉大锯围观点赞
在 KVM 上部署 Ubuntu 24.04 Server：企业级虚拟化完整实践指南
本文详细介绍了如何在 KVM 上部署 Ubuntu 24.04 Server，涵盖系统架构、部署步骤、核心命令解析和性能优化等内容。适合希望构建高性能、低成本企业虚拟化平台的技术人员阅读。
拉大锯围观点赞
旧版本的kubesphere还能用的
本文介绍了如何使用KubeSphere配置和部署一个Kubernetes集群，包括修改配置文件、设置环境变量以及执行安装命令。适合需要了解Kubernetes集群搭建的开发者和系统管理员阅读。
拉大锯围观点赞
Flutter Fragment 嵌入模式下返回键/侧滑直接退出应用-日常记录
在 Flutter 混合开发中，如何解决 Android 返回键无法正确触发 Flutter 页面返回逻辑的问题？本文详细解析了事件传递机制，并提供完整解决方案，包括 Android 和 Flutter 层的配置方式。适合开发者快速排查和修复类似问题。
拉大锯围观点赞
记录一个问题，Post请求变Get请求了？原因很简单
本文讲述了一个关于HTTP请求方法被错误转换的问题，通过分析Nginx配置和日志，最终发现是由于301重定向导致POST请求变成GET请求。作者详细描述了问题排查过程，并给出了解决方案，对于开发人员在处理类似网络问题时具有参考价值。
拉大锯围观点赞
Android 进阶：在非 ComponentActivity 中实现协程自动取消
本文深入探讨了在 Android 开发中如何为非 ComponentActivity 的类实现 LifecycleOwner 功能，分享了两种优雅的解决方案。通过手动注册和 Kotlin 属性委托的方式，确保协程能随 Activity 销毁而自动取消，提升代码健壮性。适合对 Android 生命周期管理和协程使用感兴趣的开发者阅读。
A lonely cat围观1
Uni-app 发送通知全解析（从本地通知到推送服务实战）
深入了解Uni-app中通知的四种类型及应用场景，掌握跨平台支持情况和代码实战技巧。从基础提示到高级推送架构设计，全面解析如何提升用户活跃度和业务触达能力，适合开发者系统学习与实践。
拉大锯围观1
MQTT 学习指南：从入门到工程实践
深入解析MQTT在物联网中的核心作用，了解其轻量、稳定和省流量的特性。从发布/订阅模型到QoS机制，全面掌握MQTT的通信原理与应用场景，助你高效构建物联网系统。
拉大锯围观2
深入理解 Java NIO：非阻塞 I/O 的原理、应用与案例实战
本文深入解析 Java NIO 的核心概念，包括 Buffer、Channel 和 Selector，对比传统 I/O 的优势，并通过实战案例展示如何构建高并发的聊天服务器。适合希望提升 Java 网络编程能力的开发者阅读。
TrillGates围观1
二次函数全攻略：公式、图像、性质与应用
二次函数是数学中的核心内容，广泛应用于物理、经济和工程领域。本文系统讲解其定义、图像、性质及实际应用，通过案例帮助理解，适合学生和数学爱好者深入学习。
TrillGates围观1
Java排序算法全解析：从冒泡到快速排序，案例实操
掌握Java中常见排序算法的实现方法，理解其时间复杂度和适用场景，提升编程能力。从冒泡排序到快速排序，全面解析各种排序技术，帮助你高效解决问题。
TrillGates围观2
Java 面试算法题全解析：案例、讲解与面试频率分析
Java面试中，算法题是必考内容。掌握常见算法不仅能提升编程能力，还能提高通过率。本文详细讲解了两数之和、链表反转、二分查找等经典算法题的解题思路与实现代码，帮助你更有针对性地准备面试。
TrillGates围观点赞
Java基础语法入门：跟着案例一步步学会
掌握Java基础语法，从零开始学习编程。本文通过实战案例，详细讲解程序结构、变量、运算符、条件语句、循环、数组和方法等核心内容，适合初学者系统学习。通过练习提升编程能力，为进阶开发打下坚实基础。
TrillGates围观1
Java 多线程入门：从概念到实战（初学者必看）
掌握多线程编程，提升程序效率和响应速度。本文从基础概念到实战案例，一步步讲解如何在 Java 中实现多线程，帮助你快速上手并理解核心知识点。通过实际代码示例，了解线程的生命周期、常用方法及线程安全问题，适合初学者和进阶者学习参考。
TrillGates围观点赞
Java 多线程入门：从概念到实战（初学者必看）
掌握多线程编程，提升程序效率与响应速度。本文从基础概念到实战案例，详细讲解Java多线程的实现方式、注意事项和线程安全问题，适合初学者快速上手。通过实例代码，帮助你理解如何高效编写多线程程序。
围观点赞
Flutter开发网路库封装示例
本教程详细介绍了如何在 Flutter 项目中通过 Dio 库封装网络请求，提供了一套完整的封装类及使用示例，适用于构建中大型项目。内容覆盖依赖引入、封装方法实现、使用场景演示以及扩展功能建议，帮助开发者快速提升代码复用性和可维护性。无论是初学者还是有经验的开发者，都能从中受益。
拉大锯围观点赞
写完这些案例，就掌握flutter开发了。
学习如何在Flutter中实现输入框的实时显示、页面跳转与数据传递，以及动态列表的展示和网络请求数据的解析与展示。通过这些基础案例，掌握Flutter的核心功能，为构建复杂应用打下坚实基础。
拉大锯围观点赞
Flutter学习路线
想要掌握Flutter开发？这篇详细的学习路线图将帮助你从零开始，逐步成长为Flutter开发者。覆盖基础入门、核心概念、进阶开发以及发布优化四个阶段，结合理论与实践，让你轻松掌握Flutter技能。无论是想开发手机应用还是探索跨平台开发，这份指南都能满足你的需求。立即行动，开启你的Flutter之旅吧！
拉大锯围观点赞
什么是MCP? Monte Carlo Planning（蒙特卡洛规划）
MCP（Monte Carlo Planning，蒙特卡洛规划）是强化学习和决策系统中的重要方法，广泛应用于复杂环境下的行动策略规划。无论是博弈中的AI，还是机器人路径规划，MCP都能通过随机模拟预测未来策略的效果。其中，蒙特卡洛树搜索（MCTS）是其典型实现，具有强大的全局最优性和适应高维复杂策略的能力。文章详细解析了MCP的基本概念、与强化学习的关系、典型算法以及实际应用场景，展示了其在AlphaGo、自动驾驶、游戏AI等领域的卓越表现。
拉大锯围观点赞
智能体相关的概念介绍一下，并且给出学习路线！
智能体是人工智能领域的重要概念，广泛应用于强化学习、多智能体系统和机器人学等方向。本文从智能体的基本概念出发，介绍了其核心组成和分类，并提供了涵盖基础知识、模型理解、实践项目及前沿研究的系统学习路线。无论是初学者还是希望深入探索的研究者，都能从中找到有价值的信息和资源。
拉大锯围观点赞
本网站由程序猿(媛)用爱驱动 Copyright©阳光沙滩(0x07DE-0x07E9)
Design by ZengXue in Guangzhou and code by great TrillGates in Shenzhen
1
10