AI Agent Skill：标准化能力单元的设计与实践-AI智能范式网

AI Agent Skill：标准化能力单元的设计与实践

北辰遴选·2026-09-05·阅读 21 GEO检测（免费）

AI AgentSkillPrompt工程

|难度：普通|阅读约 9 分钟

1. 什么是AI Agent Skill？

在AI编程领域，Skill（技能）正逐渐成为扩展AI能力的核心机制。简单来说，Skill就是为AI Agent编写的标准化操作手册。与传统的Prompt（提示词）不同，Skill具有持久化、可复用、结构化等特点。

1.1 Skill的核心特征

持久化存储：Skill以文件形式存储在项目中，可以被Git管理，实现团队共享
结构化组织：采用标准化的目录结构和文件格式
渐进式加载：根据需求动态加载不同层级的内容
确定性执行：通过脚本保证关键操作的稳定性

提示：Skill不是简单的Prompt集合，而是包含完整知识体系、操作流程和资源文件的标准化能力单元。

1.2 Skill与相关概念的对比

概念	特点	适用场景
Prompt	单次对话指令，用完即弃	简单、临时的任务
Skill	持久化能力单元，可复用	复杂、重复性高的任务
MCP	标准化工具接入协议	系统级集成和扩展

在实际开发中，这三者往往需要配合使用。Skill处于中间层，既不像Prompt那样临时，也不像MCP那样底层。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. Skill的标准目录结构

一个规范的Skill目录结构是其可维护性和可扩展性的基础。以下是经过多个项目验证的最佳实践：

2.1 基础目录结构

code复制my-skill/
├── SKILL.md           # 核心操作手册（必须）
├── scripts/           # 自动化脚本（可选）
│   ├── deploy.sh
│   └── validate.py
├── references/        # 参考文档（可选）
│   ├── api-guide.md
│   └── style-guide.md
└── assets/            # 资源文件（可选）
    └── config-template.json

2.2 各目录详细说明

2.2.1 SKILL.md - 核心操作手册

这是Skill的入口文件，包含两部分内容：

YAML Frontmatter（元数据）

yaml复制---
name: code-review
description: 按团队标准审查代码。当用户要求review、审查、检查代码质量时使用。
allowed-tools: Read, Bash(grep:*)
---

Markdown Body（正文指令）

markdown复制## 审查步骤
1. 架构维度检查
2. 异常处理检查
3. 日志规范检查
4. 安全风险检查

2.2.2 scripts/ - 确定性执行脚本

这个目录存放需要精确执行的操作脚本。例如：

bash复制#!/bin/bash
# scripts/check-deps.sh
echo "正在检查依赖安全..."
npm audit --production 2>&1
exit_code=$?
if [ $exit_code -ne 0 ]; then
    echo "⚠️ 发现安全漏洞，请查看上方详情"
else
    echo "✅ 未发现安全漏洞"
fi

使用脚本而非纯文字描述的优势：

保证每次执行结果一致
减少AI理解偏差
提高执行效率

2.2.3 references/ - 详细参考文档

存放不适合放在SKILL.md正文中的详细文档。例如：

markdown复制# references/coding-standards.md

## 命名规范
- 变量：camelCase
- 常量：UPPER_SNAKE_CASE
- 函数：camelCase，动词开头

AI会按需读取这些文档，避免一次性加载过多内容导致上下文窗口溢出。

2.2.4 assets/ - 资源文件

存放配置模板、示例代码等资源。例如：

json复制{
  "project": "{{PROJECT_NAME}}",
  "version": "1.0.0",
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "{{DB_NAME}}"
  }
}

3. Skill的渐进式加载机制

3.1 三级加载模型

code复制┌─────────────────────────────────────────┐
│  L1: Metadata (name + description)       │ ← 常驻上下文 (~100 tokens)
│  AI看这个决定是否调用                      │
├─────────────────────────────────────────┤
│  L2: SKILL.md Body                       │ ← 触发时加载 (<500行, <5K tokens)
│  AI读这个了解怎么干                        │
├─────────────────────────────────────────┤
│  L3: references/ scripts/ assets/        │ ← 按需读取 (<5K tokens/文件)
│  AI需要细节时才去看                        │
└─────────────────────────────────────────┘

3.2 设计考量

上下文窗口优化：现代AI模型的上下文窗口虽然扩大，但仍需谨慎使用
响应速度：轻量级元数据确保快速决策
精准调用：只有当真正需要时才加载详细内容

4. Skill编写五大实战技巧

4.1 description是灵魂

description决定了AI何时会调用这个Skill。一个好的description应该包含：

触发条件/关键词
核心功能
使用限制

示例对比：

等级	description	问题
❌ 差	"处理PDF"	太笼统
✅ 好	"从PDF文件中提取文本和表格，填写PDF表单，合并多个PDF。在用户提到PDF文档处理时使用。"	清晰明确

进阶技巧：

添加负面案例说明
使用模板化结构

4.2 先调研再编写

错误流程：
凭经验直接写 → 质量一般

正确流程：

让AI调研最佳实践
基于调研结果设计结构
编写具体内容

示例指令：

code复制请先搜索Go代码审查的最佳实践、常见问题和社区推荐的检查维度，
然后帮我设计一个完整的Skill结构。

4.3 单一职责原则

错误做法：
一个Skill包含代码审查、安全检查、性能优化等多种功能

正确做法：

code-review/SKILL.md
security-audit/SKILL.md
performance-check/SKILL.md

判断标准：
当SKILL.md超过500行时，就应该考虑拆分。

4.4 代码优于文字

文字描述：

code复制检查代码中是否有硬编码的密钥。具体来说，需要搜索源代码文件
中包含password、secret、api_key等关键词的行...

代码实现：

bash复制grep -rn "password\|secret\|api_key\|token" src/ \
  --include="*.go" --include="*.py" --include="*.js" \
  | grep -v "test" | grep -v "mock"

代码的优势：

执行精确
减少歧义
便于维护

4.5 添加Gotchas部分

Gotchas是ROI最高的改进，专门记录AI容易犯的错误和陷阱。

示例：

markdown复制## ⚠️ Gotchas

- **不要用rm -rf删除任何目录** — 使用trash命令代替
- **数据库操作前必须先备份** — 执行scripts/backup.sh
- **不要修改代码，只做审查** — 这是review不是fix

5. 完整Skill示例：代码审查

5.1 目录结构

code复制.codebuddy/skills/code-review/
├── SKILL.md
├── scripts/
│   └── check-deps.sh
└── references/
    └── coding-standards.md

5.2 SKILL.md内容

yaml复制---
name: code-review
description: >
  按团队标准审查代码质量。Use when users ask to review, audit, 
  or check code quality. Covers architecture, error handling, 
  logging, and security dimensions.
allowed-tools: Read, Bash(grep:*), Bash(find:*)
---

5.3 审查流程

markdown复制## 审查流程

### Step 1: 架构检查
- 模块拆分是否合理
- 执行`scripts/check-deps.sh`检查依赖安全

### Step 2: 异常处理
- 外部调用是否有try-catch
- 是否使用自定义AppError

### Step 3: 日志规范
- 关键操作是否有日志
- 是否包含trace_id

### Step 4: 安全检查
```bash
grep -rn "password\|secret\|api_key" src/ --include="*.go" | grep -v test

6. 质量检查清单

编写完成后，请对照以下清单检查：

[ ] description是否明确
[ ] 是否遵循单一职责
[ ] 是否有足够代码示例
[ ] 是否包含Gotchas
[ ] 是否经过实际测试

7. 个人实战心得

在实际项目中应用Skill体系后，我发现以下几个关键点：

版本控制很重要：Skill应该和代码一样进行版本管理
定期更新：随着项目发展，Skill也需要迭代
团队协作：建立Skill编写规范，确保风格一致
性能监控：记录Skill的调用频率和效果

一个特别实用的技巧是：为常用Skill创建别名系统，这样可以提高调用效率。例如：

"cr" → code-review
"sa" → security-audit

最后提醒：Skill不是银弹，它最适合标准化程度高、重复性强的任务。对于创造性工作，还是需要结合Prompt和人工干预。