本教程将手把手教你开发属于自己的 Agent Skill。我们将深入探讨 SKILL.md 的核心结构，分享来自 Anthropic、OpenAI 等厂商的最佳实践，并提供一个完整的实战案例，帮助你快速构建可复用、跨平台的 AI 技能包。

1. 理解 Agent Skill 的核心架构

一个 Agent Skill 本质上是一个包含特定文件和目录的文件夹。其核心设计理念是渐进式披露 (Progressive Disclosure)，以确保在执行复杂任务时不会撑爆 Agent 的上下文窗口 [1]。

一个标准的 Skill 目录结构如下：

my-skill/
├── SKILL.md          # 必需：元数据 + 核心指令
├── scripts/          # 可选：可执行代码（如 Python、Bash 脚本）
├── references/       # 可选：补充文档（按需加载）
└── assets/           # 可选：模板、图片等静态资源

SKILL.md 文件结构

SKILL.md 是 Skill 的灵魂，它分为两部分：YAML 前置元数据（Frontmatter）和 Markdown 正文 [2]。

1.1 YAML Frontmatter

这是 Agent 决定是否加载该 Skill 的唯一依据。只有 name 和 description 是必填项。

---
name: my-skill-name
description: >-
  在这里写详细的描述。必须包含两个要素：
  1. 这个 Skill 能做什么。
  2. 什么时候（What conditions/triggers）应该使用它。
license: MIT
metadata:
  author: YourName
  version: "1.0.0"
---

最佳实践 [3]：

• Name 规范：只能包含小写字母、数字和连字符，不能超过 64 个字符，且必须与文件夹名称完全一致。
• Description 的重要性：这是全文最重要的一行。Agent 在启动时只会读取所有 Skill 的 name 和 description。如果描述不清晰，Agent 永远不会触发这个 Skill。
• 触发三连击 (Trigger Triad)：在 description 中务必包含：(1) 能力（做什么）、(2) 触发条件（什么时候用）、(3) 用户的常用词汇（用户可能会怎么搜这个词）。

1.2 Markdown Body (指令正文)

这是 Agent 在触发 Skill 后加载的具体操作指南。官方建议控制在 500 行或 5000 Token 以内 [4]。

编写指令的原则：

• 只写 Agent 不知道的东西：Agent 已经知道什么是 HTTP 请求或什么是 PDF 文件。你需要写的是你们团队的特定 API 端点、特殊的命名规范或常见的陷阱 (Gotchas) [5]。
• 控制自由度 (Degrees of Freedom)：对于脆弱的任务（如数据库迁移），给出低自由度指令（精确的命令和脚本）；对于开放任务（如代码审查），给出高自由度指令（指导原则和检查清单）[3]。
• 使用祈使句：指令应简洁明了，如 “Run this script” 而不是 “You could try running this script”。

2. 渐进式披露的高级用法

为了让你的 Skill 既强大又不消耗过多的 Token，你需要掌握渐进式披露的技巧 [4]。

1. 按需加载文档 (References)：如果你的工作流有很多分支（例如针对不同平台的部署指南），不要全部写在 SKILL.md 里。在 SKILL.md 中指引 Agent：

   如果要部署到 AWS，请阅读 [aws-deploy.md](references/aws-deploy.md)。
   如果要部署到 GCP，请阅读 [gcp-deploy.md](references/gcp-deploy.md)。
   

2. 使用脚本替代上下文 (Scripts)：如果涉及复杂的数据处理或计算，不要让 Agent 生成 Python 代码来执行。直接提供写好的 scripts/process_data.py，并告诉 Agent 运行它 [5]。
3. 使用模板规范输出 (Assets)：如果要求 Agent 生成特定格式的报告，提供一个模板文件在 assets/report_template.md 中，并指示 Agent “严格按照 assets/report_template.md 的格式生成输出” [3]。

3. 实战案例：创建一个"安全代码审查"Skill

假设你希望开发一个 Skill，专门用于审查团队代码中的常见安全漏洞。

步骤 1：创建目录和基础文件

在你的个人 Skills 目录下创建一个新文件夹。根据你使用的 Agent 客户端，路径可能不同 [6]：

• Claude Code: ~/.claude/skills/secure-review/
• OpenAI Codex: ~/.agents/skills/secure-review/
• GitHub Copilot: .github/skills/secure-review/ (项目级) 或 ~/.agents/skills/secure-review/ (用户级)

步骤 2：编写 SKILL.md

在 secure-review/ 目录下创建 SKILL.md：

---
name: secure-review
description: >-
  审查代码中的常见安全漏洞和最佳实践。
  当用户要求进行代码审查、检查安全问题、验证身份认证逻辑或要求查找潜在的 SQL 注入、XSS 攻击风险时使用。
license: MIT
---

# Secure Code Review

## 审查流程

1. **分析输入代码**：识别使用的编程语言和框架。
2. **执行静态扫描**：运行提供的脚本进行初步检查。
3. **手动逻辑审查**：检查身份验证、授权和数据过滤逻辑。
4. **生成报告**：使用指定的模板输出结果。

## 静态扫描

运行团队提供的扫描脚本：
```bash
python scripts/security_scanner.py

如果脚本报告任何 HIGH 或 CRITICAL 级别的漏洞，必须在最终报告中列出修复建议。

常见陷阱 (Gotchas)

• 数据库查询：必须使用参数化查询 (Parameterized queries)。绝对禁止字符串拼接 SQL。
• 环境变量：敏感信息（如 API Key）不得硬编码在代码中。
• 错误信息：确保错误堆栈 (Stack Trace) 不会泄露给用户或前端。

报告格式

审查完成后，请严格按照 report_template.md 的格式生成审查报告。

### 步骤 3：添加脚本和模板

为了让这个 Skill 完整运行，你需要补充相关文件：

1.  **创建 `scripts/security_scanner.py`**：
    这是一个简单的 Python 脚本，用于演示 Agent 如何执行代码：
    ```python
    import os
    import re

    def scan_directory(path):
        issues = []
        # 简单的正则扫描演示
        if os.path.exists(path):
            for root, _, files in os.walk(path):
                for file in files:
                    if file.endswith('.py'):
                        with open(os.path.join(root, file), 'r') as f:
                            content = f.read()
                            if re.search(r'execute\(["\']SELECT.*\+.*["\']', content):
                                issues.append(f"Potential SQL Injection in {file}")
        return issues

    if __name__ == "__main__":
        issues = scan_directory('.')
        if issues:
            print(f"CRITICAL: Found {len(issues)} issues:")
            for issue in issues:
                print(f"- {issue}")
        else:
            print("SUCCESS: No obvious vulnerabilities found.")
    ```

2.  **创建 `assets/report_template.md`**：
    提供一个标准的报告结构：
    ```markdown
    # 安全代码审查报告
    
    ## 1. 审查摘要
    [简述审查的文件范围]
    
    ## 2. 发现的安全问题
    | 严重级别 | 文件位置 | 问题描述 | 修复建议 |
    |----------|----------|----------|----------|
    | HIGH     | `auth.py`| 硬编码密码 | 使用环境变量 |
    
    ## 3. 合规性检查
    - [ ] 数据库查询已参数化
    - [ ] 无敏感信息泄露
    ```

## 4. 测试与迭代

开发完 Skill 后，你需要对其进行测试。

1.  **触发测试**：在终端打开你的 Agent，然后输入："帮我看一下当前目录下代码的安全问题"。
2.  **观察行为**：
    *   Agent 是否正确识别并加载了 `secure-review` Skill？
    *   Agent 是否成功运行了 `security_scanner.py` 脚本？
    *   最终生成的报告是否符合 `report_template.md` 的要求？
3.  **迭代优化**：如果发现 Agent 漏掉了某些漏洞，或者报告格式不对，你可以直接修改 `SKILL.md` 中的指令（例如在"常见陷阱"中添加新规则），然后重新测试。

## 5. 如何分发你的 Skill

当你对自己的 Skill 满意后，你可以通过以下方式分享给团队或社区：

1.  **Git 仓库**：将 Skill 文件夹推送到 GitHub。其他用户可以使用 `npx skills add your-username/your-repo` 进行安装（支持标准 Skill 安装器的客户端）[6]。
2.  **Plugin 封装**：如果你想打包多个相关的 Skill 甚至加上 MCP 服务器配置，可以将其封装为一个 Plugin。在 OpenAI Codex 或 ChatGPT 中，Plugin 是分发复杂 Skills 的标准方式 [7]。

---

## 参考资料

[1] Agent Skills Specification. "Specification." https://agentskills.io/specification
[2] Anthropic Engineering. "Equipping agents for the real world with Agent Skills." https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
[3] Anthropic Developer Docs. "Skill authoring best practices." https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
[4] Agent Skills Docs. "Best practices for skill creators." https://agentskills.io/skill-creation/best-practices
[5] GitHub/Anthropics. "Public repository for Agent Skills." https://github.com/anthropics/skills
[6] OpenAI Developers. "Build skills." https://developers.openai.com/codex/skills/
[7] Microsoft Docs. "Use Agent Skills in VS Code." https://code.visualstudio.com/docs/agent-customization/agent-skills