skill-standardization

技能标准化

何时使用此技能

• 从头创建新的 SKILL.md
• 审核现有技能是否符合 Agent Skills 规范
• 修复薄弱的触发描述或过时的路由指引
• 将重复技能规范化为默认技能和兼容别名
• 在添加／重命名／移除／设置别名后，验证仓库级发现机制／目录是否存在偏差
• 大幅改写后，检查 SKILL.toon／SKILL.compact.md 是否存在偏差

指令

步骤 1：选择最小可行模式

使用 references/working-modes.md，并且只选择一种主要模式：

1. 验证或修复一个现有技能
2. 创建或重写 SKILL.md
3. 规范化重复技能
4. 结构性目录／发现机制同步
5. 大幅改写后的衍生内容同步

如果上述某种模式已能满足任务需求，不要一开始就进行大范围混合处理。

步骤 2：运行适用于当前工作目录的验证器命令

对于 jeo-skills 仓库根目录的维护任务，使用：

bash .agent-skills/skill-standardization/scripts/validate_skill.sh .agent-skills/<skill-name>

如果你当前位于 .agent-skills/skill-standardization 内部，请改用 references/working-modes.md 中的技能本地命令。除非当前工作目录确实适用，否则不要将裸 scripts/... 命令复制到仓库根目录的操作手册中。

验证器会检查：

• 必需的 frontmatter（name、description）
• 目录安全命名
• 描述长度和祈使式触发措辞
• 推荐章节
• 文件长度警告

仓库特定的验证器说明：

• validate_skill.sh 应能接受有效的多行 description: > 内容，包括含有普通撇号或类似 shell 文本的内容。如果它仍因文本层面的引号问题而失败，应将其视为需要修复的验证器错误，而不是削弱技能描述的理由。
• 优先修复验证器或添加回归用例，不要为了迎合 shell 解析而改写自然语言。

步骤 3：修复或编写主要的 SKILL.md

创建或重写技能时：

• 让描述以触发条件为导向，并具体说明何时使用该技能
• 在列出边缘情况之前，先明确默认要完成的任务
• 让入口优先用于路由；当示例／检查清单／模板开始挤占主技能空间时，将更新较慢的内容移至 references/
• SKILL.md 不得超过 500 行；如果该技能是高频路由器，最好大幅缩短

使用 references/working-modes.md 中的精简模板和旧标题映射，不要手动复制臃肿的起始模板。

步骤 4：先提升描述质量，再润色其他内容

描述薄弱意味着技能永远不会被触发。使用以下模式：

description: >
  [What it does — list specific operations.]
  Use when [trigger conditions]. Even if the user does not explicitly
  mention [domain keyword] — also triggers on: [synonym list].

描述规则：

1. 使用祈使式措辞——“Use when...”
2. 描述用户意图，而非内部实现
3. 包含边缘触发条件和相近说法
4. 长度少于 1024 个字符
5. 相邻技能应优先处理时，确保路由指引准确

步骤 5：行为发生实质变化时，添加评估用例

新增技能、重写其触发范围或将其缩小为别名时，创建或更新 evals/evals.json。

良好的评估覆盖范围包括：

• 明确应触发该技能的常规提示词
• 应路由至其他技能的近似但不匹配的提示词
• 相关时，用于检查目录／发现机制同步的结构变更提示词
• 当仓库中的 SKILL.toon／SKILL.compact.md 需要考虑时，对精简／发现界面的检查

确保断言具体且可验证。

第 6 步：规范重复项，避免它们相互竞争

当两个技能覆盖的默认任务足够相似，以至于它们的 name + description 元数据会相互竞争时：

1. 选定规范技能
2. 优化规范技能的描述，让它在常规提示词中胜出
3. 如果旧工作流或按确切名称安装仍依赖重叠技能，则将其转换为范围更窄的兼容性别名
4. 为两者添加评测
5. 在同一次变更中同步发现入口，避免用户看到两个看似平级、实则不然的选项
6. 如果别名包含重申规范约定的支持文档或示例，也要更新这些别名侧的文档，避免它们继续宣传调整前的数据包结构

彻底删除通常是后续步骤，而不是第一步。

第 7 步：在新增 / 重命名 / 移除 / 别名调整 / 重大重新定位后运行结构化目录同步

对于 jeo-skills 中仓库级别的偏差，请使用：

python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /Users/jang_jennie/projects/jeo-skills

可移植形式：

python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /path/to/repo

将目录验证器视为一道防护措施，而不是全部工作。它会检查成员、数量和路径的偏差，但不能替代对派生发现文案或精简内容是否仍然准确的人工审查。

第 8 步：重写内容有实质性变化时，同步派生发现入口

如果 SKILL.md 实质性地改变了待完成任务、路由转向或支持的用例，请按需检查并更新：

• 技能本地的 SKILL.toon / SKILL.compact.md
• 镜像规范约定的别名侧支持文档或检查清单
• .agent-skills/skills.json
• .agent-skills/skills.toon
• README.md
• README.ko.md
• setup-all-skills-prompt.md

如果其中某个入口不需要变更，请说明原因。

第 9 步：完成前扫描残留内容

在支持内容较多或结构性重写后，搜索明显的残留内容：

• 过时的文件名或路径
• 已移除的命令示例
• 旧的规范技能与别名表述
• 仍在宣传旧任务的精简内容 / 发现文案

只有结果比基线更准确、更易迁移时，才保留此次改动。

可用脚本

• bash .agent-skills/skill-standardization/scripts/validate_skill.sh <skill-dir> — 验证单个技能
• bash .agent-skills/skill-standardization/scripts/validate_skill.sh --all .agent-skills/ — 批量验证
• python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /path/to/repo — 将实际文件夹与目录 / 发现入口进行比较
• bash .agent-skills/skill-standardization/scripts/regression_folded_description_quotes.sh [repo-root] — 回归检查包含撇号 / 类 Shell 文本的折叠描述

示例

示例 1：从仓库根目录验证一个技能

bash .agent-skills/skill-standardization/scripts/validate_skill.sh .agent-skills/my-skill

示例 2：批量验证整个仓库

bash .agent-skills/skill-standardization/scripts/validate_skill.sh --all .agent-skills/

示例 3：重命名或更改别名后检查目录 / 发现入口同步情况

python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /path/to/repo

在新增、重命名、移除或规范化技能后使用此项，避免清单条目过时、库存数量错误，以及派生入口更新遗漏等问题。

示例 4：修复常见的 frontmatter 问题

# WRONG
metadata:
  tags: [tag1, tag2]
  platforms: Claude

# CORRECT
metadata:
  tags: tag1, tag2
allowed-tools: Bash Read Write

最佳实践

1. 优先保证描述质量 — 描述质量不佳，技能就永远不会被触发
2. 精简高频路由器 — 在入口变成手册之前，将变化较慢的细节移至 references/
3. 使用准确的命令路径 — 明确区分在仓库根目录和技能目录内执行的上下文
4. 保持脚本非交互且结构化 — 优先使用标志和机器可读的输出
5. 发布前添加评估 — 覆盖应触发、不应触发和结构变更场景
6. 将精简版／发现文件视为派生文件 — 重大重写后更新这些文件，否则说明原因
7. 规范重复项，而非增加同级项 — 优先采用一个默认技能加一个兼容别名
8. 规范契约变更时同步别名侧的支持内容 — 如果别名包含清单、参考资料或示例，重述了旧的数据包结构，则应在同一轮更新它们，避免别名悄然保留过时指引
9. 结构重写后扫描残留项 — 即使验证器通过，仍可能残留过时的文件名、命令或发现文案

参考资料

• Agent Skills 规范
• 优化描述
• 评估技能
• 使用脚本
• 添加技能支持