名称： agentskills-io
描述： 遵循 agentskills.io 官方开放标准，创建、验证和发布智能体技能。适用于以下场景：(1) 为 AI 智能体创建新技能，(2) 验证技能结构和元数据，(3) 理解智能体技能规范，(4) 将现有文档转换为可移植技能，(5) 确保与 Claude Code、Cursor、GitHub Copilot 等工具的跨平台兼容性。
许可证： Apache-2.0
元数据：
author: agentic-insights
version: "1.0"
spec-url: https://agentskills.io/specification
reference-repo: https://github.com/agentskills/agentskills

Agent Skills (agentskills.io)

为 AI 智能体创建可移植的技能。兼容 Claude Code、Cursor、GitHub Copilot、OpenAI 集成、VS Code（通过符号链接可在不同工具间共享技能）。

资源

• 规范文档：https://agentskills.io/specification | 验证工具：https://github.com/agentskills/agentskills

目录结构

技能名称/
├── SKILL.md          # 必需文件（包含 Frontmatter 和指令，激活时 <5000 tokens）
├── scripts/          # 可选：可执行代码
├── references/       # 可选：详细文档
└── assets/           # 可选：模板、静态文件

规则：目录名必须与 Frontmatter 中的 name: 字段一致。最多只能有 3 个子目录。SKILL.md 文件应少于 500 行。用于技能发现的摘要（名称+描述）约 100 tokens。

Frontmatter（前置元数据）

必需字段

• name: 1-64 个字符，仅限小写字母、数字和连字符（正则：^[a-z0-9]+(-[a-z0-9]+)*$）
• description: 1-1024 个字符，必须包含 "Use when..." 或 "适用于..." 字样（发现摘要约 100 tokens）

可选字段

• license: SPDX 许可证标识符（如 Apache-2.0, MIT）| compatibility: 环境要求（<500 字符）
• metadata: 键值对（作者、版本、标签等）| allowed-tools: 空格分隔的工具列表

验证

# 永久安装验证工具（与临时安装 uvx 相对）
uv tool install git+https://github.com/agentskills/agentskills#subdirectory=skills-ref
# 或使用 uvx 进行一次性验证
uvx --from git+https://github.com/agentskills/agentskills#subdirectory=skills-ref skills-ref validate ./skill

编写规则

• 使用祈使句：例如“检查：命令”，而非“你可能需要...”
• 提供包含预期输出的具体示例；针对常见错误提供解决方案
• 渐进式披露：核心内容放在 SKILL.md（<5000 tokens），详细信息放在 references/ 目录下

常见错误

快速工作流

1. 创建：mkdir 技能名称 && touch 技能名称/SKILL.md
2. 添加 Frontmatter：填写 name 和 description（必须包含 "Use when..."）
3. 编写指令：使用项目符号而非段落；验证：skills-ref validate ./技能名称
4. 测试与迭代：使用 AI 智能体测试，迭代优化；添加 LICENSE 文件，推送至代码仓库

插件结构（Claude Code）

插件名称/
├── .claude-plugin/plugin.json
├── README.md, LICENSE, CHANGELOG.md  # CHANGELOG.md 用于记录版本变更
├── skills/技能名称/SKILL.md
├── agents/     # 可选：子智能体（.md 文件）
└── examples/   # 可选：完整的演示项目

区别：插件的 examples/ 目录包含可运行的项目。技能的 assets/ 目录仅包含静态资源。

批量验证与版本管理

bash scripts/validate-skills-repo.sh     # 验证仓库中的所有技能
bash scripts/bump-changed-plugins.sh     # 自动为发生变更的插件升级版本号（遵循语义化版本）

最小示例

---
名称： example-skill
**描述：** 简要描述。适用于执行 X 操作时。
---
# 示例技能
## 先决条件
- 所需工具
## 指令
1.  第一步：`命令`
2.  第二步及示例
## 故障排除
**错误**：错误信息 → **修复**：解决方案

符号链接共享

在 Claude Code、Cursor、VS Code 之间共享技能：ln -s /技能/路径 ~/.cursor/skills

参考文档

• specification.md - 完整的 YAML 模式定义、token 限制
• examples.md - 跨平台的完整示例
• validation.md - 错误排查指南
• best-practices.md - 高级模式、符号链接设置