在智能体（Agent）的开发中，我们正在从单纯的“提示词工程”转向更严谨的**“上下文工程（Context Engineering）”**。构建一个 Agent Skill 不仅仅是写几行指令，而是创建一个结构化的能力单元。

本指南将教你如何遵循开放标准，构建一个既能被模型精准发现，又能高效执行的标准化 SKILL.md。

一、 规范的目录结构

一个标准的 Skill 是一个自包含的文件夹。虽然模型主要读取 SKILL.md，但配套的脚本和资源能让智能体的操作从“幻觉生成”转变为“确定性执行”。

推荐结构：

my-skill-name/
├── SKILL.md       # 核心文件：包含元数据与指令（必须）
├── scripts/       # 脚本目录：存放 Python/JS 自动化脚本（可选）
├── references/    # 参考文献：存放长篇 API 文档或业务规范（可选）
└── assets/        # 静态资产：存放模板文件、示例图片或 Schema（可选）

技术要点：在指令中引用这些文件时，务必使用 {baseDir} 变量。它是一个运行时注入的路径，确保 Skill 无论安装在何处，智能体都能准确找到配套资源。

二、 YAML Frontmatter 深度解析

SKILL.md 的开头必须包含 YAML 格式的元数据块。这是智能体的“发现引擎”，模型在启动时会扫描这些信息。

---
name: pr-reviewer-pro
description: 专业拉取请求（PR）审查技能。当用户请求代码审查、PR 分析或提交建议时激活。
version: 1.0.0
allowed-tools: Bash(git:*), Read, Write
metadata:
  author: "TechTeam"
  license: "MIT"
---

• name：唯一标识符。必须使用全小写字母、数字和连字符。禁止使用空格或连续连字符。它通常也作为智能体的唤起指令（如在控制台输入 $pr-reviewer-pro）。
• description：这是 Skill 被自动触发的关键。描述应包含特定的触发关键词（Trigger Keywords）。不要只写“帮助处理 PR”，应写“分析代码变更、检查代码风格、并提供修复建议”。
• allowed-tools（实验性）：预先批准的工具列表。设置此项可以减少模型在执行任务时反复询问用户权限的干扰，提升自动化体验。

三 指令正文编写：程序性知识的表达

指令正文是教导模型“如何做”的部分。优秀的 Skill 指令应具备以下特质：

1. 使用命令式语言：使用“分析代码…”而非“你应该分析代码…”。这能增强模型的指令遵循度。
2. 分阶段的工作流：清晰地划分步骤，并定义每个阶段的“成功标准”。
3. 输入输出示例：提供具体的示例能极大降低模型的幻觉率。
4. 错误处理逻辑：明确告知模型当脚本报错或环境不匹配时该如何应对。

示例片段：

# PR 审查专家模式

## 核心流程
1. **获取差异**：首先运行 `git diff --staged` 查看当前变更。
2. **静态分析**：使用内置脚本检查逻辑风险：
   ```bash
   python {baseDir}/scripts/analyze_diff.py --path .

3. 输出报告：按照 REPORT_TEMPLATE.md 的格式生成总结。

成功标准

• 必须包含至少一个性能改进建议。
• 如果检测到安全漏洞，必须以 [CRITICAL] 开头标注。

错误处理

• 如果 analyze_diff.py 报错，请尝试读取错误日志并手动进行逐行审查。

---

### 四、 版本控制与分发

构建好的 Skill 需要被团队成员轻松共享。Agent Skills 的设计使其像文本文件一样具备高度的**可移植性**。

*   **项目级共享**：将 Skill 文件夹存放在项目根目录的 `.github/skills/`（推荐用于 GitHub Copilot/VS Code）或 `.claude/skills/` 中。直接提交到 Git 仓库，团队成员拉取代码后，其智能体将自动获得该能力。
*   **个人级复用**：将通用的技能（如 PDF 处理）存放在全局目录（如 `~/.claude/skills/`），让它在所有项目中随叫随到。
*   **统一安装**：你可以利用 `ai-agent-skills` 这种类似于 Homebrew 的工具，通过一行指令从远程 GitHub 仓库安装 Skill：
    `npx ai-agent-skills install owner/repo/path-to-skill`

---

### 结语

构建一个 `SKILL.md` 的本质是在**模块化人类的专业知识**。通过严格的元数据定义和渐进式的资源引用，我们不仅节省了昂贵的上下文 Token，更让 AI 智能体拥有了可预测、可审计的专业执行力。

**专家建议**：保持 Skill 的职责单一。与其写一个“全能开发助手”，不如拆分为“API 设计专家”、“测试用例专家”和“部署脚本专家”，通过智能体的自主调度实现复杂目标的达成。