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.

ID	Check	Rule	Auto-fix
S1	YAML frontmatter exists	SKILL.md starts with `---`	No
S2	`name` field present	Required, non-empty string	No
S3	`name` format valid	`^[a-z0-9-]+$` , max 64 chars	Yes — slugify
S4	`description` field present	Required, non-empty string	No
S5	`description` length	Max 1024 chars	Yes — truncate
S6	`description` has no XML tags	No `<tags>` in value	Yes — strip tags
S7	`description` is a string	Not YAML array/object	Yes — join if array
S8	SKILL.md exists	Must exist in skill directory	No
S9	config.json exists	Must exist in skill directory	Yes — generate from SKILL.md
S10	config.json is valid JSON	Must parse without error	No

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	检查项	规则	自动修复
S1	YAML前置元数据存在	SKILL.md以 `---` 开头	否
S2	存在 `name` 字段	必填，非空字符串	否
S3	`name` 格式有效	符合 `^[a-z0-9-]+$` ，最长64字符	是 — 转换为slug格式
S4	存在 `description` 字段	必填，非空字符串	否
S5	`description` 长度	最长1024字符	是 — 截断
S6	`description` 无XML标签	值中不含 `<tags>`	是 — 移除标签
S7	`description` 为字符串类型	不是YAML数组/对象	是 — 若为数组则拼接
S8	SKILL.md存在	必须在Skill目录中	否
S9	config.json存在	必须在Skill目录中	是 — 从SKILL.md生成
S10	config.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.

ID	Check	Rule	Auto-fix
C1	`<objective>` section exists	Must be present in SKILL.md body	Yes — add stub
C2	`<quick_start>` section exists	Must be present in SKILL.md body	Yes — add stub
C3	`<success_criteria>` section exists	Must be present in SKILL.md body	Yes — add stub
C4	Line count	Body ≤ 500 lines (warning only)	Warning
C5	Dead reference links	Internal `reference/` links must resolve	Yes — remove dead
C6	Naming convention	Directory 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.

ID	Check	Rule	Auto-fix
I1	config.json has standard keys	Must have `name` , `version` , `category`	Yes — add missing
I2	Uses `activation_triggers` key	Not `triggers` (legacy name)	Yes — rename key
I3	Uses `depends_on` key	Not `dependencies` (legacy name)	Yes — rename key
I4	Has `version` field	Must have `version` string	Yes — add "1.0.0"
I5	No duplicate activation triggers	No trigger collisions across skills	Warning

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	检查项	规则	自动修复
I1	config.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:

Check	Fix Strategy
S3	Slugify: lowercase, replace spaces/special chars with hyphens
S5	Truncate to 1024 chars at last sentence boundary
S6	Strip XML tags with regex: `</?[a-z_]+>` → empty string
S7	If array: join elements with ". ". If object: use first value
S9	Generate minimal config.json from SKILL.md frontmatter
C1	Add `<objective>\nTODO: Add objective\n</objective>` after frontmatter
C2	Add `<quick_start>\nTODO: Add quick start\n</quick_start>` after objective
C3	Add `<success_criteria>\nTODO: Add success criteria\n</success_criteria>` after quick_start
C5	Remove dead `[text](reference/...)` links
I1	Add missing keys with defaults from SKILL.md frontmatter
I2	Rename `triggers` → `activation_triggers` in config.json
I3	Rename `dependencies` → `depends_on` in config.json
I4	Add `"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.

Source	Pattern	Check
GitHub #9817	Whitespace before `---` prevents YAML parse	S1
GitHub #11322	Prettier reformats description to multi-line	S7
GitHub #17604	YAML array in description crashes slash commands	S7
GitHub #6377	Missing `name` field despite valid YAML structure	S2
GitHub #14882	Skills consume full tokens (no progressive disclosure)	C4
GitHub #14577	`/skills` shows "No skills found" — frontmatter parse failure	S1, S2
Library audit	8 skills missing XML sections	C1-C3
Library audit	9 skills using legacy config.json keys	I2, I3
Library audit	1 skill missing `-skill` suffix	C6

</core_content>

<common_mistakes>

这些模式来自真实的GitHub问题和技能库审计结果。诊断引擎会检查所有这些模式。

来源	模式	检查项
GitHub #9817	`---` 前的空白导致YAML解析失败	S1
GitHub #11322	Prettier将description格式化为多行	S7
GitHub #17604	description中的YAML数组导致斜杠命令崩溃	S7
GitHub #6377	尽管YAML结构有效，但缺失 `name` 字段	S2
GitHub #14882	Skill占用全部令牌（无渐进式披露）	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

常见问题

Mistake	Fix
Running `--fix` without reviewing diffs	Always preview first. The protocol requires confirmation.
Ignoring WARNINGS	Warnings are advisory but indicate tech debt. Track them.
Fixing only CRITICAL issues	HIGH and MEDIUM issues affect discoverability and tooling. Fix all layers.
Adding XML stubs without filling them in	Stubs are placeholders. Schedule time to write real content.
Running heal on a single skill when library-wide issues exist	Run full scan first to see the big picture.

</common_mistakes>

错误	修复方案
未查看差异就运行 `--fix`	始终先预览。协议要求必须确认。
忽略警告	警告虽为建议，但表明存在技术债务。需跟踪处理。
仅修复严重问题	高优先级和中优先级问题会影响可发现性和工具使用。需修复所有层级的问题。
添加XML占位符但未填充内容	占位符仅为临时方案。需安排时间编写真实内容。
当存在全库问题时仅诊断单个Skill	先运行全扫描以了解整体情况。

</common_mistakes>