create-or-audit-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create or audit a skill

创建或审核Skill

Two modes, same skill: Mode 1 writes a new skill by discovering the pattern already used in the codebase and encoding it. Mode 2 reviews an existing or proposed

SKILL.md

against the principles and the

skills/meta/create-or-audit-skill/lib/validate.sh

quality gates.

两种模式，同一目标：模式1 通过发现代码库中已使用的模式并将其编码，编写新的Skill。模式2 依据相关原则和

skills/meta/create-or-audit-skill/lib/validate.sh

质量标准，审核现有或拟议的

SKILL.md

。

Before You Start

开始之前

```
principles/06-portability-test.md
```
— the core rule: a skill belongs in a project's
```
.claude/skills/
```
only if it would fail in an unrelated project. If it works unchanged elsewhere, it's generic and does not belong there.
```
skills/meta/create-or-audit-skill/templates/skill.md
```
— annotated blank skeleton with comments explaining every field.
Categories used in this library:
```
meta/
```
,
```
workflow/
```
,
```
documentation/
```
,
```
planning/
```
. Project-specific starter kits (scaffolding, debugging, reference) live under
```
guides/
```
since they need codebase-specific adaptation.
```
skills/meta/create-or-audit-skill/lib/validate.sh
```
— the authoritative structural checks. Run this BEFORE any content review.

```
principles/06-portability-test.md
```
— 核心规则：只有当某个Skill在无关项目中无法正常运行时，它才属于项目的
```
.claude/skills/
```
目录。如果它无需修改即可在其他地方运行，说明它是通用型的，不应放在该目录下。
```
skills/meta/create-or-audit-skill/templates/skill.md
```
— 带注释的空白模板，其中的注释解释了每个字段的用途。
本库使用的分类：
```
meta/
```
、
```
workflow/
```
、
```
documentation/
```
、
```
planning/
```
。项目专属入门套件（脚手架、调试、参考）位于
```
guides/
```
目录下，因为它们需要针对代码库进行特定适配。
```
skills/meta/create-or-audit-skill/lib/validate.sh
```
— 权威的结构检查脚本。在进行任何内容审核之前，请先运行此脚本。

Mode 1 — build a new skill

模式1 — 构建新Skill

Step 1: validate the idea

步骤1：验证想法

Determine whether this SHOULD be a skill:

Is it multi-step? Single-step procedures belong in
```
CLAUDE.md
```
, not a skill.
Is it project-specific? Generic programming workflows (writing tests, using git) don't need skills unless the codebase does them in a non-obvious way.
Is it frequent? Runs < 1×/month → a
```
CLAUDE.md
```
line is sufficient.
Is it already covered? Check existing skills and
```
CLAUDE.md
```
:

bash

find .claude/skills -name "SKILL.md" 2>/dev/null | while read f; do
  echo "=== $(basename "$(dirname "$f")") ==="
  sed -n '/^description:/,/^[a-z]*:/p' "$f" | head -5
done

Should it be a hook? If the rule is "always do X after Y" and X is deterministic →
```
PostToolUse
```
hook, not a skill.

If 1–3 is no or 4–5 is yes, tell the user why a skill isn't the right tool and propose the alternative.

确定是否应该创建该Skill：

是否为多步骤流程？ 单步骤操作应放在
```
CLAUDE.md
```
中，而非Skill里。
是否为项目专属？ 通用编程工作流（编写测试、使用git）无需做成Skill，除非代码库采用了非显而易见的实现方式。
是否频繁使用？ 每月使用次数少于1次 → 只需在
```
CLAUDE.md
```
中添加一行说明即可。
是否已有相关覆盖？ 检查现有Skill和
```
CLAUDE.md
```
：

bash

find .claude/skills -name "SKILL.md" 2>/dev/null | while read f; do
  echo "=== $(basename "$(dirname "$f")") ==="
  sed -n '/^description:/,/^[a-z]*:/p' "$f" | head -5
done

是否应做成钩子？ 如果规则是“执行Y后必须执行X”且X是确定性操作 → 应做成
```
PostToolUse
```
钩子，而非Skill。

如果1-3的答案为否，或4-5的答案为是，请告知用户为何Skill不是合适的工具，并提出替代方案。

Step 2: find the existing pattern

步骤2：查找现有模式

The skill encodes what senior engineers already do; don't invent a procedure:

bash

undefined

Skill应编码资深工程师已在使用的流程；请勿自行发明流程：

bash

undefined

Find 2-3 real examples of this workflow in the codebase

在代码库中查找2-3个该工作流的实际示例

git log --pretty=format: --name-only -100 | sort | uniq -c | sort -rn | head -20

Look at which files changed together in past PRs (reveals coupled files)

查看过去PR中哪些文件一起变更（揭示关联文件）

git log --all --pretty=format:"%h %s" --name-only -50 | grep -iE "{keyword}"


Read 2–3 real examples. Note: files created/modified, exact verification commands, ordering, registration/wiring steps that are easy to forget, edge cases from code comments or PR reviews.

git log --all --pretty="%h %s" --name-only -50 | grep -iE "{keyword}"


阅读2-3个实际示例。记录：创建/修改的文件、确切的验证命令、操作顺序、容易遗漏的注册/连接步骤、代码注释或PR评审中提到的边缘情况。

Step 3: write the skill

步骤3：编写Skill

Copy

skills/meta/create-or-audit-skill/templates/skill.md

and fill in. The description is load-bearing:

Include what it does, referencing specific parts of this codebase.
≥3 trigger phrases in natural language engineers actually say.
≥1 "Do NOT use for" clause defining the boundary to a sibling skill.
< 1024 characters total.
No angle brackets (
```
<
```
or
```
>
```
) — they break YAML parsers.

The body:

Every instruction references a real file path, command, or pattern from this repo.
If you find generic advice ("use descriptive names", "handle errors properly"), delete it — it's not earning its tokens.
End with a concrete verification — a test command or a validation script. "Make sure it works" is not verification.

复制

skills/meta/create-or-audit-skill/templates/skill.md

并填写内容。描述部分至关重要：

包含功能说明，并引用代码库的特定部分。
包含至少3个触发短语，即工程师实际会说的自然语言表述。
包含**至少1条“请勿用于”**条款，定义与同类Skill的边界。
总长度少于1024字符。
不包含尖括号（
```
<
```
或
```
>
```
）——它们会破坏YAML解析器。

正文部分：

每条指令都引用本仓库中的实际文件路径、命令或模式。
如果发现通用建议（如“使用描述性名称”、“正确处理错误”），请删除——这类内容没有实际价值。
以具体的验证步骤结尾——比如测试命令或验证脚本。“确保正常运行”不属于验证步骤。

Step 4: run the validator

步骤4：运行验证器

bash

bash skills/meta/create-or-audit-skill/lib/validate.sh .claude/skills/{skill-name}/SKILL.md

Fix every error and warning before presenting to the user.

bash

bash skills/meta/create-or-audit-skill/lib/validate.sh .claude/skills/{skill-name}/SKILL.md

在提交给用户之前，修复所有错误和警告。

Step 5: semantic test

步骤5：语义测试

Trigger test: "When would you use the {skill-name} skill?" — the answer should accurately describe the intended case.
Negative test: Would it trigger for adjacent-but-different queries? Adjust the "Do NOT" clause until no.
Token check:
```
wc -l .claude/skills/{skill-name}/SKILL.md
```
— over 500 lines warns; over 600 fails.

触发测试： “何时应使用{skill-name} Skill？”——答案应准确描述预期使用场景。
否定测试： 是否会因相近但不同的查询触发？调整“请勿用于”条款直至不会触发。
字数检查：
```
wc -l .claude/skills/{skill-name}/SKILL.md
```
——超过500行警告；超过600行视为不合格。

Mode 2 — audit an existing skill

模式2 — 审核现有Skill

Step 1: structural check first

步骤1：先进行结构检查

bash

bash skills/meta/create-or-audit-skill/lib/validate.sh path/to/SKILL.md

If this exits 1, stop and report. No point reviewing content if the skeleton is broken.

bash

bash skills/meta/create-or-audit-skill/lib/validate.sh path/to/SKILL.md

如果脚本返回1，请停止并上报。如果框架存在问题，内容审核毫无意义。

Step 2: six gates (semantic)

步骤2：六大语义审核标准

Gate 1 — Portability. Read every instruction. For each, ask: does it reference something specific to this project? Hard fail if fewer than 3 real references OR if the skill would work unchanged in a random GitHub repo.

Gate 2 — Overlap. Check against

CLAUDE.md

and other skills:

bash

find .claude/skills -name "SKILL.md" | xargs grep -l "{skill-topic}"
grep -l "{skill-topic}" CLAUDE.md **/CLAUDE.md 2>/dev/null

Hard fail if > 50% of content duplicates

CLAUDE.md

or if another skill has > 70% overlap.

Gate 3 — Description quality. Verify trigger phrases (≥3), negative scope (≥1), length (< 1024), no angle brackets. Ask "would an adjacent query wrongly trigger this?"

Gate 4 — Instruction quality. For each step: real path/command/pattern, actionable language, includes the why when non-obvious, doesn't restate what a linter catches (principle 03).

Check for stale paths:

bash

grep -oE '`[a-zA-Z_./-]+/[a-zA-Z_.-]+`' .claude/skills/{name}/SKILL.md | tr -d '`' | while read p; do
  [ ! -e "$p" ] && echo "STALE: $p"
done

Gate 5 — Safety.

allowed-tools

scoped to what's needed. No embedded secrets. Validation scripts have no destructive side effects.

Gate 6 — Alternatives for prohibitions. Every "never", "don't", "do not" must pair with an "instead" in the same section (principle 05). If not, add the alternative.

标准1 — 可移植性 阅读每条指令。针对每条指令，询问：是否引用了本项目特有的内容？如果项目特定引用少于3个，或者该Skill无需修改即可在任意GitHub仓库运行，则视为不合格。

标准2 — 内容重叠 对照

CLAUDE.md

和其他Skill进行检查：

bash

find .claude/skills -name "SKILL.md" | xargs grep -l "{skill-topic}"
grep -l "{skill-topic}" CLAUDE.md **/CLAUDE.md 2>/dev/null

如果超过50%的内容与

CLAUDE.md

重复，或与其他Skill的重叠度超过70%，则视为不合格。

标准3 — 描述质量 验证触发短语（至少3个）、否定范围（至少1条）、长度（少于1024字符）、无尖括号。询问“相近的查询是否会错误触发该Skill？”

标准4 — 指令质量 每条步骤：包含实际路径/命令/模式、表述可执行、对非显而易见的操作说明原因、不重复代码检查工具已覆盖的内容（原则03）。

检查过时路径：

bash

grep -oE '`[a-zA-Z_./-]+/[a-zA-Z_.-]+`' .claude/skills/{name}/SKILL.md | tr -d '`' | while read p; do
  [ ! -e "$p" ] && echo "STALE: $p"
done

标准5 — 安全性

allowed-tools

仅包含必要工具。不嵌入密钥。验证脚本无破坏性副作用。

标准6 — 禁止操作的替代方案 每条“never”、“don't”、“do not”必须在同一部分搭配“instead”说明替代方案（原则05）。如果没有，请添加替代方案。

Step 3: report

步骤3：生成报告

markdown

undefined

markdown

undefined

Skill Audit: {skill-name}

Skill审核报告：{skill-name}

Verdict: APPROVE | REVISE | REJECT

结论：通过 | 需要修订 | 拒绝

Gate results

审核标准结果

Gate	Result	Notes
1. Portability	PASS/FAIL	{X/Y instructions are project-specific}
2. Overlap	PASS/FAIL	{overlaps with X / none}
3. Description	PASS/FAIL	{specific issues}
4. Instructions	PASS/FAIL	{stale paths, generic advice, ...}
5. Safety	PASS/FAIL	{specific issues}
6. Alternatives	PASS/FAIL	{prohibitions without instead-clauses}

标准	结果	备注
1. 可移植性	通过/未通过	{X/Y条指令为项目专属}
2. 内容重叠	通过/未通过	{与X内容重叠 / 无重叠}
3. 描述质量	通过/未通过	{具体问题}
4. 指令质量	通过/未通过	{过时路径、通用建议等}
5. 安全性	通过/未通过	{具体问题}
6. 替代方案	通过/未通过	{无替代方案的禁止操作}

Proposed revisions

建议修订内容

{Concrete rewrites, not just "make it more specific".}

undefined

{具体改写内容，而非仅“更具体一些”。}

undefined

Verify

验证

Run the validator against the produced or audited skill:

bash

bash skills/meta/create-or-audit-skill/lib/validate.sh path/to/SKILL.md

Expected:

VERDICT: PASS

. Fix errors until it does.

针对生成或审核后的Skill运行验证器：

bash

bash skills/meta/create-or-audit-skill/lib/validate.sh path/to/SKILL.md

预期结果：

VERDICT: PASS

。修复错误直至通过。

Common Mistakes

常见错误

Mistake	Correction
Writing a skill that's really a generic programming tutorial	Delete it or move its content to `CLAUDE.md` . Skills encode project-specific procedures.
Description without a "Do NOT use for" clause	Add one pointing at a sibling skill. Without it, the router will over-match.
Instructions that say "handle errors properly" or similar	Replace with "use `ProjectError` from `src/errors/index.ts` ; see `src/users/service.ts:45` for an example."
Missing the verification step	Every skill ends with a concrete check — a test command, a file-exists probe, a lint pass.

错误	修正方案
将Skill写成通用编程教程	删除或将内容移至 `CLAUDE.md` 。Skill应编码项目专属流程。
描述中缺少“请勿用于”条款	添加一条指向同类Skill的条款。没有该条款，路由会匹配过度。
指令中出现“正确处理错误”等表述	替换为“使用 `src/errors/index.ts` 中的 `ProjectError` ；示例请见 `src/users/service.ts:45` ”。
缺少验证步骤	每个Skill都应以具体检查步骤结尾——比如测试命令、文件存在性检查、代码扫描通过。