heal-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/heal-skill — Automated Skill Maintenance

/heal-skill — 自动化Skill维护

Purpose: Detect and auto-fix common skill hygiene issues across the skills/ directory.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

用途： 检测并自动修复skills/目录下常见的Skill规范性问题。

你必须执行此工作流，不能仅进行描述。

Quick Start

快速开始

bash

/heal-skill                    # Check all skills (report only)
/heal-skill --fix              # Auto-repair all fixable issues
/heal-skill skills/council     # Check a specific skill
/heal-skill --fix skills/vibe  # Fix a specific skill

bash

/heal-skill                    # 检查所有Skill（仅生成报告）
/heal-skill --fix              # 自动修复所有可修复问题
/heal-skill skills/council     # 检查指定Skill
/heal-skill --fix skills/vibe  # 修复指定Skill

What It Detects

检测范围

Six checks, run in order:

Code	Issue	Auto-fixable?
`MISSING_NAME`	No `name:` field in SKILL.md frontmatter	Yes -- adds name from directory
`MISSING_DESC`	No `description:` field in SKILL.md frontmatter	Yes -- adds placeholder
`NAME_MISMATCH`	Frontmatter `name` differs from directory name	Yes -- updates to match directory
`UNLINKED_REF`	File in references/ not linked in SKILL.md	Yes -- converts bare backtick refs to markdown links
`EMPTY_DIR`	Skill directory exists but has no SKILL.md	Yes -- removes empty directory
`DEAD_REF`	SKILL.md references a non-existent references/ file	No -- warn only

共六项检查，按顺序执行：

代码	问题	是否可自动修复？
`MISSING_NAME`	SKILL.md中缺少 `name:` 字段	是 -- 从目录名添加name字段
`MISSING_DESC`	SKILL.md中缺少 `description:` 字段	是 -- 添加占位符
`NAME_MISMATCH`	前置元数据中的 `name` 与目录名不匹配	是 -- 更新为与目录名一致
`UNLINKED_REF`	references/中的文件未在SKILL.md中关联	是 -- 将反引号包裹的引用转换为Markdown链接
`EMPTY_DIR`	Skill目录存在但无SKILL.md文件	是 -- 删除空目录
`DEAD_REF`	SKILL.md引用了不存在的references/文件	否 -- 仅发出警告

Execution Steps

执行步骤

Step 1: Run the heal script

步骤1：运行修复脚本

bash

undefined

bash

undefined

Check mode (default) -- report only, no changes

检查模式（默认）-- 仅生成报告，不修改内容

bash skills/heal-skill/scripts/heal.sh --check

Fix mode -- auto-repair what it can

修复模式 -- 自动修复可处理的问题

bash skills/heal-skill/scripts/heal.sh --fix

Target a specific skill

针对指定Skill执行

bash skills/heal-skill/scripts/heal.sh --check skills/council bash skills/heal-skill/scripts/heal.sh --fix skills/council

undefined

bash skills/heal-skill/scripts/heal.sh --check skills/council bash skills/heal-skill/scripts/heal.sh --fix skills/council

undefined

Step 2: Interpret results

步骤2：解读结果

Exit 0: All clean, no findings.
Exit 1: Findings reported. In
```
--fix
```
mode, fixable issues were repaired; re-run
```
--check
```
to confirm.

退出码0： 无问题，所有Skill均合规。
退出码1： 检测到问题。在
```
--fix
```
模式下，可修复的问题已被修复；请重新运行
```
--check
```
确认结果。

Step 3: Report to user

步骤3：向用户反馈结果

Show the output. If

--fix

was used, summarize what changed. If

DEAD_REF

findings remain, advise the user to remove or update the broken references manually.

展示输出内容。若使用了

--fix

模式，总结已修改的内容。若仍存在

DEAD_REF

问题，建议用户手动删除或更新无效引用。

Output Format

输出格式

One line per finding:

[MISSING_NAME] skills/foo: No name field in frontmatter
[MISSING_DESC] skills/foo: No description field in frontmatter
[NAME_MISMATCH] skills/foo: Frontmatter name 'bar' != directory 'foo'
[UNLINKED_REF] skills/foo: refs/bar.md not linked in SKILL.md
[EMPTY_DIR] skills/foo: Directory exists but no SKILL.md
[DEAD_REF] skills/foo: SKILL.md links to non-existent refs/bar.md

每条检测结果占一行：

[MISSING_NAME] skills/foo: SKILL.md中缺少name字段
[MISSING_DESC] skills/foo: SKILL.md中缺少description字段
[NAME_MISMATCH] skills/foo: 前置元数据name为'bar'与目录名'foo'不匹配
[UNLINKED_REF] skills/foo: refs/bar.md未在SKILL.md中关联
[EMPTY_DIR] skills/foo: 目录存在但无SKILL.md文件
[DEAD_REF] skills/foo: SKILL.md引用了不存在的refs/bar.md

Notes

注意事项

The script is idempotent -- running
```
--fix
```
twice produces the same result.
```
DEAD_REF
```
is warn-only in
```
--fix
```
mode because the correct resolution (delete reference, create file, or update link) requires human judgment.
When run without a path argument, scans all directories under
```
skills/
```
.

该脚本具有幂等性（idempotent）-- 多次运行
```
--fix
```
指令结果一致。
在
```
--fix
```
模式下，
```
DEAD_REF
```
仅发出警告，因为正确的处理方式（删除引用、创建文件或更新链接）需要人工判断。
若未指定路径参数，将扫描
```
skills/
```
下的所有目录。