Agent Skills (agentskills.io)

为AI智能体创建可移植技能。适用于Claude Code、Cursor、GitHub Copilot、OpenAI集成、VS Code（通过符号链接实现跨工具共享）。

资源

• 规范：https://agentskills.io/specification| 验证器：https://github.com/agentskills/agentskills

结构

skill-name/
├── SKILL.md          # Required (frontmatter + instructions, <5000 tokens activation)
├── scripts/          # Optional: executable code
├── references/       # Optional: detailed docs
└── assets/           # Optional: templates, static files

规则: 目录名 = 前置元数据名称：. 仅允许3个子目录。SKILL.md文件少于500行。发现预算约100个词元（名称+描述）。

前置元数据

必需项

• 名称: 1-64个字符，小写字母数字和连字符（^[a-z0-9]+(-[a-z0-9]+)*$）
• 描述: 1-1024个字符，需包含"在以下情况使用..."（发现预算：约100个词元）

可选项

• 许可证SPDX标识符（Apache-2.0，MIT） |兼容性：环境要求（<500字符）
• 元数据：键值对（作者、版本、标签） |允许的工具：空格分隔的工具列表

验证

# Install permanently (vs ephemeral uvx)
uv tool install git+https://github.com/agentskills/agentskills#subdirectory=skills-ref
# Or use uvx for one-shot validation
uvx --from git+https://github.com/agentskills/agentskills#subdirectory=skills-ref skills-ref validate ./skill

编写规则

• 使用祈使句："检查：命令"，而非"你可能想要..."
• 提供带预期输出的具体示例；处理常见错误并提供解决方案
• 渐进式披露：核心内容在SKILL.md中（<5000令牌），详细信息在参考资料中

常见错误

快速工作流程

1. 创建步骤：mkdir skill-name && touch skill-name/SKILL.md
2. 添加前置元数据（名称、包含“在以下情况下使用...”的描述）
3. 撰写说明（使用项目符号，而非段落）；验证：skills-ref validate ./技能名称
4. 使用AI代理测试，迭代；添加LICENSE，推送至仓库

插件结构（Claude Code）

plugin-name/
├── .claude-plugin/plugin.json
├── README.md, LICENSE, CHANGELOG.md  # CHANGELOG.md tracks versions
├── skills/skill-name/SKILL.md
├── agents/     # Optional: subagents (.md files)
└── examples/   # Optional: full demo projects

区别: 插件examples/= 可运行的项目。技能assets/= 仅静态资源。

批量验证与版本管理

bash scripts/validate-skills-repo.sh     # Validate all skills in repo
bash scripts/bump-changed-plugins.sh     # Auto-bump only changed plugins (semver)

最小示例

---
name: example-skill
description: Brief description. Use when doing X.
---
# Example Skill
## Prerequisites
- Required tools
## Instructions
1. First step: `command`
2. Second step with example
## Troubleshooting
**Error**: Message → **Fix**: Solution

符号链接共享

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

参考文档

• specification.md- 完整的YAML架构，令牌预算
• examples.md- 跨平台的完整示例
• validation.md- 错误排查
• best-practices.md- 高级模式，符号链接设置