什么是 Agent Skill
Skill 是一个文件夹。最少只要一份 SKILL.md，里面写清「这个技能在解决什么问题」「Agent 应该在什么场景下调用它」「具体怎么做」。可以再附上 scripts/（脚本）、references/（参考资料）、assets/（模板）。这套格式由 Anthropic 提出并开放为标准（agentskills.io），目前已被 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Goose、GitHub Copilot 等 30 多家 Agent 产品采纳。
一个 Skill 的目录结构
只有 SKILL.md 是必须的，其他全部按需添加。Codex 还会读取可选的 agents/openai.yaml 来配置 UI 显示、调用策略和工具依赖。
my-skill/
├── SKILL.md # 必须 · 元数据 + 指令
├── scripts/ # 可选 · 可执行代码
├── references/ # 可选 · 参考文档
├── assets/ # 可选 · 模板与素材
└── agents/openai.yaml # 可选 · Codex 专用 UI/策略SKILL.md frontmatter 字段
所有字段写在 Markdown 文件顶部的 --- 之间。规范硬性要求只有 `name` 和 `description`，其余字段属于本站审计加分项或社区惯例。`description` 建议控制在 140 字以内，因为它会进入 Agent 启动时的渐进披露摘要；只有匹配上这条描述，Agent 才会读取完整正文。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 技能 slug，需匹配文件夹名，全小写带连字符 |
description | string ≤ 140 | 是 | 一句话说明「什么时候该 / 不该调用这个技能」 |
category | enum | 否 | 所属分类：engineering · ai · productivity · design · devops · documentation · writing · data · security · other |
license | SPDX | 否 | 许可证标识符，建议显式声明（+6 审计分） |
version | semver | 否 | 语义化版本号，便于变更追踪（+4 审计分） |
agents | string[] | 否 | 兼容的 Agent ID 列表，决定详情页生成几条安装命令 |
allowed-tools | string[] | 否 | 声明这个技能用到的工具（Bash、Read 等），未声明等于全部允许 |
tags | string[] | 否 | 检索关键词，会进搜索 haystack |
渐进披露：Agent 怎么用 Skill
Agent 启动时只读取每个 Skill 的 name + description（约几十个 token），整体不超过 1KB 上下文。当用户的请求与某条 description 匹配，Agent 才把对应 SKILL.md 全文读进来；如果中途需要执行脚本，再去 scripts/ 目录加载。这套机制让一个 Agent 可以同时挂载几百个 Skill 而不爆上下文。
- 01 发现
只读 name + description，每个 skill 几十 token
- 02 激活
匹配上才拉取 SKILL.md 全文
- 03 执行
按需加载 scripts/ 与 references/
安装位置：4 种作用域
不同 Agent 使用的目录略有差异，但作用域语义一致：SYSTEM 由 Agent 厂商内置；ADMIN 由组织管理员推送；USER 是当前用户的个人技能库；REPO 跟着仓库走，团队共享。本站抓取覆盖前三类的公开 SKILL.md，不会读取你本地的私有技能。
| 作用域 | 路径 | 说明 |
|---|---|---|
SYSTEM | 随 Agent 安装包内置 | 由 Agent 厂商打包，最新版 Codex 自动启用 .system 目录 |
ADMIN | /etc/codex/skills · 类似企业策略 | 组织管理员推送的合规技能集，覆盖个人配置 |
USER | ~/.claude/skills · ~/.codex/skills · ~/.agents/skills | 当前用户的个人技能库，跨项目共享 |
REPO | $REPO/.agents/skills · $CWD/.claude/skills | 仓库内置技能，跟随分支与团队走 |
在各 Agent 里安装 Skill
技能详情页只为安装器已验证支持的 Agent 给出单行命令，统一使用公开的 skills CLI 与明确的目标 Agent 参数。未验证的 Agent 仍保留兼容性资料，但不会生成看似可复制的占位命令。
读懂审计结果
兼容期仍保留 0–100 legacy audit score 与 verified / community / unverified / flagged 分类，但它们只描述旧静态审计层，不代表来源可信、运行安全、跨平台兼容、真实运行测试或真人复核。详情页会把 Source、Spec validation、Static scan、Compatibility、Runtime、Human review 分层展示。
公开接口
公开站点当前提供只读的技能浏览、搜索与打包下载。写入型 Webhook 和 MCP 服务尚未对外开放；开放前会补齐鉴权、密钥清洗、限流和审计证据。
隐私与数据
浏览和安装无须登录，当前站点不发送浏览或停留时长遥测。索引里的技能数据来自公开 GitHub 仓库，并保留上游作者与来源链接。
编写原则：从真实链路沉淀
不要把 Skill 写成一段漂亮提示词。更稳定的做法是先让 Agent 在真实文件、真实环境和真实目标下跑通一次，记录输入假设、工具顺序、失败恢复、验证命令和输出格式，再压缩成可审核的工作流。正文只保留会影响执行路径的关键判断；长资料进入 references，重复且确定的动作进入 scripts，模板和样例进入 assets。
质量闭环：先审计，再测试，再迭代
复用别人的 Skill 时，星标只能作为发现线索，不能当作质量证明。安装前要完整阅读 SKILL.md、参考资料、脚本、素材和依赖说明，检查密钥、私有路径、联网、删除、发布、全局配置等风险。自己写 Skill 时要准备应触发、不应触发、应停止三类测试；一次失败只是线索，不要立刻写成狭窄特判，先比较多个真实样例，再决定改 description、正文、脚本还是参考资料。