Back to Details

heal-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<objective> Diagnose and auto-repair broken skills. Run `/heal-skill` for a full library scan or `/heal-skill <name>` for a single skill diagnosis. Reports issues by severity with health scoring and offers auto-fixes with user confirmation. </objective>
<quick_start>
/heal-skill              → Full library scan (all skills)
/heal-skill <name>       → Single skill diagnosis
/heal-skill --fix        → Apply all auto-fixes (with confirmation)
/heal-skill --fix <name> → Fix single skill (with confirmation)
</quick_start>
<success_criteria>
  • All YAML frontmatter validates against Anthropic spec
  • All required XML sections present (
    <objective>
    , 
    <quick_start>
    , 
    <success_criteria>
    )
  • All config.json files use standard schema with correct keys
  • Health score reported: X/Y checks passing per skill
  • Auto-fixes applied ONLY with user confirmation (preview diff first)
  • Self-test passes: 
    /heal-skill heal-skill
    reports 0 issues </success_criteria>
<core_content>
<objective> 诊断并自动修复损坏的Skill。运行`/heal-skill`进行全技能库扫描，或运行`/heal-skill <name>`诊断单个Skill。按严重程度报告问题并给出健康评分，在获得用户确认后提供自动修复选项。 </objective>
<quick_start>
/heal-skill              → 全技能库扫描（所有Skill）
/heal-skill <name>       → 单个Skill诊断
/heal-skill --fix        → 应用所有自动修复（需确认）
/heal-skill --fix <name> → 修复单个Skill（需确认）
</quick_start>
<success_criteria>
  • 所有YAML前置元数据符合Anthropic规范
  • 所有必填XML章节齐全（
    <objective>
    、
    <quick_start>
    、
    <success_criteria>
    ）
  • 所有config.json文件使用标准schema且键值正确
  • 报告健康评分：每个Skill通过X/Y项检查
  • 仅在获得用户确认后应用自动修复（先预览差异）
  • 自检通过：
    /heal-skill heal-skill
    报告0个问题 </success_criteria>
<core_content>

3-Layer Diagnostic Engine

三层诊断引擎

The engine runs checks in order of severity. Each layer builds on the previous.
Layer 1: STRUCTURAL (CRITICAL)     → Files exist, YAML parses, required fields present
Layer 2: CONTENT (HIGH)            → XML sections, line count, naming conventions
Layer 3: INTEGRATION (MEDIUM)      → config.json schema, duplicate triggers, cross-refs
引擎按严重程度顺序运行检查，每一层都基于前一层的结果。
Layer 1: STRUCTURAL (CRITICAL)     → 文件存在、YAML可解析、必填字段齐全
Layer 2: CONTENT (HIGH)            → XML章节、行数、命名规范
Layer 3: INTEGRATION (MEDIUM)      → config.json schema、重复触发条件、交叉引用

Layer 1: Structural Validation (CRITICAL)

第一层：结构验证（CRITICAL，严重）

These checks verify the skill can even load. Failures here mean the skill is broken.
IDCheckRuleAuto-fix
S1YAML frontmatter existsSKILL.md starts with 
---
No
S2
name
field present		Required, non-empty stringNo
S3
name
format valid
^[a-z0-9-]+$
, max 64 chars		Yes — slugify
S4
description
field present		Required, non-empty stringNo
S5
description
length		Max 1024 charsYes — truncate
S6
description
has no XML tags		No 
<tags>
in value		Yes — strip tags
S7
description
is a string		Not YAML array/objectYes — join if array
S8SKILL.md existsMust exist in skill directoryNo
S9config.json existsMust exist in skill directoryYes — generate from SKILL.md
S10config.json is valid JSONMust parse without errorNo
Detection for S1-S2: Read first 5 lines; check 
---
delimiter and 
name:
key. Detection for S3: Regex 
^[a-z0-9-]+$
on name value, check 
length <= 64
. Detection for S6: Regex 
<[a-z_]+>
in description value. Detection for S7: YAML parse — check type is string, not array/object.
这些检查用于验证Skill是否能正常加载。此处失败意味着Skill已损坏。
ID检查项规则自动修复
S1YAML前置元数据存在SKILL.md以
---
开头		否
S2存在
name
字段		必填，非空字符串否
S3
name
格式有效		符合
^[a-z0-9-]+$
，最长64字符		是 — 转换为slug格式
S4存在
description
字段		必填，非空字符串否
S5
description
长度		最长1024字符是 — 截断
S6
description
无XML标签		值中不含
<tags>
是 — 移除标签
S7
description
为字符串类型		不是YAML数组/对象是 — 若为数组则拼接
S8SKILL.md存在必须在Skill目录中否
S9config.json存在必须在Skill目录中是 — 从SKILL.md生成
S10config.json是有效JSON可正常解析无错误否
S1-S2检测方式： 读取前5行；检查
---
分隔符和
name:
键。 S3检测方式： 对name值使用正则
^[a-z0-9-]+$
校验，检查
length <= 64
。 S6检测方式： 在description值中匹配正则
<[a-z_]+>
。 S7检测方式： 解析YAML — 检查类型为字符串，而非数组/对象。

Layer 2: Content Quality (HIGH)

第二层：内容质量（HIGH，高）

These checks verify the skill follows library conventions for discoverability.
IDCheckRuleAuto-fix
C1
<objective>
section exists		Must be present in SKILL.md bodyYes — add stub
C2
<quick_start>
section exists		Must be present in SKILL.md bodyYes — add stub
C3
<success_criteria>
section exists		Must be present in SKILL.md bodyYes — add stub
C4Line countBody ≤ 500 lines (warning only)Warning
C5Dead reference linksInternal 
reference/
links must resolve		Yes — remove dead
C6Naming conventionDirectory ends with 
-skill
Warning
Detection for C1-C3: Search SKILL.md body (after frontmatter) for 
<objective>
, 
<quick_start>
, 
<success_criteria>
. Detection for C4: 
wc -l SKILL.md
. Detection for C5: Extract paths from 
[text](reference/...)
links, verify file exists. Detection for C6: Check directory name ends with 
-skill
.
这些检查用于验证Skill是否遵循技能库规范，以确保可发现性。
ID检查项规则自动修复
C1存在
<objective>
章节		必须在SKILL.md正文中是 — 添加占位符
C2存在
<quick_start>
章节		必须在SKILL.md正文中是 — 添加占位符
C3存在
<success_criteria>
章节		必须在SKILL.md正文中是 — 添加占位符
C4行数正文≤500行（仅警告）警告
C5无效引用链接内部
reference/
链接必须可解析		是 — 移除无效链接
C6命名规范目录以
-skill
结尾		警告
C1-C3检测方式： 在SKILL.md正文（前置元数据之后）中搜索
<objective>
、
<quick_start>
、
<success_criteria>
。 C4检测方式： 执行
wc -l SKILL.md
统计行数。 C5检测方式： 提取
[text](reference/...)
链接中的路径，验证文件是否存在。 C6检测方式： 检查目录名称是否以
-skill
结尾。

Layer 3: Integration Health (MEDIUM)

第三层：集成健康度（MEDIUM，中）

These checks verify consistency across the library.
IDCheckRuleAuto-fix
I1config.json has standard keysMust have 
name
, 
version
, 
category
Yes — add missing
I2Uses 
activation_triggers
key		Not 
triggers
(legacy name)		Yes — rename key
I3Uses 
depends_on
key		Not 
dependencies
(legacy name)		Yes — rename key
I4Has 
version
field		Must have 
version
string		Yes — add "1.0.0"
I5No duplicate activation triggersNo trigger collisions across skillsWarning
Detection for I2: Check if config.json has key 
triggers
instead of 
activation_triggers
. Detection for I3: Check if config.json has key 
dependencies
instead of 
depends_on
.
这些检查用于验证技能库中的一致性。
ID检查项规则自动修复
I1config.json包含标准键必须包含
name
、
version
、
category
是 — 添加缺失的键
I2使用
activation_triggers
键		不使用旧版名称
triggers
是 — 重命名键
I3使用
depends_on
键		不使用旧版名称
dependencies
是 — 重命名键
I4包含
version
字段		必须有
version
字符串		是 — 添加"1.0.0"
I5无重复激活触发条件不同Skill之间无触发条件冲突警告
I2检测方式： 检查config.json是否使用旧版键
triggers
而非
activation_triggers
。 I3检测方式： 检查config.json是否使用旧版键
dependencies
而非
depends_on
。

Diagnostic Flow

诊断流程

1. DISCOVER
   - Scan active/ and stable/ directories
   - Build skill inventory (name, path, has SKILL.md, has config.json)

2. LAYER 1 — STRUCTURAL
   - For each skill: parse YAML frontmatter, validate fields
   - STOP on critical failures (no SKILL.md = skip remaining checks)

3. LAYER 2 — CONTENT
   - For each skill: search for XML sections, check line count
   - Check naming convention

4. LAYER 3 — INTEGRATION
   - For each skill: validate config.json schema
   - Cross-skill: check for duplicate triggers

5. REPORT
   - Generate health report grouped by severity
   - Calculate health score
   - List available auto-fixes
1. 发现
   - 扫描active/和stable/目录
   - 构建Skill清单（名称、路径、是否有SKILL.md、是否有config.json）

2. 第一层 — 结构
   - 对每个Skill：解析YAML前置元数据，验证字段
   - 若出现严重失败则停止（无SKILL.md则跳过后续检查）

3. 第二层 — 内容
   - 对每个Skill：搜索XML章节，检查行数
   - 检查命名规范

4. 第三层 — 集成
   - 对每个Skill：验证config.json schema
   - 跨Skill：检查是否有重复触发条件

5. 报告
   - 按严重程度分组生成健康报告
   - 计算健康评分
   - 列出可用的自动修复选项

Output Format

输出格式

Generate the report in this exact format:
SKILL HEALTH REPORT
════════════════════════════════════════════════
Scanned: X skills | Health Score: Y/Z (N%)

CRITICAL (n):
  ✗ skill-name: Description of issue [CHECK-ID]

HIGH (n):
  ⚠ skill-name: Description of issue [CHECK-ID]

MEDIUM (n):
  ℹ skill-name: Description of issue [CHECK-ID]

WARNINGS (n):
  ~ skill-name: Description of advisory [CHECK-ID]

════════════════════════════════════════════════
AUTO-FIX AVAILABLE: N issues can be auto-fixed
  Run /heal-skill --fix to preview and apply
Single skill mode — same format but for one skill only.
Severity definitions:
  • CRITICAL: Skill cannot load or activate (S1-S10 failures)
  • HIGH: Skill loads but missing expected sections (C1-C3)
  • MEDIUM: Schema inconsistencies that affect library tooling (I1-I5)
  • WARNING: Advisory only, no action required (C4, C6)
请严格按照以下格式生成报告：
SKILL HEALTH REPORT
════════════════════════════════════════════════
已扫描：X个Skill | 健康评分：Y/Z（N%）

严重问题（n）：
  ✗ skill-name: 问题描述 [检查项ID]

高优先级问题（n）：
  ⚠ skill-name: 问题描述 [检查项ID]

中优先级问题（n）：
  ℹ skill-name: 问题描述 [检查项ID]

警告（n）：
  ~ skill-name: 建议说明 [检查项ID]

════════════════════════════════════════════════
可自动修复：N个问题可自动修复
  运行 /heal-skill --fix 预览并应用修复
单个Skill模式 — 格式相同，但仅针对一个Skill。
严重程度定义：
  • 严重问题（CRITICAL）： Skill无法加载或激活（S1-S10检查失败）
  • 高优先级问题（HIGH）： Skill可加载但缺失预期章节（C1-C3）
  • 中优先级问题（MEDIUM）： Schema不一致，影响技能库工具（I1-I5）
  • 警告（WARNING）： 仅为建议，无需立即处理（C4、C6）

Auto-Fix Protocol

自动修复协议

When 
--fix
is specified, follow this exact protocol:
1. PREVIEW
   - Show each proposed change as a diff:
     ```
     FIX: skill-name — [CHECK-ID] Description
     --- before
     +++ after
     @@ change description @@
     -old content
     +new content
     ```

2. CONFIRM
   - Ask user: "Apply N fixes? (yes/no/select)"
   - "select" lets user pick individual fixes

3. APPLY
   - Make changes to files
   - Re-run affected checks to verify fix worked

4. RE-VALIDATE
   - Run full scan on fixed skills
   - Report new health score
Auto-fix strategies by check:
CheckFix Strategy
S3Slugify: lowercase, replace spaces/special chars with hyphens
S5Truncate to 1024 chars at last sentence boundary
S6Strip XML tags with regex: 
</?[a-z_]+>
→ empty string
S7If array: join elements with ". ". If object: use first value
S9Generate minimal config.json from SKILL.md frontmatter
C1Add 
<objective>\nTODO: Add objective\n</objective>
after frontmatter
C2Add 
<quick_start>\nTODO: Add quick start\n</quick_start>
after objective
C3Add 
<success_criteria>\nTODO: Add success criteria\n</success_criteria>
after quick_start
C5Remove dead 
[text](reference/...)
links
I1Add missing keys with defaults from SKILL.md frontmatter
I2Rename 
triggers
→ 
activation_triggers
in config.json
I3Rename 
dependencies
→ 
depends_on
in config.json
I4Add 
"version": "1.0.0"
to config.json
当指定
--fix
参数时，请严格遵循以下协议：
1. 预览
   - 以差异形式展示每个拟议更改：
     ```
     修复：skill-name — [检查项ID] 描述
     --- 修复前
     +++ 修复后
     @@ 更改描述 @@
     -旧内容
     +新内容
     ```

2. 确认
   - 询问用户：“是否应用N个修复？（是/否/选择）”
   - “选择”选项允许用户挑选单个修复项

3. 应用
   - 修改文件
   - 重新运行受影响的检查以验证修复效果

4. 重新验证
   - 对已修复的Skill运行完整扫描
   - 报告新的健康评分
各检查项的自动修复策略：
检查项修复策略
S3转换为slug格式：小写，将空格/特殊字符替换为连字符
S5在最后一个句子边界处截断至1024字符
S6使用正则移除XML标签：
</?[a-z_]+>
→ 空字符串
S7若为数组：用“. ”拼接元素。若为对象：使用第一个值
S9从SKILL.md前置元数据生成最简config.json
C1在前置元数据后添加
<objective>\nTODO: 添加目标\n</objective>
C2在目标章节后添加
<quick_start>\nTODO: 添加快速开始\n</quick_start>
C3在快速开始章节后添加
<success_criteria>\nTODO: 添加成功标准\n</success_criteria>
C5移除无效的
[text](reference/...)
链接
I1从SKILL.md前置元数据添加缺失的键及默认值
I2在config.json中将
triggers
重命名为
activation_triggers
I3在config.json中将
dependencies
重命名为
depends_on
I4在config.json中添加
"version": "1.0.0"

Known Issue Patterns

已知问题模式

These patterns come from real GitHub issues and library audits. The diagnostic engine checks for all of them.
SourcePatternCheck
GitHub #9817Whitespace before 
---
prevents YAML parse		S1
GitHub #11322Prettier reformats description to multi-lineS7
GitHub #17604YAML array in description crashes slash commandsS7
GitHub #6377Missing 
name
field despite valid YAML structure		S2
GitHub #14882Skills consume full tokens (no progressive disclosure)C4
GitHub #14577
/skills
shows "No skills found" — frontmatter parse failure		S1, S2
Library audit8 skills missing XML sectionsC1-C3
Library audit9 skills using legacy config.json keysI2, I3
Library audit1 skill missing 
-skill
suffix		C6
</core_content>
<common_mistakes>
这些模式来自真实的GitHub问题和技能库审计结果。诊断引擎会检查所有这些模式。
来源模式检查项
GitHub #9817
---
前的空白导致YAML解析失败		S1
GitHub #11322Prettier将description格式化为多行S7
GitHub #17604description中的YAML数组导致斜杠命令崩溃S7
GitHub #6377尽管YAML结构有效，但缺失
name
字段		S2
GitHub #14882Skill占用全部令牌（无渐进式披露）C4
GitHub #14577
/skills
显示“未找到Skill” — 前置元数据解析失败		S1, S2
技能库审计8个Skill缺失XML章节C1-C3
技能库审计9个Skill使用旧版config.json键I2, I3
技能库审计1个Skill缺失
-skill
后缀		C6
</core_content>
<common_mistakes>

What Goes Wrong

常见问题

MistakeFix
Running 
--fix
without reviewing diffs		Always preview first. The protocol requires confirmation.
Ignoring WARNINGSWarnings are advisory but indicate tech debt. Track them.
Fixing only CRITICAL issuesHIGH and MEDIUM issues affect discoverability and tooling. Fix all layers.
Adding XML stubs without filling them inStubs are placeholders. Schedule time to write real content.
Running heal on a single skill when library-wide issues existRun full scan first to see the big picture.
</common_mistakes>
错误修复方案
未查看差异就运行
--fix
始终先预览。协议要求必须确认。
忽略警告警告虽为建议，但表明存在技术债务。需跟踪处理。
仅修复严重问题高优先级和中优先级问题会影响可发现性和工具使用。需修复所有层级的问题。
添加XML占位符但未填充内容占位符仅为临时方案。需安排时间编写真实内容。
当存在全库问题时仅诊断单个Skill先运行全扫描以了解整体情况。
</common_mistakes>