前言¶
在 Cursor、Claude Code、Gemini CLI 等环境里给 Agent 加「专项能力」，常见做法是写一长段系统提示或项目规则。提示会越堆越长，换工具就要重写，也很难用版本管理做评审。Agent Skills 把能力收成可移植的文件夹：元数据加说明文档，必要时附带脚本与参考资料。问题是规范里有不少硬性约定——目录怎么命名、SKILL.md 要写哪些节、代码示例该放哪里、发布前如何校验。meta-skill-creator 是一套面向「写 Skill 的人」的 Meta Skill：它按 Agent Skills 开放标准 梳理完整流程，适合作为理解 Skill 生态的入门材料。
这是什么¶
meta-skill-creator 由 oakoss 维护，仓库路径为 oakoss/agent-skills/skills/meta-skill-creator，许可为 MIT，Skill 元数据版本为 1.0，规范来源标注为 agentskills.io。
它的定位是：在 Claude Code、Cursor、Gemini CLI 及其他兼容 Agent 上，指导你完成新 Skill 的创建、结构设计与验证。覆盖 Skill 结构、SKILL.md 撰写、frontmatter 配置、渐进式披露、reference 文件、校验与分发等环节。Skill 自身设置了 disable-model-invocation: true，表示由人在合适场景下启用，而不是默认让模型随意调用。
根据 Agent Skills 概览，Skill 本质是包含 SKILL.md 的文件夹，可附带 scripts/、references/、assets/ 等；Agent 通过渐进式披露按需加载，从而在保留大量 Skill 的同时控制上下文占用。
核心功能¶
下面介绍 meta-skill-creator 在资料中明确列出的能力要点。
目录与必需文件¶
标准结构以 skill-name/SKILL.md 为核心，可选目录包括 references/、scripts/、assets/。唯一必需文件是 SKILL.md。
Frontmatter 与命名¶
必填 YAML 字段为 name 与 description：name 必须与父目录名完全一致，最长 64 字符；命名仅允许小写字母、数字与连字符，不得出现 --，不得以 - 开头或结尾，最少 4 个字符。可选字段包括 license、compatibility、metadata、allowed-tools 等，由开放标准定义，便于跨 Agent 移植。部分 Agent 专有扩展（如 model、context、hooks）在资料中标注为不可移植。
description 应包含 “Use when…” 或 “Use for…” 等触发短语，用第三人称、关键词丰富的写法，便于 Agent 发现何时启用该 Skill。
SKILL.md 结构与篇幅¶
SKILL.md 须包含五个固定章节：Overview、Quick Reference、Common Mistakes、Delegation、References。目标篇幅约 100–150 行，上限 500 行；不在 SKILL.md 内放代码示例，示例应拆到 references/。
渐进式披露分三层：元数据 → 指令正文 → 资源文件；SKILL.md 全文在激活时加载，reference 按需读取。
Reference 与脚本¶
references/[topic].md 每个文件建议自包含、从 SKILL.md 仅一层链接，单文件上限 500 行，且需带 frontmatter：title、description、tags。scripts/ 下放可执行代码；Agent 执行脚本而非通读源码。
分发时排除的文件名包括 README.md、metadata.json 以及以 _ 开头的文件。
校验与协作分工¶
发布前应运行项目自带校验器或 skills-ref validate。规范细节可查 Agent Skills specification；需要对照现有 Skill 结构时，资料建议用 Explore 类 Agent 做模式发现。
安装与启用¶
Skill 可按作用域放在不同路径（资料中的示例如下，具体产品是否完全一致以各客户端文档为准）：
| 作用域 | 路径 | 说明 |
|---|---|---|
| 个人 | ~/.claude/skills/ |
当前用户、所有项目 |
| 项目 | .claude/skills/ |
仓库内共享 |
| 分发 | 通过 skills CLI |
插件或包用户 |
将 meta-skill-creator 作为文件夹安装到上述兼容目录后，在 Cursor 等客户端中按产品说明启用 Skills 即可。资料未给出单独的 git clone 或一键安装命令，获取源码以官方仓库为准。
典型用法：创建新 Skill 的工作流¶
官方在 Skill 内归纳的五步流程可直接复现：
- 在合适位置新建目录，并创建
SKILL.md。 - 编写 frontmatter：
name与目录名一致，description写清触发场景。 - 写完五个必需章节（Overview、Quick Reference、Common Mistakes、Delegation、References）。
- 把代码示例抽到
references/，保持SKILL.md无代码块示例。 - 用
skills-ref validate或项目校验器验证后再分发。
frontmatter 示例（字段含义见上文，此处仅示意结构）：
---
name: my-skill-name
description: >
Short summary of what the skill does.
Use when ...
Use for ...
license: MIT
metadata:
author: your-name
version: '1.0'
---
校验示例：
skills-ref validate
meta-skill-creator 还通过 references/ 链接更细的说明，例如 skill-anatomy、frontmatter、validation 等主题，写 Skill 时可按需让 Agent 加载对应 reference。
适用场景与注意¶
适合谁： 要在多 Agent 环境复用同一套工作流说明的开发者；团队希望把流程、检查清单、脚本打包成可版本管理的 Skill；需要系统了解 agentskills.io 规范而非凭感觉写 Markdown 的人。
常见错误（资料中的对照表）： 缺少 “Use when/for” 触发语；在 SKILL.md 里写代码；reference 互相深层嵌套；name 与目录不一致；frontmatter 第一行前有空行；reference 缺少 title/description/tags；未在 SKILL.md 中显式链接支撑文件。
限制： 开放标准字段与 Claude Code 等扩展字段需区分，避免不可移植配置。SKILL.md 行数与 reference 深度、自包含性都有硬性建议，忽视后可能导致校验失败或 Agent 加载不全。资料称兼容 27+ Agent 客户端，具体支持列表以 agentskills.io 的 Client Showcase 为准。
结尾¶
meta-skill-creator 的价值在于把「教 Agent 做事」收敛成可检验的文件夹规范：结构、触发描述、渐进披露和校验步骤都写死在流程里，减少各工具各写一套说明的重复劳动。若要上手或对照规范，可从官方仓库阅读完整 SKILL.md 与 reference：https://github.com/oakoss/agent-skills/tree/main/skills/meta-skill-creator。
