skill-standardization

用途

Skill Standardization 用于按照 Agent Skills 规范（agentskills.io）标准化和校验 SKILL.md 文件。它面向技能作者与维护者，帮助在创建、重写、审计或整理技能时保持结构、描述与仓库发现面的一致性。

主要能力

• 校验单个或批量 SKILL.md 是否符合规范，包括必需 frontmatter（name、description）、目录安全命名、描述长度与祈使式触发措辞、推荐章节以及文件长度警告。
• 创建或重写 SKILL.md，保持描述面向触发、默认任务清晰，并将变化较慢的示例、清单和模板移入 references/。
• 改进描述质量，使用“Use when...”祈使句式，描述用户意图而非内部实现，包含边缘触发与近义关键词，控制在 1024 字符以内。
• 在行为发生实质变化时补充评测（evals/evals.json），覆盖应触发、不应触发以及结构变化场景。
• 将重复技能规范化为一个默认技能加一个窄范围兼容别名，避免两个技能在名称与描述元数据上相互竞争。
• 在新增、重命名、删除、别名或重大重定位后执行仓库级目录与发现同步校验。
• 在实质重写后同步派生发现面，如 SKILL.toon、SKILL.compact.md、skills.json、skills.toon、README 等。
• 收尾前进行残留扫描，查找过时文件名、路径、已移除命令示例、旧规范与别名措辞等。

使用方式

技能提供分步指令，建议先选择最小工作模式，只选一个主要模式：校验或修复单个已有技能、创建或重写 SKILL.md、规范化重复技能、结构目录与发现同步、实质重写后的派生面同步。

校验命令示例：

• 单个技能：bash .agent-skills/skill-standardization/scripts/validate_skill.sh .agent-skills/<skill-name>
• 批量校验：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]

描述推荐模式：

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].

frontmatter 修正示例：

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

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

适用场景

• 从零创建新的 SKILL.md。
• 审计已有技能是否符合 Agent Skills 规范。
• 修复薄弱的触发描述或过时的路由。
• 将重复技能规范化为默认技能加兼容别名。
• 在新增、重命名、删除或别名操作后校验仓库级发现与目录漂移。
• 在实质重写后审查 SKILL.toon / SKILL.compact.md 漂移。

限制

• 目录校验器仅作为护栏，检查成员、数量与路径漂移，不替代对派生发现措辞或紧凑新鲜度的人工审查。
• 校验器预期能接受包含普通撇号或类 shell 文本的合法多行 description: > 块；若仍因散文级引号失败，应视为校验器缺陷修复，而非削弱技能描述。
• 硬删除通常是后续步骤，而非第一步。
• 若某个派生发现面无需变更，应能解释原因。
• 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。