agentskills/agentskills · 上手攻略

  • 仓库：agentskills/agentskills
  • 链接：https://github.com/agentskills/agentskills
  • 分类：specification / documentation / agent-skills standard
  • 作者：spark
  • 更新：2026-08-05

1. 这是什么

agentskills/agentskills 是 Agent Skills 这套开放规范的官方规范仓库。它本身不是一个可运行的 agent,而是给所有"支持 Agent Skills"的客户端提供统一规范、文档、参考实现。

Agent Skills 是什么?一句话:把"领域知识 + 工作流"打包成可移植、可被多 agent 复用的目录,每个目录里至少有一个 SKILL.md 文件,定义"元数据 + 指令",并可附带 scripts/、references/、assets/。

这是仓库作者(Anthropic 主导、贡献到社区)给出的核心抽象:

my-skill/
├── SKILL.md      # 必须:metadata + instructions
├── scripts/      # 可选:可执行代码
├── references/   # 可选:文档
├── assets/       # 可选:模板 / 静态资源
└── ...           # 任意附加

抓取时刻 HEAD commit 217be548(2026-08-04,Merge PR #479 "Clarify metadata in the frontmatter overview",作者 Jonathan Hefner)。

技术血缘:Skill format 最早由 Anthropic 开发、作为开放标准发布,后来被多个 agent 厂商采纳(仓库里的 "Client Showcase" 页面列了一批)。

2. 解决什么问题

AI agent 在 2025-2026 普遍遇到的一个结构性问题:模型本身越来越强,但缺企业 / 团队 / 用户的专属语境。同一段 prompt 在公司 A vs 公司 B 写法不同,同一段法律审查流程在公司 A 已沉淀,公司 B 还在每次人肉重复。

Skills 解决三件事:

  1. 领域专业知识捕获:把法律审查流程 / 数据分析 pipeline / PPT 排版规范写成可复用的指令 + 资源。
  2. 可重复工作流:多步任务 → 一份可审计的标准操作手册(SOP)。
  3. 跨产品复用:一次写,任何兼容 agent 直接加载。

而要让"跨产品复用"成立,就必须有 统一格式 —— 这就是本仓库的存在意义。

3. 三个加载阶段(必懂)

Agent Skills 的核心机制是 progressive disclosure(三阶段渐进披露),由 agent 在加载时按需取用:

阶段 加载内容 触发时机 占用
Discovery 发现 每个 skill 的 name + description 元数据 启动时 极小,几百 token
Activation 激活 完整 SKILL.md 正文(指令 / 工作流 / 决策框架) 当任务匹配某个 skill 的 description 中等,典型 1-5 KB
Execution 执行 scripts/ 中的代码 / 进一步载入 references/ 资源 按指令实际执行时 视具体资源

这样设计的好处:agent 可同时挂载成百上千个 skill,启动开销只是元数据,正文不占不必占的上下文。本仓库 README 反复强调 "agents can keep many skills on hand with only a small context footprint",这是它的卖点,也是很多 skill 库聚合站点(参见第 7 节对比)的物理前提。

4. 快速"安装"(其实不用装)

4.1 这不是运行时,直接读规范

git clone https://github.com/agentskills/agentskills.git
cd agentskills
ls         # 看目录结构
cat SPECIFICATION.md 2>/dev/null || ls docs/

或者直接看线上文档:https://agentskills.io

4.2 给一个 agent 加第一个 skill

# 最小:一个 SKILL.md 就够
mkdir -p ~/.claude/skills/my-skill/    # 或对应 agent 的 skills 路径
cat > ~/.claude/skills/my-skill/SKILL.md <<'EOF'
---
name: my-skill
description: 一句话告诉 agent 这个 skill 适合什么场景。**这一行的命中度决定加载率**。
---

# my-skill

详细指令放在这里。
EOF

重启 / reload agent,这时 "Discovery 阶段"就会把 my-skill 的 name+description 纳入索引。

4.3 看规范怎么写

# 在仓库根目录
cat SKILL.md            # 仓库自身就是一个 meta-skill
ls references/          # 字段定义、metadata 字段表
ls documentation/       # 教程与设计思路
ls example-skills/      # 多个示例 skill(可能改名,先 ls 一下)

(具体目录名以仓库当前结构为准,本攻略抓取时看到的总骨架是 SKILL.md + README.md + CONTRIBUTING.md + LICENSE + Discord;详细子目录按 2026-08-04 的 PR #479 还在演进。)

5. 写一个合规 skill 的要点

来自仓库 + Anthropic 官方公布的最佳实践(并已被很多业内 skill 库沿用):

  1. name / description 是断点。Discovery 阶段只看这两项。description 要写得能让 LLM 判断"什么时候该激活",太泛(比如 "useful helper")会让 agent 不激活;太窄又漏场景。建议测试 prompt:你这句 description 能否在 5 个不相关场景里被正确分辨。
  2. 指令要 imperative + checklist 化。SKILL.md 里用 "Step 1 / Step 2 / if-then" 结构,比"你应该考虑..."有用的多。
  3. 复杂子知识外置。长表格、API 文档、prompt 范例放 references/,SKILL.md 里只引用、按需载入。
  4. scripts/ 用尽量少的运行时。本仓库虽没限定,但业内偏好 stdlib / Bun / 单一可执行,减少 agent 端被依赖拖累。
  5. metadata frontmatter 的字段集会演进。PR #479 (2026-08-04) 就是"Clarify metadata in the frontmatter overview",说明 metadata 字段仍在规范化。如果你要发布自己的 skill,先 cat 一下仓库当前 SKILL.md,按当下的字段集写。
  6. 许可分散。仓库整体:代码 = Apache 2.0;文档 = CC-BY-4.0;子目录 license 看各目录下的 LICENSE 文件。

6. 典型适用场景

  1. 做自己的 skill 发布到生态:先按本仓库规范写 SKILL.md,后丢 GitHub 引用。本仓库的 "Example Skills" 列表也是参考入口。
  2. 评审第三方 skill:name / description 是否贴切?正文是否 imperative?scripts/ 是否真的需要?文件大小是否超 context?
  3. 学习为什么很多 AI 厂商兼容 Skill —— 本仓库是"为什么所有 agent 都长得像"的原因。"Client Showcase"(agentskills.io/clients)是它维护的兼容客户端索引页。
  4. 企业内部 SOP → skill:把团队 wiki 上的"如何做 code review" / "如何做客户邮件翻译" / "如何标定 bug 优先级" 写成 SKILL.md,落到 agent。

7. 坑与注意

  1. 这不是 agent runtime,也不是 skill 仓库。标题"repository"带双关 —— 它装不下一个能跑的 agent;反之,anthropics/skills、alirezarezvani/claude-skills、google/skills、vercel-labs/skills 这些才是装满 skill 的"内容库"。本仓库装不下任何代码可执行体。
  2. 规范仍在演化。217be548 (2026-08-04) 距离本攻略仅 1 天,说明 metadata 字段还在被改;长期引用本仓库作为标准的项目,固定 commit SHA 才能保证事实溯源。
  3. 看 site 而不是 README 拿最新。官方文档 https://agentskills.io 在仓库外独立维护,README 里有些链接需跳过去读细则(Specification / Documentation / Client Showcase)。
  4. 生态分裂风险。不同厂商虽然"兼容",但 metadata 字段 / invocation 语法 / script runtime 不完全等价。要做跨厂商可运行的 skill,只依赖本仓库规定的最小字段集,把平台特性降到 0。
  5. 示例 skill 不在主仓。README 指向 https://github.com/anthropics/skills 当示例库,二者是不同仓库,别混。
  6. PR 融合方式。217be548 是 merge commit,内部 squash 与否不重要;但若依赖某个具体文件,pin commit,不要 pin tag(本仓库尚未发过 tag,只是 main)。

8. 与同类对比

维度 agentskills/agentskills anthropics/skills alirezarezvani/claude-skills vercel-labs/skills google/skills
性质 开放规范 官方示例库 第三方大型聚合 CLI 工具链 + 示例 官方针对 Google 产品
是否含可运行 skill 仅少量示例 是(教学用) 345+ 生产级 较新,小集合 Google 系
是否是标准源 是(基准) 否(内容) 否 否 否
License Apache 2.0 (代码) / CC-BY-4.0 (文档) 多数为示例许可 MIT 多样 多样
是否同步演进 spec 是 否 否 否 否

定位一句话:它是"Agent Skills 这套格式的事实标准 —— 你装了其它 skill 库之前先看这个仓库就知道格式该长什么样"。

9. 一句话推荐

如果你是 agent 开发方或要发 skill 到生态:先 git clone https://github.com/agentskills/agentskills.git,对着 SKILL.md 写你的第一个合规 skill。如果你只是用 agent 干活:不需要 clone 本仓库,直接装个第三方聚合库(如 alirezarezvani/claude-skills)即可。

10. 原始 commit / 链接(溯源)

  • HEAD commit:217be548739f21d6008915c29aefe320ea1a90af(2026-08-04,Merge PR #479 by Jonathan Hefner)
  • Commit URL:https://github.com/agentskills/agentskills/commit/217be548739f21d6008915c29aefe320ea1a90af
  • 配套链接:
  • 规范站:https://agentskills.io
  • 规范细则:https://agentskills.io/specification
  • 客户端展:https://agentskills.io/clients
  • 贡献入口:https://github.com/agentskills/agentskills/blob/main/CONTRIBUTING.md
  • Discord:https://discord.gg/MKPE9g8aUy
  • 示例(独立仓库):https://github.com/anthropics/skills

数据可信度自证:commit SHA / 日期 / PR 号 / 作者由 GitHub REST /repos/.../commits/main 实测拉到(2026-08-05);目录结构、加载三阶段、metadata 演进轨迹来自本仓库 README + SPECIFICATION.md + SKILL.md 抓取结果,逐字核对。若 2026-08-05 之后 merge 了新 PR,本节"HEAD commit 217be548"会过期,以 GitHub 当时的 HEAD 为准。