按开放规范编写 Agent Skills

Skill 在你本机可用、同事却用不了，多半是规范问题而非模型问题。Agent Skills 开放标准（agentskills/agentskills 仓库文档）规定了 Agent 期望的最小元数据与目录结构。

本教程说明如何让发现、激活与执行在 Claude Code、Codex、Cursor 等工具上表现一致。

规范要解决什么

磁盘上可以有几十个 Skill，但 Agent 不能启动时把全部正文塞进上下文。标准用渐进披露分三步：

1. 发现 — 启动时只读 name 与 description
2. 激活 — 任务匹配描述时再读完整 SKILL.md
3. 执行 — 按指令操作；可选运行 scripts/ 或读 references/

description 含糊，第 2 步就不会发生。正文过长，第 3 步即使用上也会浪费上下文。

必需目录结构

my-skill/
├── SKILL.md          # 必需
├── scripts/          # 可选
├── references/       # 可选
└── assets/           # 可选模板与示例

SKILL.md 是契约，其余为辅助材料。

最小合法 SKILL.md

---
name: release-notes
description: Generate structured release notes from git history, grouped by conventional commit type
---

## When to activate

The user asks for release notes, a changelog, or "what changed" since a tag or date.

## Instructions

1. Run `git log --oneline` for the requested range.
2. Group commits by prefix (feat, fix, docs, chore).
3. Output Markdown with sections for New Features, Bug Fixes, and Other Changes.
4. Do not invent commits that are not in the log.

两条最关键：

• name — 稳定标识，kebab-case，无空格
• description — 一句话说明「什么任务会用到」，供路由模型匹配

description 不是宣传语，写触发条件，不写「超强」「智能」。

实战：修复「从不激活」的 Skill

磁盘上有 code-review，Agent 却即兴评审。

诊断

常见坏例子：

description: Helps with code

太宽，会和默认行为及其他 Skill 抢上下文。

改写 description 与激活段

description: Review staged git diff for correctness, security, and test gaps; output findings by severity

正文增加：

## When to activate

The user asks for a code review, PR review, or "check my diff" on current changes.
Do NOT activate for writing new features from scratch or generating release notes.

测试

新开会话（发现阶段在启动时运行），然后问：

Review my staged changes for security issues before I commit

Agent 应在推理中点名 Skill，或按你定义的输出结构回复。

实战：用 references 控制体积

要把 40 页内部 API 文档塞进 Skill，全写进 SKILL.md 会让每次激活都很重。

拆分方式：

## Instructions

1. Read references/api-overview.md for authentication rules.
2. Only load references/endpoints/<service>.md when the user names that service.
3. Never guess endpoint paths not present in references/.

my-skill/
├── SKILL.md
└── references/
    ├── api-overview.md
    └── endpoints/
        ├── billing.md
        └── users.md

规范允许在执行阶段再读引用文件，发现阶段保持轻量。

分享前自检表

不确定时对照：agentskills.io/specification。

规范对齐 vs 随意写法

只有一个 Skill、只有你一个人用时，随意写法往往还能跑；第二个 Skill 或第二个同事加入后，冲突和上下文膨胀就会暴露。

技巧

• 生态入门读 Agent Skills 101，多工具发布前用本篇校对结构。
• 参考 anthropics/skills 官方示例。
• 用 git 管理 Skill，把 SKILL.md 变更当 API 变更对待。
• 本地验证通过后，用 npx skills 分发。

何时不必上完整结构

个人偏好类一行规则（「始终用 tab」）不必建 references/ 和脚本。仍建议 name、description 准确，便于日后扩展。

浏览符合规范的 Skill 见 SkillMap 排行榜。