jQuery指针时钟(附带日期)

提示词模板

Agent Skills 完全指南:如何创建高质量的 AI 技能

Agent Skills 是由 Anthropic 维护的开放格式,用于让 AI 获得特定领域的能力和专业知识。本文档提供了创建高质量 Skill 的完整模板和书写要点。

GitHub 地址: https://github.com/anthropics/skills

官方文档: https://agentskills.io

规范文档: https://agentskills.io/specification


目录


什么是 Agent Skills

Agent Skills 是一种简单、开放的格式,通过包含指令、脚本和资源的文件夹,让 AI 能够在特定任务中表现出色。

核心特点

  • 简单易用:只需创建一个 SKILL.md 文件
  • 可重用:编写一次,到处使用
  • 可扩展:支持添加脚本、模板和参考文档
  • 开放标准:基于开放的 Agent Skills 规范

适用场景

  • 专业化任务(代码审查、文档处理、数据分析)
  • 领域知识(法律、医疗、金融)
  • 工作流程自动化(CI/CD、测试、部署)
  • 企业定制(品牌规范、内部流程)

Skill 文件结构

一个标准的 Skill 文件由两部分组成:

---
name: skill-name
description: [核心描述]
license: Apache 2.0
---

# 技能名称

[主体内容]

必需元素

  • YAML Frontmatter:包含元数据(name、description)
  • Markdown 内容:具体的指令和指南

可选元素

  • 辅助脚本和工具
  • 模板文件
  • 参考文档
  • 示例代码

第一部分:YAML Frontmatter

YAML Frontmatter 是 Skill 的元数据部分,决定了 AI 何时加载和使用该 Skill。

1. name(必需)

name: skill-name

命名规则

  • ✅ 使用小写字母
  • ✅ 用连字符 - 分隔单词
  • 简洁明了,一眼看出功能
  • ✅ 作为唯一标识符

示例对比

示例 评价 原因
name: pdf-processor ✅ 优秀 小写、连字符、清晰
name: code-review-skill ✅ 优秀 小写、连字符、清晰
name: PDFTool ❌ 避免 大写字母
name: skill for pdf ❌ 避免 包含空格
name: my-skill ❌ 避免 过于模糊

2. description(最关键

description 是整个 Skill 最重要的字段,它决定了 AI 何时加载和使用该 Skill。

Description 的黄金法则

一个优秀的 description 必须包含 5 个要素,让 AI 准确理解何时使用该 Skill。

✅ 5 个必备要素

要素 1:核心功能(做什么)

说明该 Skill 能够完成的具体任务和功能。

示例

处理 PDF 文件的读取、创建、合并、拆分等操作
要素 2:使用场景(何时用)

描述在什么情况下应该使用该 Skill。

示例

当用户需要处理 PDF 文档、提取内容或转换格式时
要素 3:触发关键词

列出用户可能提到的关键词或短语。

示例

.pdf 文件、"PDF"、"合并文档"、"拆分页面"、"提取文本"
要素 4:具体能力列表

详细列出 Skill 包含的主要功能。

示例

包括读取/提取文本/表格、合并/拆分 PDF、旋转页面、添加水印、创建新 PDF、填写表单、加密/解密、提取图片和 OCR
要素 5:否定边界(不做什么)

明确说明该 Skill 不适用于什么场景。

示例

不用于一般文本处理、Word 文档(.docx)或图片编辑

📝 Description 书写模板

使用以下模板确保 description 的完整性:

description: "当用户需要[核心功能]时使用此技能。包括[具体能力列表]。如果用户提到[关键词1]、[关键词2]、[关键词3]等,或者请求[具体场景],使用此技能。不适用于[否定边界场景]。"

✅ 优秀的 Description 示例

示例 1:PDF 处理

description: "当用户需要处理 PDF 文件时使用此技能。包括读取/提取文本/表格、合并/拆分 PDF、旋转页面、添加水印、创建新 PDF、填写表单、加密/解密、提取图片和 OCR 等功能。如果用户提到 .pdf 文件、'PDF'、'合并文档'、'拆分页面'、'提取文本'等关键词,或请求生成 PDF,使用此技能。不用于一般文本处理、Word 文档(.docx)或图片编辑。"

为什么优秀

  • ✅ 核心功能明确:处理 PDF 文件
  • ✅ 使用场景:提到 PDF、操作文档
  • ✅ 具体能力:10+ 功能列表
  • ✅ 触发关键词:.pdf、PDF、合并文档、拆分页面、提取文本
  • ✅ 否定边界:不用于文本处理、Word、图片

示例 2:代码审查

description: "在用户需要进行代码审查、代码质量分析、发现潜在bug、性能优化建议、安全漏洞检查、代码规范遵循性检查时使用此技能。适用于审查 Python、JavaScript、TypeScript、Java、Go、C++、Rust 等编程语言的代码。当用户提到 'code review'、'代码审查'、'check code quality'、'find bugs'、'optimize code'、'代码质量'、'安全检查'等关键词时,应该使用此技能。不用于一般性的编程问题解答或代码生成,专注于对已有代码的深入分析和改进建议。"

为什么优秀

  • ✅ 核心功能:代码审查、质量分析
  • ✅ 使用场景:分析已有代码
  • ✅ 适用范围:7 种编程语言
  • ✅ 触发关键词:code review、代码审查、check code quality、find bugs、optimize code
  • ✅ 否定边界:不用于编程问题解答、代码生成

❌ 差的 Description 示例

错误示例 问题描述
description: "PDF 工具" 太模糊,不知道何时用,不知道能做什么
description: "帮助用户处理各种文档" 边界不清晰,和 Word、Excel 混淆
description: "代码助手" 范围太广,不知道具体能力
description: "这个 skill 用于创建算法艺术" 缺少触发关键词和使用场景

3. license(可选但推荐)

license: Apache 2.0

常见许可证类型

许可证 适用场景 说明
Apache 2.0 开源 Skill 推荐,宽松的商业友好的开源许可证
MIT 开源 Skill 最宽松的开源许可证
Proprietary 私有 Skill 专有,不公开源码
Complete terms in LICENSE.txt 复杂许可 引用完整的许可证文件

第二部分:Markdown 主体内容

Markdown 主体是 Skill 的核心指令部分,包含详细的操作指南和规则。

完整结构

# 技能名称

## 1. 身份与定位
[你是谁,你的使命]

## 2. 核心能力
[你能做什么]

## 3. 关键规则
[必须遵守和禁止事项]

## 4. 工作流程
[分步骤的操作指南]

## 5. 使用示例
[实际应用案例]

## 6. 注意事项
[常见问题和陷阱]

## 7. 参考资源
[进一步学习的链接]


部分 1:身份与定位

目的:让 AI 理解该 Skill 的角色定位

书写要点

  • 明确角色身份
  • 说明专注领域
  • 定义核心使命

示例

# 代码审查专家

你是代码审查专家,专注于提供高质量的代码审查、质量分析、bug发现、性能优化建议和安全检查。

你的目标是帮助开发者提升代码质量、可维护性和安全性。


部分 2:核心能力

目的:清晰列出 Skill 包含的所有功能

书写要点

  • 按功能分类组织
  • 每个功能具体可执行
  • 使用动词开头

示例

## 核心能力

### 代码质量分析
- 检查代码的可读性、可维护性和可扩展性
- 识别代码异味(Code Smell)和反模式
- 评估代码复杂度和架构设计
- 提供代码重构建议

### Bug 发现与预防
- 识别潜在的运行时错误和边界情况
- 发现空指针引用、数组越界、资源泄漏等问题
- 检查并发和线程安全问题
- 验证错误处理的完整性

### 性能优化
- 分析时间复杂度和空间复杂度
- 识别性能瓶颈和低效算法
- 提供优化建议和替代方案
- 考虑内存使用和资源管理

### 安全漏洞检查
- 检查常见安全漏洞(SQL注入、XSS、CSRF等)
- 验证输入验证和输出编码
- 评估认证和授权机制
- 检查敏感数据处理

### 代码规范遵循
- 检查是否符合项目代码规范
- 验证命名约定和注释质量
- 评估测试覆盖率和测试质量
- 确保遵循语言最佳实践


部分 3:关键规则(最重要

目的:明确 AI 必须遵守的规则和禁止事项

这是决定 AI 行为边界的关键部分。

书写要点

  • 使用明确的"必须"和"禁止"语言
  • 规则具体可执行
  • 提供清晰的判断标准

示例

## 关键规则

### 审查原则
- **建设性反馈**:始终提供具体、可执行的改进建议
- **平衡观点**:既指出问题,也认可优点
- **分级严重性**:按严重程度分类问题(严重/重要/建议)
- **上下文感知**:考虑代码的实际使用场景和约束

### 必须检查项
- ✅ 错误处理是否完整
- ✅ 边界条件是否考虑
- ✅ 资源是否正确释放
- ✅ 并发安全性是否保证
- ✅ 安全漏洞是否存在
- ✅ 性能是否合理
- ✅ 代码可读性是否良好

### 禁止行为
- ❌ 不进行无根据的批评
- ❌ 不建议过度工程化
- ❌ 不提出破坏现有接口的激进重构
- ❌ 不忽略上下文和业务逻辑


部分 4:工作流程

目的:提供清晰、可执行的步骤指南

书写要点

  • 按步骤顺序组织
  • 每个步骤具体可执行
  • 包含检查清单

示例

## 工作流程

### 第一步:整体评估

#### 1. 理解代码目的
- 阅读相关文档和注释
- 理解业务逻辑和功能需求
- 识别关键依赖和接口

#### 2. 快速扫描
- 检查整体结构和组织
- 识别明显的代码异味
- 评估测试覆盖情况

### 第二步:详细审查

#### 2.1 功能正确性
```bash
# 检查清单
- 业务逻辑是否正确实现
- 边界条件是否处理
- 错误情况是否覆盖
- 数据验证是否充分

2.2 代码质量

# 检查清单
- 函数/方法长度是否合理(建议 < 50 行)
- 圈复杂度是否可控(建议 < 10)
- 命名是否清晰有意义
- 注释是否准确且必要
- 重复代码是否可以抽取

第三步:问题分类

严重级别定义

🔴 严重

  • 安全漏洞
  • 数据损坏风险
  • 资源泄漏
  • 死锁风险

🟡 重要

  • 潜在错误
  • 性能问题
  • 代码异味
  • 测试缺失

🟢 建议

  • 代码风格
  • 可读性改进
  • 最佳实践
  • 微小优化

第四步:生成审查报告

[具体的报告模板]

---

### 部分 5:使用示例

**目的**:通过实际案例展示如何使用该 Skill

#### 书写要点

- 提供多个场景
- 展示完整的处理流程
- 包含用户请求和 AI 响应

#### 示例

​```markdown
## 使用示例

### 示例 1:Python 代码质量审查

**用户请求**:

请帮我审查这段 Python 代码,检查是否有问题:

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)

**处理流程**:

1. **分析代码目的**:计算数字列表的平均值
2. **功能正确性检查**:
   - 边界条件:空列表会引发 ZeroDivisionError
   - 输入验证:未检查 numbers 是否为空
3. **代码质量检查**:
   - 函数长度:合理
   - 命名:清晰有意义
   - 复杂度:低,易于理解
4. **安全检查**:无明显安全问题

**输出结果**:


代码审查报告

总体评价

代码功能正确但缺少边界条件处理。整体结构清晰,命名规范。

问题清单

🟡 重要问题

  1. 空列表未处理

    • 位置: 函数最后一行

    • 描述: 当 numbers 为空列表时,len(numbers) 返回 0,引发 ZeroDivisionError

    • 影响: 程序崩溃

    • 建议: 添加空列表检查

    • 示例:

      # 修改前
      return total / len(numbers)
      
      # 修改后
      if not numbers:
          return 0
      return total / len(numbers)
      
      

优点

✅ 函数命名清晰
✅ 逻辑简洁明了
✅ 易于理解

总体评分

  • 正确性: 7/10
  • 可读性: 9/10
  • 可维护性: 8/10
  • 性能: 8/10
  • 安全性: 10/10

下一步建议

优先处理空列表问题



部分 6:注意事项和常见误区

目的:帮助避免常见错误

书写要点

  • 对比正确和错误做法
  • 使用清晰的警告标识
  • 提供具体示例

示例

## 注意事项

### 常见误区

❌ **错误做法**
```python
def process_data(items):
    result = []
    for item in items:
        result.append(process(item))
    return result

正确做法

def process_data(items: List[Item]) -> List[Result]:
    """处理数据列表"""
    return [process(item) for item in items]

改进点

  1. 添加类型注解
  2. 添加文档字符串
  3. 使用列表推导式简化代码

关键警告

⚠️ 重要提示

  • 始终验证用户输入
  • 不要假设数据格式
  • 考虑边界条件
  • 记录关键操作

最佳实践

推荐做法

  • 使用有意义的变量名
  • 保持函数简短(< 50 行)
  • 编写清晰的注释
  • 编写测试用例
  • 遵循语言规范
---

### 部分 7:专项检查清单(可选)

**目的**:针对特定场景的详细检查项

#### 示例

​```markdown
## 专项检查清单

### Python 代码检查
​```python
# 检查项
□ PEP 8 遵循情况
□ 类型注解使用
□ 异常处理完整性
□ 资源管理(with语句)
□ 导入组织
□ 魔术方法使用
□ 装饰器使用
□ 生成器/迭代器使用

JavaScript/TypeScript 代码检查

// 检查项
□ ESLint 规则遵循
□ 类型安全
□ 异步处理(async/await)
□ 事件循环阻塞
□ 内存泄漏风险
□ 原型链污染
□ this 绑定
□ 模块化

Java 代码检查

// 检查项
□ Java 代码规范
□ 异常处理规范
□ 空指针检查(Optional使用)
□ 资源关闭(try-with-resources)
□ 并发安全性
□ 注解使用
□ 泛型使用
□ 内存管理

---

### 部分 8:评分标准(可选)

**目的**:提供量化的评估标准

#### 示例

​```markdown
## 评分标准

| 维度 | 优秀 (8-10) | 良好 (6-7) | 需改进 (< 6) |
|------|-------------|-----------|-------------|
| 正确性 | 无已知bug,边界处理完善 | 有小问题但不影响主要功能 | 存在bug或严重边界问题 |
| 可读性 | 命名清晰,结构简洁 | 整体可读但有改进空间 | 难以理解,命名混乱 |
| 可维护性 | 低耦合高内聚 | 基本合理但有重构空间 | 高耦合难修改 |
| 性能 | 算法高效,无瓶颈 | 性能可接受但有优化空间 | 存在性能问题 |
| 安全性 | 无已知漏洞 | 基本安全但有小风险 | 存在安全漏洞 |


部分 9:参考资源(可选)

目的:提供进一步学习的链接和资源

示例

## 参考资源

### 工具
- **SonarQube**: 综合代码质量分析
- **ESLint/Pylint**: 静态代码分析
- **Coveralls**: 测试覆盖率分析
- **Code Climate**: 代码质量评分

### 文档
- **Anthropic Skills Guide**: https://agentskills.io
- **Clean Code**: Robert C. Martin
- **Refactoring**: Martin Fowler
- **Effective Java**: Joshua Bloch

### 最佳实践
- **Design Patterns**: Gang of Four
- **SOLID Principles**: Robert C. Martin
- **Test-Driven Development**: Kent Beck


高级写作技巧

1. 使用图标增强可读性

在标题和关键点使用图标,让结构更清晰:

# 标题
## 🎯 子标题
### ✅ 建议
### ❌ 禁止
### ⚠️ 警告
### 💡 技巧
### 📚 资源

常用图标

  • 🎯 目标/焦点
  • ✅ 正确/必须
  • ❌ 错误/禁止
  • ⚠️ 警告/注意
  • 💡 技巧/提示
  • 📚 资源/文档
  • 🔧 工具/配置
  • 🚀 部署/启动
  • 📝 示例/代码
  • 📊 评估/评分

2. 使用代码块展示示例

通过对比展示修改前后的代码:

**当前代码**:
```python
def process_data(items):
    result = []
    for item in items:
        result.append(process(item))
    return result

建议改进:

def process_data(items: List[Item]) -> List[Result]:
    """处理数据列表

    Args:
        items: 输入数据项列表

    Returns:
        处理后的结果列表
    """
    return [process(item) for item in items]

改进点

  1. 添加类型注解
  2. 添加文档字符串
  3. 使用列表推导式简化代码
---

### 3. 使用表格对比

通过表格清晰展示对比信息:

​```markdown
| 对比项 | 方案 A | 方案 B |
|--------|--------|--------|
| 性能 | 快(O(n)) | 慢(O(n²)) |
| 可读性 | 高 | 中 |
| 复杂度 | 低 | 高 |
| 适用场景 | 大数据量 | 小数据量 |

4. 使用引用块强调

使用引用块突出重要信息:

> **重要**:description 是 Skill 最重要的字段,决定了 AI 何时加载该 Skill。

> **提示**:在 description 中明确列出触发关键词,提高匹配准确度。

> **警告**:避免在关键规则中使用模糊语言,如"应该"、"可以",应使用"必须"、"禁止"。

5. 使用决策树

通过决策树展示复杂的判断逻辑:

## 决策树

任务 → 是否需要处理 PDF?
├─ 是 → 是否需要读取内容?
│ ├─ 是 → 使用 pdfplumber
│ └─ 否 → 使用 pypdf

└─ 否 → 检查其他文档类型
├─ Word → 使用 docx 库
├─ Excel → 使用 pandas
└─ 其他 → 提示不支持



完整性检查清单

在创建 Skill 时,使用以下清单确保质量:

Frontmatter 部分


内容部分


质量检查


常见错误与修正

错误 1:Description 太模糊

❌ 错误示例

description: "PDF 工具"

问题:太模糊,不知道何时用,不知道能做什么

✅ 正确示例

description: "当用户需要处理 PDF 文件时使用此技能。包括读取/提取文本/表格、合并/拆分 PDF、旋转页面、添加水印、创建新 PDF、填写表单、加密/解密等功能。"

错误 2:缺少否定边界

❌ 错误示例

description: "处理文档的工具,包括 PDF 和 Word"

问题:边界不清晰,和 Word、Excel 混淆

✅ 正确示例

description: "处理 PDF 文件的工具。不适用于 Word 文档(.docx)或图片文件。"

错误 3:规则不明确

❌ 错误示例

## 规则
- 应该注意安全
- 可以优化性能

问题:使用模糊语言,不具体可执行

✅ 正确示例

## 关键规则

### 必须遵守
- ✅ 始终检查 SQL 注入风险
- ✅ 验证所有用户输入
- ✅ 使用参数化查询

### 禁止事项
- ❌ 绝不信任用户输入
- ❌ 不要在客户端做安全验证

错误 4:流程不完整

❌ 错误示例

## 工作流程
分析代码
检查问题
给出建议

问题:流程不详细,缺少具体步骤

✅ 正确示例

## 工作流程

### 第一步:整体评估
1. 理解代码目的
2. 检查整体结构
3. 识别明显问题

### 第二步:详细审查
1. 功能正确性检查
2. 代码质量分析
3. 性能评估
4. 安全漏洞扫描

### 第三步:问题分类
- 严重问题
- 重要问题
- 改进建议

### 第四步:生成报告
[具体报告模板]

实战案例

案例 1:创建一个 Excel 处理 Skill

Frontmatter

---
name: excel-processor
description: "当用户需要处理 Excel 文件时使用此技能。包括读取/写入数据、数据清洗、数据转换、数据合并、数据透视表生成、图表创建、公式计算、格式设置等功能。如果用户提到 .xlsx、.xls 文件、'Excel'、'电子表格'、'数据表'等关键词,或请求处理表格数据,使用此技能。不用于 CSV 文件处理(使用 csv-skill)或数据库操作。"
license: Apache 2.0
---

主体内容(节选)

# Excel 处理专家

你是 Excel 处理专家,专注于提供高效的 Excel 文件操作和数据分析能力。

你的目标是帮助用户快速处理、分析和可视化 Excel 数据。

## 核心能力

### 数据读取
- 读取 .xlsx、.xls 文件
- 处理多工作表
- 解析单元格格式和公式
- 提取图表和图像

### 数据写入
- 创建新的 Excel 文件
- 写入数据到指定单元格
- 批量写入数据
- 设置单元格格式

### 数据操作
- 数据清洗和转换
- 数据排序和筛选
- 数据合并和拆分
- 数据透视表生成

## 关键规则

### 必须遵守
- ✅ 使用 openpyxl 或 pandas 处理 Excel
- ✅ 保存前验证数据完整性
- ✅ 处理大文件时使用 chunk 分块读取

### 禁止事项
- ❌ 不要尝试处理密码保护的文件
- ❌ 不支持 .xlsb 格式

## 工作流程

### 第一步:文件读取
1. 检查文件格式(.xlsx 或 .xls)
2. 读取文件内容
3. 解析工作表结构

### 第二步:数据处理
1. 执行请求的操作
2. 验证处理结果
3. 处理异常情况

### 第三步:文件保存
1. 验证输出路径
2. 保存文件
3. 确认保存成功

案例 2:创建一个 API 测试 Skill

Frontmatter

---
name: api-tester
description: "当用户需要进行 API 测试和自动化时使用此技能。包括发送 HTTP 请求、处理响应、验证返回数据、性能测试、压力测试、生成测试报告等功能。如果用户提到 'API'、'接口测试'、'HTTP 请求'、'postman'、'curl'、'RESTful'、'GraphQL'等关键词,或请求测试接口,使用此技能。不用于 UI 自动化测试(使用 webapp-testing)。"
license: Apache 2.0
---

Skill 质量评分

使用以下标准评估你的 Skill 质量:

评价维度 优秀 (8-10) 良好 (6-7) 需改进 (< 6)
Description 完整包含5要素,边界清晰 基本完整但有遗漏 模糊不清,边界不明
结构 层次分明,逻辑清晰 结构基本合理 组织混乱
规则 必须/禁止明确,可执行 有规则但不够具体 规则模糊或缺失
流程 步骤详细,可执行 流程基本完整 流程不完整
示例 多个场景,代码完整 有示例但不够 缺少示例
可读性 格式统一,图标恰当 可读但需改进 难以阅读

最终模板总结

---
name: skill-name
description: "当用户需要[核心功能]时使用此技能。包括[具体能力列表]。如果用户提到[关键词1]、[关键词2]等,使用此技能。不适用于[否定边界场景]。"
license: Apache 2.0
---

# 技能名称

你是 [角色],专注于 [领域]。
你的目标是 [使命]。

## 核心能力

- **能力 1**:具体说明
- **能力 2**:具体说明
- **能力 3**:具体说明

## 关键规则

### 必须遵守
- ✅ 规则 1
- ✅ 规则 2

### 禁止事项
- ❌ 禁止 1
- ❌ 禁止 2

## 工作流程

### 步骤 1:[名称]
[具体操作]

### 步骤 2:[名称]
[具体操作]

## 使用示例

### 示例 1
[场景描述和完整流程]

## 注意事项

### 常见误区
❌ 错误做法
✅ 正确做法

### 关键警告
⚠️ 重要提示

## 参考资源

[工具、文档、最佳实践链接]

总结

创建高质量的 Agent Skills 的关键要点:

  1. Description 是最重要的字段
    • 必须包含 5 个要素
    • 明确边界和触发条件
    • 避免模糊描述
  2. 关键规则决定了 AI 的行为
    • 使用"必须"和"禁止"
    • 规则具体可执行
    • 避免模糊语言
  3. 工作流程必须具体可执行
    • 分步骤组织
    • 每个步骤清晰
    • 包含检查清单
  4. 提供充分的使用示例
    • 多个场景
    • 完整流程
    • 对比展示
  5. 注意格式和可读性
    • 使用图标和表格
    • 层次清晰
    • 语言简洁准确

相关资源


最后提醒:优秀的 Skill 不仅要有清晰的 description,还要有具体可执行的规则、完整的流程和丰富的示例。始终从使用者的角度思考,提供最有价值的指导。

posted @ 2026-03-13 15:30  atsuc  阅读(31)  评论(0)    收藏  举报