skill-improver

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Improver

Overview

概述

Make an existing skill better. The goal is helpful improvement, not a grade — produce concrete, prioritized changes the author can apply, not a score. You review five dimensions, lean on the bundled linter for mechanical facts, and apply judgment to the rest.

Core principle: Every observation comes with a suggested fix.

改进现有skill。目标是提供有用的改进建议，而非评分——给出作者可以实施的具体、分优先级的修改建议，而非分数。你需要从五个维度进行审查，借助内置的linter获取机械性事实，其余部分则运用判断能力。

核心原则： 每一项观察结果都附带对应的修复建议。

Inputs

输入

Required: path to a skill directory (with
```
SKILL.md
```
) or to a
```
SKILL.md
```
file.
Optional: the skill's intended purpose, if stated — used to judge whether name and scope match intent.

必填： skill目录（包含
```
SKILL.md
```
）或
```
SKILL.md
```
文件的路径。
可选： skill的预期用途（如有说明）——用于判断名称和范围是否与意图匹配。

Steps

步骤

Gather mechanical facts deterministically:
bash
```
bash "${CLAUDE_SKILL_DIR}/scripts/skill-lint.sh" <skill-dir-or-SKILL.md>
```
Reports frontmatter validity, name format, description shape, SKILL.md size, preferred sections, and referenced vs orphaned files. Treat
```
[FLAG]
```
s as leads, not verdicts.
Read the SKILL.md and bundled files yourself — the linter can't judge clarity, scope, or correctness.
Review the five dimensions (Guidelines), turning each finding into a concrete fix.
Prioritize high -> low impact. Lead with anything that breaks discovery (weak description) or correctness.
Write the report (Output). Offer to apply changes; if asked, hand authoring to
```
superpowers:writing-skills
```
.

确定性收集机械性事实：
bash
```
bash "${CLAUDE_SKILL_DIR}/scripts/skill-lint.sh" <skill-dir-or-SKILL.md>
```
报告前置元数据有效性、名称格式、描述形态、SKILL.md文件大小、推荐章节，以及已引用文件与孤立文件情况。将
```
[FLAG]
```
视为线索，而非定论。
自行阅读SKILL.md及附带文件——linter无法判断清晰度、范围或正确性。
审查五个维度（指南），将每一项发现转化为具体的修复建议。
按优先级排序：高影响 -> 低影响。首先处理任何会影响发现（描述薄弱）或正确性的问题。
撰写报告（输出）。主动提出帮助实施修改；若被请求，将编写工作交给
```
superpowers:writing-skills
```
。

Guidelines

指南

Dimension	What good looks like
Name & scope	Verb-first, active, single clear purpose. Flag vague or multi-purpose skills (suggest a split).
Description	Says when to invoke (triggers/symptoms/situations), not just what it does — `"Use when the user asks about slow queries or indexes"` , not `"Analyze and optimize queries"` . Third person; lead with "Use when". A summary of the steps makes agents skip the body — flag it.
Structure	Prefer overview, inputs, steps, guidelines, output format. Note missing sections; suggest where content should move.
Lean SKILL.md	Body holds workflow + judgment; heavy detail (APIs, long tables, big examples) belongs in `references/` . Flag bloat and name what to extract.
References / scripts / assets	Mechanical actions -> a deterministic script. Reusable context -> a reference. Templates -> assets. Flag orphaned files and non-deterministic scripts.

Look explicitly for the two highest-value opportunities: extraction (inline content that belongs in a

references/

file, leaning out the always-loaded body) and determinism (prose steps an agent does inconsistently that a small script would make reproducible).

维度	优秀标准
名称与范围	以动词开头、表述主动、单一明确用途。标记模糊或多用途的skill（建议拆分）。
描述	说明何时调用（触发条件/场景/症状），而非仅说明功能——例如 `"当用户询问慢查询或索引相关问题时使用"` ，而非 `"分析并优化查询"` 。使用第三人称；以“Use when”开头。若步骤摘要导致Agent跳过正文内容，需标记此问题。
结构	优先采用概述、输入、步骤、指南、输出格式的结构。标记缺失的章节；建议内容应调整到的位置。
精简SKILL.md	正文包含工作流程与判断逻辑；详细内容（API、长表格、大型示例）应放在 `references/` 目录下。标记冗余内容，并指出需要提取的部分。
参考资料/脚本/资源	机械操作 -> 确定性脚本。可复用上下文 -> 参考资料。模板 -> 资源。标记孤立文件和非确定性脚本。

重点关注两个最高价值的优化机会：提取（将内联内容移至

references/

文件中，精简始终加载的正文）和确定性（Agent执行时不一致的文字步骤，可通过小型脚本实现可重复性）。

Output format

输出格式

undefined

undefined

Skill review: <name>

Strengths: <1-2 lines>

Suggested improvements (highest impact first)

[<dimension>] <observation> -> <concrete fix>
...

[<dimension>] <observation> -> <concrete fix>
...

Extraction & determinism opportunities

<inline content -> references/file.md>, <prose step -> scripts/x.sh>

Overall: <1-2 sentences, specific and encouraging. No score.>

undefined

<inline content -> references/file.md>, <prose step -> scripts/x.sh>

Overall: <1-2 sentences, specific and encouraging. No score.>

undefined

Common mistakes

常见错误

Grading instead of helping — no scores; every point needs an actionable fix.
Parroting the linter — its flags are inputs; add the judgment it can't.
Extraction with nowhere to go — name the target file and what moves into it.

评分而非提供帮助——不打分；每一点都需要可操作的修复建议。
照搬linter结果——linter的标记只是输入；需要补充它无法做出的判断。
提取但无目标位置——明确目标文件及要移入的内容。

Scripts

脚本

```
scripts/skill-lint.sh
```
— deterministic mechanical checks (frontmatter, name, description, size, sections, orphaned/non-deterministic files). Read-only; pass a skill dir or
```
SKILL.md
```
path.

If a script can't run here (missing

bash

/a tool, or a different OS): don't abandon the task — the scripts only automate ordinary git/text commands, so reproduce the same steps directly with whatever tools this environment has.

```
scripts/skill-lint.sh
```
—— 确定性机械检查（前置元数据、名称、描述、大小、章节、孤立/非确定性文件）。只读；传入skill目录或
```
SKILL.md
```
路径。

若脚本无法在此运行（缺少

bash

/工具，或操作系统不同）：不要放弃任务——脚本只是自动化常规的git/文本命令，因此可直接使用当前环境中的任何工具重现相同步骤。