环境搭建与实战：编写你的第一个 Agent Skill

在理解了 Agent Skills 的基本概念后，是时候动手实践了。本章将带你完成开发环境的搭建，并一步步编写、部署和测试你的第一个 Agent Skill。我们将从最简单的 "Hello World" 开始，逐渐过渡到能够执行实际脚本的实用技能。

1. 开发环境准备

Q: 在开始编写 Skill 之前，我需要准备哪些工具和环境？

A: 开发 Agent Skills 的门槛非常低，你主要需要以下两个组件：

1. AI 编程助手客户端：

   • Claude Code（推荐）：Anthropic 官方提供的 CLI 工具，对 Agent Skills 支持最完善。
   • OpenAI Codex CLI：如果你是 OpenAI 生态的用户，Codex CLI 也支持同样的规范。
   • 注意：确保你已经申请并获得了相应的 API 访问权限（如 Claude API Key）。

2. 基础编程环境：

   • 文本编辑器：VS Code、Cursor 或任何你喜欢的编辑器。
   • Node.js (v18+)：运行 Claude Code 的基础环境。
   • Python/Shell（可选）：如果你计划编写复杂的脚本技能，需要确保本地安装了相应的解释器。

**安装 Claude Code (示例)**：

npm install -g @anthropic-ai/claude-code
claude login

2. 技能目录结构与配置

Q: 我写好的 Skill 文件应该放在哪里？AI 怎么找到它们？

A: Claude Code 和 Codex 遵循特定的目录约定来加载技能。你可以选择将技能安装在全局范围或项目范围。

目录路径

• **全局技能 (Global Skills)**：

  • 适用于所有项目的通用工具（如：天气查询、日程管理）。
  • macOS/Linux: ~/.claude/skills/
  • Windows: %APPDATA%\Claude\skills\ (通常是 C:\Users\你的用户名\AppData\Roaming\Claude\skills\)

• **项目技能 (Project Skills)**：

  • 仅针对当前项目有效的特定工具（如：当前项目的部署脚本、数据库迁移工具）。
  • 路径: 项目根目录下的 .claude/skills/ 文件夹。
  • 提示：记得将 .claude 加入 .gitignore，除非你想与团队共享这些配置（通常建议共享）。

标准结构

一个标准的 Skill 文件夹结构如下：

my-awesome-skill/
├── SKILL.md           # 核心定义文件 (必须)
├── script.py          # 可选：执行逻辑脚本
├── template.txt       # 可选：提示词模板
└── marketplace.json   # 可选：元数据，用于发布

3. 实战：编写 "Hello World" Skill

Q: 能带我写一个最简单的 Skill 吗？

A: 当然。我们将创建一个名为 greeter 的简单技能，当用户打招呼时，它会返回一段个性化的问候。

步骤 1：创建目录
在你的全局技能目录下创建一个名为 greeter 的文件夹。

步骤 2：编写 SKILL.md
在 greeter 文件夹中创建 SKILL.md，内容如下：

# Greeter

## Description
这是一个用于向用户致以热情问候的技能。当用户说“你好”、“Hello”或初次见面时触发。它应该返回一段包含当前时间的友好问候。

## Usage
直接向用户返回问候语，无需执行外部脚本。

## Examples
User: 你好呀！
Assistant: 你好！很高兴见到你。现在是工作时间，让我们开始高效编码吧！

User: Hello
Assistant: Hi there! Ready to build something amazing together?

步骤 3：加载与测试

1. 打开终端，运行 claude 启动助手。
2. 输入 /skills 命令，检查列表中是否出现了 Greeter。
3. 尝试输入：“你好，今天心情怎么样？”
4. 观察 AI 是否根据 Skill 的指示进行了回复。

注：这个例子展示了 Agent Skill 的纯 Prompt 模式——不执行代码，仅通过 System Prompt 注入行为指令。

4. 进阶：集成 Python 脚本

Q: 如果我想让 Skill 做点实事，比如生成一个 UUID，该怎么做？

A: 这时我们需要在 Usage 部分定义具体的命令执行逻辑。

步骤 1：创建脚本
在 uuid-generator 文件夹下创建 generate_uuid.py：

import uuid
print(f"Generated UUID: {uuid.uuid4()}")

步骤 2：编写 SKILL.md

# UUID Generator

## Description
用于生成随机 UUID (Universally Unique Identifier) 的工具。当用户需要“生成 ID”、“创建唯一标识符”或“给我一个 UUID”时使用。

## Usage
运行以下 Python 脚本并向用户展示结果：

```bash
python generate_uuid.py

Examples

User: 帮我生成一个 UUID。
Assistant: (Executes python generate_uuid.py)
Output: Generated UUID: 550e8400-e29b-41d4-a716-446655440000
Assistant: 好的，这是为你生成的 UUID：550e8400-e29b-41d4-a716-446655440000。

关键点：

• 在 Usage 中使用 Markdown 代码块包裹具体的 Shell 命令。
• AI 会在沙箱或受控环境中执行该命令，并读取标准输出（stdout）。

5. 调试与排错

Q: 我的 Skill 好像没反应，或者报错了，如何排查问题？

A: 调试 Agent Skills 主要关注两个方面：意图识别和执行错误。

1. 检查意图识别（Routing）：

   • 如果 AI 没有调用 Skill，通常是 Description 写得不够明确。
   • 技巧：在对话中直接问 AI：“查看你的技能列表，哪个技能最适合处理我刚才的请求？” AI 的回答通常能暴露它对描述的理解偏差。
   • 修改：增加更具体的关键词，或在 Examples 中添加刚才失败的 Case。

2. 检查执行错误（Execution）：

   • 如果 AI 调用了但报错，通常是路径或环境问题。
   • 路径问题：Claude Code 执行命令时，当前工作目录（CWD）通常是项目根目录，而不是 Skill 所在的目录。
   • 绝对路径：在 Usage 中引用脚本时，尽量使用相对路径的动态获取方式，或者让 AI 先 cd 到指定目录（不推荐）。
   • 最佳实践：将脚本打包或确保其在系统 PATH 中，或者在 Usage 中明确指出脚本的相对位置（AI 通常能感知 Skill 文件的位置上下文）。

6. 关于 marketplace.json

Q: 我看到有些开源 Skill 里有一个 marketplace.json 文件，这是必须的吗？

A: 不是必须的，但如果你想分享你的 Skill，它非常有用。

marketplace.json 是 Skills Marketplace 用来索引和展示技能的元数据文件。它就像 package.json 之于 npm 包。

基本结构：

{
  "name": "uuid-generator",
  "version": "1.0.0",
  "description": "A simple tool to generate UUIDs.",
  "author": "YourName",
  "license": "MIT",
  "entry": "SKILL.md"
}

添加这个文件后，你的 Skill 就具备了被分发和被工具自动安装的能力。

总结

恭喜！你已经成功迈出了 Agent Skills 开发的第一步。从简单的问候到执行本地脚本，你现在拥有了扩展 AI 助手能力的钥匙。

在下一章中，我们将深入探讨 高级 Prompt 技巧与复杂工作流，学习如何让 Skill 处理参数输入、进行多步骤推理以及与其他 Skill 协同工作。

课后作业：
编写一个 system-info Skill，调用系统命令（如 uname -a 或 systeminfo），让 AI 能够回答“我的电脑配置怎么样？”这类问题。

参考资源：

• Claude Code CLI Manual
• Node.js Download