JMBargueno/skanvil

skanvil 是做什么的？

目标

通过 skanvil CLI 管理技能库的变更，确保技能文件夹、SKILL.md 的 frontmatter、README 索引以及库约定保持一致，并且验证始终保持通过状态。

何时激活此技能

• 仓库中包含 .skanvilrc.json、skills/ 文件夹（内含 SKILL.md 文件），或 package.json 中列出了 skanvil。
• 用户请求添加、编写、重命名、移动、修改标题、修改描述、删除、列出、验证或索引技能。
• skanvil validate、npm test 或 CI 因 skanvil 诊断信息而失败。
• 用户希望将一个库中的技能在其他项目中供 Claude Code、GitHub Copilot 或 Codex 使用。

使用说明

1. 熟悉环境

1. 读取 .skanvilrc.json。该文件定义了类别（id、文件夹 prefix、README title、aliases）、必填节区、占位符和规则严重级别。如果文件缺失，则使用默认预设：front-、back-、无前缀的 transversal（默认类别）和 _internal。
2. 运行 npx skanvil list --json 查看每个技能及其类别、README 存在性和有效性。
3. 在进行任何更改之前，运行 npx skanvil validate --json，以便了解哪些问题已经存在。

2. 黄金法则

• 切勿手动重命名、移动或删除技能文件夹，也切勿手动编辑 README 索引。 请使用 skanvil edit，它会保持文件夹、frontmatter name、# 标题 和 README 条目的同步，并在失败时回滚。
• 切勿手动创建技能文件夹。 请使用 skanvil add，它会自动应用类别前缀、模板、frontmatter 元数据和 README 条目。
• 在非交互式 Shell 中始终传递所有选项。 add 需要 --type、--name 和 --description。edit --remove 需要 --yes。否则命令会进行交互提示，或在没有 TTY 时失败。
• 切勿不带参数运行 skanvil 或运行 skanvil wizard。 它们会打开一个为人类设计的交互菜单。请使用下面的显式命令。如果用户偏好菜单，建议他们自己运行 npx skanvil。
• 当需要解析输出时，添加 --json。数据输出到 stdout；警告和错误输出到 stderr。
• 每次更改后运行 npx skanvil validate，并确保结束时没有错误。退出码 1 表示错误，或者在使用 --strict 时表示警告。
• 除非 skanvil 已在 PATH 中，否则在每个命令前加上 npx。使用 -C <路径> 来定位另一个文件夹中的库。

3. 常见任务

创建技能，然后编写其内容。

npx skanvil add --type <类别> --name "<短名称>" \
  --description "<功能描述>. 当 <触发情境> 时使用。"

然后编辑 skills/<前缀><名称>/SKILL.md：

• 填写每个必填节区，内容要具体、可操作。
• 替换所有通用的模板句子。在您完成替换之前，validate 会报告 template-unchanged 警告，并且 validate --strict（用于库的 npm test）会失败。
• 将篇幅较长的材料移动到 references/ 中，并且只链接到实际存在的文件（否则会报告 broken-references）。

如果这些文件夹会保持为空，请使用 --no-scripts、--no-assets 或 --no-references。使用 --template <名称> 来选择 .skanvil/templates/ 中的自定义模板。

重命名或移动技能。

npx skanvil edit <技能> --rename <新名称>          # 前缀会自动重新应用
npx skanvil edit <技能> --type <其他类别>           # 新前缀、新 README 节区、新元数据
npx skanvil edit <技能> --title "<标题>" --description "<文本>"

--rename 接受基础名称：edit front-a --rename b 会产生 front-b。

删除技能。 请先与用户确认；此操作不可恢复。

npx skanvil edit <技能> --remove --yes

修复验证错误。

1. 运行 npx skanvil doctor --fix。它会修复 README 条目、name 不匹配、frontmatter 中的制表符，并将 tools 转换为 allowed-tools。
2. 通过编辑 SKILL.md 修复剩余问题。请参考下面的诊断表。
3. 再次运行 npx skanvil validate。

在更改 .skanvilrc.json 中的类别标题后，重新构建 README 索引：

npx skanvil index          # 重写索引节区
npx skanvil index --check  # 仅验证（CI 中使用）

将技能安装到项目中。

npx skanvil sync <项目目录> -C <库目录> --target claude,copilot --dry-run   # 预览
npx skanvil sync <项目目录> -C <库目录> --target claude,copilot
npx skanvil sync --from @scope/package --target agents                             # 已安装的包

目标平台：

• claude 安装到 .claude/skills；
• copilot 安装到 .github/skills；
• agents 和 codex 安装到 .agents/skills。
• 自定义路径必须是项目内的一个文件夹。
• --global（不带项目目录）会安装到用户的 ~/.claude/skills、~/.copilot/skills 或 ~/.agents/skills。仅当用户要求技能在每个项目中都可用时才使用此选项。

同步行为：

• 它绝不会覆盖非自己安装的文件夹。
• 它会清理从库中移除的技能。
• 除非指定 --force，否则它会跳过存在验证错误的技能。
• 它绝不会发布 _internal 技能。

添加或更改类别。 编辑 .skanvilrc.json 中的 categories：

• 恰好有一个类别设置了 "default": true 且无前缀；
• 其他每个类别都有一个前缀，该前缀是 _ 或是以 - 结尾的 kebab-case；
• 没有哪个前缀可以是另一个前缀的开头。

然后使用 edit --type 移动现有技能，并运行 skanvil index。

4. 编写好的技能内容

• description 要说明技能 做什么 以及 何时 使用，其中包含智能体可能会看到的触发关键词。长度不得超过 1024 个字符。
• name 必须与文件夹名称一致：小写字母、数字和单个连字符，最多 64 个字符。
• 正文： 保持 SKILL.md 在 500 行以内。将指令编写为带编号的、可验证的步骤，并将示例、边缘情况和较长的检查清单放在 references/ 中（深度一级）。
• 占位符： 切勿保留填充文本。任何 validation.placeholders 中列出的条目（待办标记、伪拉丁文本、“待决定”等注释）都会导致验证失败。
• metadata： 仅使用字符串值，因此请对数字加引号，例如 version: "1.0"。
• allowed-tools： 是一个空格分隔的字符串，而不是列表。

5. 诊断与修复对应表

规则	修复方法
readme-missing、readme-orphan、readme-section	npx skanvil doctor --fix
name-matches-folder、name-required	doctor --fix，或者如果文件夹名称错误则使用 edit --rename
frontmatter-tabs、tools-field	doctor --fix
frontmatter	修复 --- 行之间的 YAML（对包含 : 或 # 的值加引号）。
required-sections	添加 validation.requiredSections 中列出的缺失的 ## 节区。
placeholders	用真实内容替换占位符文本。
description-length、max-lines	缩短描述；将详细信息移至 references/。
metadata-format	对非字符串值加引号。
duplicate-name	两个文件夹共享同一个 name：使用 edit --rename 重命名其中一个。
broken-references	创建被引用的文件，或修复链接（路径相对于技能文件夹）。
template-unchanged	将通用的占位符句子重写为特定于技能的操作指令。

有关每个命令的选项、配置模式和 JSON 输出格式，请参见 references/REFERENCE.md。

输出格式

向用户报告：

• 您运行的 skanvil 命令；
• 已创建、更改或删除的技能及其文件夹名称；
• 最终的 skanvil validate 结果（错误和警告），以及任何留给用户决定的事项。

质量标准

• 所有结构性的更改都通过 skanvil add 或 skanvil edit 完成。不存在手动重命名文件夹或编辑 README 索引的情况。
• npx skanvil validate 报告无错误，且 npx skanvil index --check 通过。
• 新创建或编辑的技能具有包含触发器的具体描述，并且没有模板填充内容或占位符。
• 删除操作以及向其他项目同步的操作已与用户确认。