技能使用指南

skill-generator（技能生成器）Skill 是什么？怎么用？

skill-generator（技能生成器）是一个元技能，一条命令即可生成符合 frontmatter 规范、目录结构与资源捆绑约定的 AI 技能脚手架，并内置校验脚本排查格式错误与多余文件。本文详解安装验证、使用方法、竞品对比与典型场景，帮你告别格式幻觉，快速沉淀高质量技能资产。

技能生成器Skillskill-generator
19 个章节 约 17 分钟阅读 AI 智能生成

技能生成器Skill：一句话生成规范的 AI 技能脚手架，让「格式幻觉」彻底消失

  • 它是什么：一个「元技能」——不直接做业务，而是专门用来创建新技能，保证新技能符合 frontmatter 格式、目录结构与资源捆绑约定。
  • 核心能力：一条命令生成完整技能脚手架（SKILL.md + scripts/ + references/ + assets/），并内置校验脚本检查格式与占位符。
  • 最大价值：把「凭记忆写格式」变成「按模板填内容」，避免模型在 YAML frontmatter、目录层级、描述字段上胡编乱造。
  • 适用人群：需要批量沉淀内部技能的团队、把重复工作流固化的独立开发者、为多技能系统做编排的平台工程同学。
  • 上手成本：低。会敲一行 bash 命令就能拿到可用骨架，剩下的只是往骨架里填业务内容。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

该技能的中文名是 技能生成器Skill，英文名 skill-generator，技能 ID 为 11646。它的官方定位写得很明确：这是一个元技能（meta-skill），用于生成具有正确格式和结构的新技能，在「创建群系统的新技能」或「代理需要生成技能脚手架」时使用，确保技能遵循约定（frontmatter 格式、目录结构、捆绑资源）。

它到底解决什么问题？

写过 AI 技能的人几乎都踩过同一批坑：

  1. 格式记不准。YAML frontmatter 到底要哪几个字段？name 和 description 的顺序、缩进、引号怎么处理？手写十次错八次。
  2. 描述字段写废了。description 是技能被发现和触发的关键，但很多人只写「这个技能做什么」，不写「什么时候该触发它」，结果技能装了却从不被调用。
  3. 目录结构各写各的。有人把脚本塞进 references/，有人建了一堆 README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md，把上下文窗口挤满。
  4. 模型自己会「幻觉」格式。让通用大模型「帮我写一个技能」，它经常自信地编出一套并不存在的字段规范。

技能生成器的思路是：格式交给脚手架，内容交给人。它把「约定」固化成脚本和模板，你只需要给出技能名称，剩下的骨架它来搭。

一键安装与生效验证思路

技能生成器运行在技能平台上，具体安装入口与命令因平台而异，以官方说明为准。通用的落地流程可以按下面几步走：

  1. 确认安装前提：本地需要能执行 bash 脚本（macOS / Linux 原生支持，Windows 建议使用 WSL 或 Git Bash）；由于校验脚本以 bun 运行，环境中还需要具备对应的运行时（具体版本要求以官方说明为准）。
  2. 获取并安装技能：通过平台提供的技能安装入口（技能市场、技能管理面板或平台 CLI，以官方说明为准）安装 skill-generator；若为手动部署，则将技能目录放入平台的技能目录。
  3. 验证是否生效：安装完成后，在新会话中让代理「生成一个技能脚手架」，观察它是否会自动引用本技能、并调用 scripts/generate-skill.sh；若能正常触发，说明元数据（name 与 description）已被正确加载。
  4. 跑通一次生成：执行 bash scripts/generate-skill.sh <技能名称> [目标目录]，看到完整目录结构被创建出来，即代表技能可用。

安装完成后，你就拥有了一个「造技能的工具」，用它生成的每一个技能都会自带正确格式。

该技能的主要功能和特点

  • 一条命令生成完整脚手架：执行 bash scripts/generate-skill.sh <技能名称> [目标目录]，即可创建包含 SKILL.md（带正确 frontmatter）、scripts/、references/ 以及遵循约定的占位符内容的完整技能骨架。第二个参数可选，支持指定输出目录，方便把技能直接生成到平台技能目录下。
  • 强制统一 frontmatter 规范：技能内明确了 YAML frontmatter 必须包含 name 与 description，并强调 description 必须写清「技能的功能 + 何时使用它（具体触发条件）+ 激活它的上下文」，直接对标技能发现与触发机制。
  • 内置目录结构约定：给出标准结构树——SKILL.md（必需）、scripts/（可执行代码）、references/（按需加载文档）、assets/（输出用文件），并区分三者的加载行为：脚本通过 bash/python 运行、不进入上下文；references 按需加载；assets 不加载到上下文。
  • 内置「不该建什么」清单：明确禁止创建 README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md。这一条非常有价值——技能是给 AI 代理执行任务用的，不是给人看的项目文档，多余的辅助文档只会污染上下文。
  • 提供校验脚本闭环：生成之后可用 bun scripts/validate-skill.ts 路径/到/技能 进行校验，检查 frontmatter 格式、必需字段是否存在、有无 TODO 占位符、有无多余文件、命名是否合规，把「写完就发」变成「校验再发」。
  • 传授编写方法论：技能内沉淀了三条实操原则——SKILL.md 控制在 500 行以内并把细节下沉到 references/；指令使用命令式（「首先读取文件」✓，「你应该读取文件」✗）；采用三级渐进式披露（元数据约 100 词常驻上下文 → SKILL.md 正文 <5k 词在触发时加载 → 捆绑资源按需无限加载）。

和普通「让大模型帮我写技能」相比强在哪？ 普通做法是生成一段「看起来像技能」的文本，格式是否正确取决于模型的记忆；技能生成器则是生成一套真实可运行的目录与文件，并且附带官方约定的校验器。前者产出的是草稿，后者产出的是可直接投产的工程件。

如何使用该技能？

第 1 步：生成技能骨架

在技能生成器所在目录下执行：

bash scripts/generate-skill.sh 我的新技能

如需指定输出位置：

bash scripts/generate-skill.sh 我的新技能 ./skills/

执行后你会得到如下结构：

我的新技能/
├── SKILL.md（必需）
├── scripts/（可选）
│   └── 示例脚本.sh
├── references/（可选）
│   └── 约定.md
└── assets/（可选）
    └── 模板文件

第 2 步：补全 frontmatter

打开生成的 SKILL.md，把占位内容替换为真实内容，重点是 description：

---
name: 我的新技能
description: 把周报原始素材整理成结构化周报。当用户提到"写周报""汇总本周进展""整理工作记录"时使用，适用于需要按团队模板输出周报的场景。
---

输入示例：一句用户请求「帮我把这周的记录整理成周报」；输出说明：由于 description 中写明了触发条件，代理能在该场景下正确激活技能。

第 3 步：把确定性逻辑放进 scripts/

凡是「同样的代码被反复重写」「可靠性至关重要」的任务，都应当固化为脚本，而不是让模型每次现写。生成后记得赋予执行权限：

chmod +x scripts/我的脚本.sh

脚本通过 bash/python 运行，不加载进上下文，因此不会占用 token。

第 4 步：把长文档放进 references/

数据库模式、API 文档、详细工作流、领域知识都应放进 references/，并在 SKILL.md 中显式指引何时阅读：

参见 references/api文档.md 获取完整 API 参考。

超过 100 行的参考文件建议加上目录。

第 5 步：校验并交付

bun scripts/validate-skill.ts 路径/到/技能

检查项包括 YAML frontmatter 格式、必需字段、无 TODO 占位符、无额外文件、命名约定。全部通过后即可发布或提交到团队技能库。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
技能生成器（skill-generator） 元技能，专造技能 一键生成脚手架、约定化 frontmatter、内置校验脚本、明确禁建文件清单 低：一条 bash 命令 + 一次校验命令 团队批量沉淀技能、平台侧统一规范 优势：格式零幻觉、带校验闭环、约定固化；不足：只解决「骨架与规范」，业务逻辑仍需自己写
手工手写技能目录 完全自建 自己建目录、自己写 YAML 中：需熟记全部约定 一次性、极简单的技能 优势：完全自由；不足：格式易错、描述字段常写废、多人协作风格不统一
通用大模型对话生成 让模型直接「写一个技能」 输出技能文本 低：会提问即可 快速试水、生成文案型内容 优势：上手最快；不足：容易虚构字段规范、目录结构不可控、无校验环节
官方模板仓库 / CLI 工具 通用项目脚手架 提供标准模板与初始化命令 中：需理解模板变量与目录约定 官方生态内的标准技能开发 优势：与平台强绑定、更新及时；不足：模板通常偏通用，缺少「描述字段怎么写才触发」这类方法论提示

选择建议：如果你只做一两个技能、且对格式已很熟，手写也无妨；如果你要在一个团队里持续推进技能资产化，技能生成器这类「生成 + 校验」的组合更稳。

该技能的典型应用场景与实际体验情况

场景一：平台团队批量建设技能库

角色与痛点：平台工程团队要给公司内部沉淀几十个技能，十几个同学分头写，结果 frontmatter 字段五花八门，描述字段有的只写功能不写触发条件，技能装上去却从不被调用。

使用方式：统一用 bash scripts/generate-skill.sh <技能名称> 生成骨架，把「description 必须包含触发场景」写进团队规范，合并前必须通过 validate-skill.ts 校验。

实际体验：上手几乎没有门槛，新同学第一次就能产出格式正确的技能；校验环节把「多余文件」和「TODO 占位符」这两类最常见问题拦在了合并之前。注意点是脚本命名与技能命名要保持一致，否则校验会报命名约定问题。

场景二：独立开发者把重复工作流固化成技能

角色与痛点：一个人反复让模型做同一件事（如整理会议纪要、按模板生成发布说明），每次都要重新描述一遍要求，还经常因为措辞差异导致输出不稳定。

使用方式：先生成技能骨架，把稳定的处理步骤写成命令式指令放进 SKILL.md，把重复出现的确定性代码抽到 scripts/，把详细的输出模板放进 assets/。

实际体验：把「确定性代码」和「上下文指令」分开之后，技能体积明显更小、触发更准。一个容易忽略的细节是：SKILL.md 别写太长，官方建议控制在 500 行以内，长内容一律下沉到 references/，否则每次触发都会吃掉大量上下文。

场景三：知识型团队把领域文档变成可调用技能

角色与痛点：有大量内部规范、API 文档、数据库表结构，希望代理在需要时能查到，但又不想把这些内容常驻上下文。

使用方式：用技能生成器建骨架，把文档全部放进 references/，在 SKILL.md 里写明「参见 references/xxx.md 获取完整参考」，实现按需加载。

实际体验：这正是「渐进式披露」三级加载设计的价值所在——元数据约 100 词常驻，SKILL.md 正文在触发时加载，references 按需读取。体验上要注意：参考文件最好拆得足够聚焦，单一超长文件反而不利于按需加载。

场景四：多技能系统的编排与规范化

角色与痛点：已经有多个技能在跑，但风格不统一、目录结构各异，编排时经常踩「脚本没执行权限」「技能里混进了 README」这类低级问题。

使用方式：新建技能一律从生成器起步，存量技能按同一套约定逐步回炉，用校验脚本做统一体检。

实际体验：治理效果比预想的好，因为「不该建的文件」是白纸黑字写死的清单，团队评审时有据可依。需要注意的是，已有技能改造仍需人工迁移内容，生成器只负责给出正确骨架。

该技能能为用户带来的价值

1. 把格式成本降到接近零。 过去写一个技能，格式摸索和返工往往占掉一半时间；现在骨架由脚本生成，人只需要专注于「这个技能到底要做什么、什么时候被触发」。

2. 显著提升技能的「被调用率」。 技能的 description 对发现和触发至关重要。生成器强制你把「功能 + 触发条件 + 激活上下文」写清楚，从源头上减少了「装了但从不触发」的沉默技能。

3. 降低团队协作的沟通成本。 统一的目录结构、统一的 frontmatter、统一的命名约定，让技能可以像普通代码一样被评审、被复用、被交接。校验脚本则把「风格争论」变成「机器判定」。

4. 控制上下文成本，提升长期可维护性。 通过 scripts/ 不进上下文、references/ 按需加载、assets/ 不加载的三层设计，加上「禁止 README 等辅助文档」的硬约束，技能不会随着迭代越来越臃肿。这对长期运行的多技能系统是实打实的收益。

5. 可量化的收益方向。 团队可以用「单技能从零到通过校验的耗时」「技能首次触发成功率」「因格式问题返工的次数」三个指标衡量收益。经验上，格式类返工是最容易归零的一类成本。

常见问题 FAQ

Q1：这个技能怎么安装？需要什么环境？ 通过技能平台提供的安装入口（技能市场 / 技能管理面板 / 平台 CLI，以官方说明为准）安装 skill-generator。本地需要能运行 bash 脚本；校验命令 bun scripts/validate-skill.ts 需要对应的运行时环境，具体版本要求以官方说明为准。安装后建议先跑一次 generate-skill.sh，能生成完整目录即代表生效。

Q2：它收费吗？ 技能本身的定价与授权方式取决于你所在平台的规则，以官方说明为准。可以先在本地用一条命令生成骨架、跑一次校验，确认符合团队习惯后再决定是否纳入正式流程。

Q3：它适合谁用？ 最适合三类人：一是需要批量建设内部技能库的平台/工具团队；二是把重复工作流固化下来的独立开发者；三是为多技能系统做规范治理的工程同学。如果只是偶尔写一个极简技能，手写也完全够用。

Q4：它和「直接让大模型帮我写一个技能」有什么区别？ 最大区别是产出物形态与是否有校验。大模型给你的是文本，格式正确与否取决于它的记忆，很容易虚构字段或目录结构；技能生成器给你的是真实可运行的目录与文件，并且附带 validate-skill.ts 做格式、必需字段、TODO 占位符、多余文件、命名约定的检查。前者是草稿，后者是工程件。

Q5：生成的技能里为什么不能放 README.md？ 官方约定明确不创建 README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md——技能应只包含 AI 代理执行任务所需的内容，不需要面向人的辅助文档。这类文件既不会被有效利用，还会占用上下文。需要给人看的说明，请放在技能目录之外。

Q6：SKILL.md 写多长合适？ 官方建议控制在 500 行以内。核心工作流程留在 SKILL.md；详细示例、API 文档、长解释一律移到 references/，并在 SKILL.md 中明确指引何时去读。同时坚持命令式写法（「首先读取文件」✓，「你应该读取文件」✗）。