skills-creator

技能创建器

用于创建、验证和管理符合 agentskills.io 规范的 Agent 技能的综合技能。

何时使用此技能

在以下情况使用此技能：

• 用户要求创建新的 Agent 技能
• 用户想修改或改进现有技能
• 用户需要验证技能的结构或 frontmatter
• 用户提到“skill”“agent skill”或 agentskills.io
• 用户想了解 Agent Skills 格式

什么是 Agent Skills

Agent Skills 是一种轻量级的开放格式，用于通过专业知识和工作流扩展 AI Agent 的能力。技能的核心是一个包含 SKILL.md 文件的文件夹，该文件包含元数据和说明。

渐进式披露原则

技能通过渐进式披露来高效管理上下文：

1. 发现：启动时，Agent 仅加载名称和描述
2. 激活：在相关时，Agent 会读取完整的 SKILL.md 说明
3. 执行：Agent 会根据需要加载引用的文件或执行代码

这样既能让 Agent 保持快速，又能按需提供更多上下文。

目录结构

skill-name/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

SKILL.md 格式

每个技能都以 YAML frontmatter 开头，后接 Markdown 说明。

必需的 frontmatter

---
name: skill-name
description: A description of what this skill does and when to use it.
---

可选的 frontmatter 字段

---
name: skill-name
description: What this skill does and when to use it.
license: MIT
compatibility: Requires git, docker, jq, and internet access
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---

字段规范

name 字段

• 必需：是
• 限制：1-64 个字符，只能包含小写字母、数字和连字符
• 开头和结尾都不能是连字符
• 不能包含连续的连字符（--）
• 必须与父目录名称一致

有效示例：

• pdf-processing
• data-analysis
• code-review

无效示例：

• PDF-Processing（包含大写字母）
• -pdf（以连字符开头）
• pdf--processing（包含连续的连字符）

description 字段

• 必需：是
• 限制：1-1024 个字符，不能为空
• 应说明技能的功能以及适用时机
• 应包含能帮助 Agent 识别相关任务的具体关键词

良好示例：

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

较差示例：

description: Helps with PDFs.

license 字段

• 必需：否
• 保持简短（许可证名称或对捆绑文件的引用）

示例：

license: Apache-2.0

compatibility 字段

• 必需：否
• 限制：如提供，须为 1-500 个字符
• 仅当技能有特定环境要求时才填写
• 可注明预期使用的产品、所需软件包、网络访问等

示例：

compatibility: Designed for Claude Code (or similar products)

compatibility: Requires git, docker, jq, and access to the internet

metadata 字段

• 必需：否
• 将字符串键映射到字符串值
• 用于存储规范未定义的其他属性
• 键名应具有足够的独特性，以避免冲突

示例：

metadata:
  author: example-org
  version: "1.0"
  category: development

allowed-tools 字段

• 必需：否
• 以空格分隔的预先批准工具列表
• 实验性功能，支持情况各不相同

示例：

allowed-tools: Bash(git:*) Bash(jq:*) Read

正文内容指南

frontmatter 后的 Markdown 正文包含技能说明。格式不受限制，但请遵循以下最佳实践：

推荐章节

1. 何时使用此技能 - 明确说明 Agent 应在何种情况下激活此技能
2. 此技能的功能 - 简要概述其能力
3. 分步说明 - 详细流程
4. 示例 - 示例输入和预期输出
5. 常见模式 - 可复用的方法
6. 最佳实践 - 提示和建议
7. 边缘情况 - 如何处理特殊情况

内容最佳实践

• 将主 SKILL.md 控制在 500 行以内（建议少于 5000 个 token）
• 将详细的参考资料移至 references/ 中的单独文件
• 使用清晰、可执行的语言
• 在有帮助时加入代码示例
• 重点说明“为什么”和“如何”，而不仅是“是什么”
• 撰写说明时考虑 Agent 的视角

可选目录

scripts/

包含 Agent 可运行的可执行代码。

最佳实践：

• 让脚本自包含，或清楚地说明依赖项
• 提供有帮助的错误消息
• 妥善处理边缘情况
• 使用常见语言（Python、Bash、JavaScript）

结构示例：

scripts/
├── validate.py
├── generate.sh
└── utils/
    └── helpers.py

references/

包含按需加载的补充文档。

最佳实践：

• 每个文件专注于单一主题
• 使用描述性文件名
• 推荐文件：
  • REFERENCE.md - 详细的技术参考
  • FORMS.md - 表单模板或结构化数据格式
  • 特定领域的文件（finance.md、legal.md 等）

结构示例：

references/
├── REFERENCE.md
├── API.md
└── TROUBLESHOOTING.md

assets/

包含模板、图像和数据文件等静态资源。

结构示例：

assets/
├── templates/
│   └── config.yaml
├── diagrams/
│   └── workflow.png
└── data/
    └── schema.json

文件引用

引用技能中的其他文件时，请使用相对于技能根目录的路径：

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
```bash
scripts/extract.py

Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains.

## Creating a new skill step-by-step

When a user asks you to create a skill, follow these steps:

### 1. Gather requirements
Ask the user:
- What should the skill do?
- When should it be activated?
- What tools or resources are needed?
- Are there specific examples or use cases?

### 2. Choose a name
- Use lowercase with hyphens
- Keep it short and descriptive
- Ensure it matches the directory name

### 3. Write a clear description
- Include what the skill does
- Include when to use it
- Add keywords for agent matching

### 4. Create directory structure
```bash
mkdir -p skill-name/scripts
mkdir -p skill-name/references
mkdir -p skill-name/assets

5. 编写 SKILL.md

先添加 frontmatter，然后编写正文，包含：

• 何时使用部分
• 功能说明
• 分步说明
• 示例
• 最佳实践

6. 添加支持文件（如需要）

• scripts/ 中的脚本
• references/ 中的参考文档
• assets/ 中的模板和资源

7. 验证

检查以下内容：

• 名称符合约束（小写、不能有连续连字符等）
• 描述清晰且包含丰富的关键词（1-1024 个字符）
• Frontmatter 是有效的 YAML
• 目录名称与技能名称一致
• 说明清晰且可执行

常见模式

基础技能（仅含说明）

basic-skill/
└── SKILL.md

含脚本的技能

automation-skill/
├── SKILL.md
└── scripts/
    └── automate.py

含参考文档的复杂技能

complex-skill/
├── SKILL.md
├── scripts/
│   └── process.py
├── references/
│   ├── REFERENCE.md
│   └── API.md
└── assets/
    └── templates/
        └── config.yaml

验证清单

完成技能前，请确认：

• 目录名称与 frontmatter 中的 name 一致
• name 长度为 1-64 个字符，且仅包含小写字母、数字和连字符
• name 不以连字符开头或结尾，也不包含连续连字符
• description 长度为 1-1024 个字符，且包含何时使用
• YAML frontmatter 有效
• 主 SKILL.md 少于 500 行
• 文件引用使用相对路径
• 脚本具有清晰的错误处理（如有）
• 没有过深的参考链

技能模板示例

最简技能

---
name: example-skill
description: Brief description of what this does and when to use it.
---

## When to use this skill
Use when...

## Instructions
1. Step one
2. Step two
3. Step three

功能完备的技能

---
name: advanced-skill
description: Comprehensive description with keywords for activation.
license: MIT
compatibility: Requires specific tools or environment
metadata:
  author: your-name
  version: "1.0"
---

## When to use this skill
Use when...

## What this skill does
Overview...

## Instructions
Detailed steps...

## Examples
Sample code and outputs...

## Best practices
Tips and recommendations...

## Common patterns
Reusable approaches...

## Troubleshooting
See [troubleshooting guide](references/TROUBLESHOOTING.md)

集成说明

技能旨在与基于文件系统的 Agent（首选）或基于工具的 Agent 配合使用：

基于文件系统的 Agent

• 通过 cat /path/to/skill/SKILL.md 等 Shell 命令激活技能
• 通过 Shell 命令访问捆绑的资源

基于工具的 Agent

• 实现用于触发技能和访问资源的工具
• 工具的实现方式由开发者决定

资源

更多信息：

• agentskills.io 规范
• 集成指南
• GitHub 上的技能示例
• 编写最佳实践
• 参考库（skills-ref）

验证命令

如果用户已安装 skills-ref 库：

# Validate a skill directory
skills-ref validate ./skill-name

# Generate XML for agent prompts
skills-ref to-prompt ./skill-name

编写技能的最佳实践

1. 保持专注：一个技能应做好一件事
2. 明确描述：包含激活关键词
3. 渐进式披露：保持 SKILL.md 简洁，将详细内容移至参考文档
4. 提供示例：展示，而不只是说明
5. 妥善处理错误：预想到边缘情况
6. 充分测试：确保说明清晰且完整
7. 为技能添加版本信息：使用元数据跟踪更改
8. 记录依赖项：必要时使用兼容性字段
9. 确保可移植性：尽可能让技能适用于不同环境
10. 从 Agent 的角度思考：以 Agent 的视角编写说明

安全注意事项

创建包含脚本的技能时：

• 警告用户注意潜在的危险操作
• 记录所有外部依赖项
• 考虑沙盒要求
• 使用允许列表管理可信脚本
• 记录脚本执行情况以供审计
• 避免硬编码凭据或机密