skill-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Audit

技能审核

Audit a skill before calling it ready. Favor Tessl output, repo conventions, and the skill's actual file shape over taste.

Tessl

is the skill-evaluation CLI this repo uses to review skills, score their quality, and suggest improvements. See tessl.io and the CLI docs. If

npx tessl ...

tessl ...

is unavailable, install or initialize Tessl before running the audit loop.

在判定技能就绪前对其进行审核。优先参考Tessl输出结果、仓库规范以及技能的实际文件结构，而非主观偏好。

Tessl

是本仓库用于评审技能、为技能质量打分并提出改进建议的技能评估CLI工具。详情请查看tessl.io及CLI文档。若无法使用

npx tessl ...

或

tessl ...

命令，请先安装或初始化Tessl，再运行审核流程。

Principles

原则

Evidence beats hunches
Discovery matters: score
```
name
```
and
```
description
```
before polishing the body
Keep
```
SKILL.md
```
lean; move depth into
```
references/
```
or scripts only when they earn their keep
Prefer the smallest change set that improves activation, clarity, or verification
Audit only the requested scope; flag adjacent issues separately

依据证据而非直觉
先发现问题：在完善技能主体内容前，先对
```
name
```
和
```
description
```
进行评分
保持
```
SKILL.md
```
简洁；仅当内容具备足够价值时，才将深度内容移至
```
references/
```
目录或脚本中
优先选择能提升激活率、清晰度或可验证性的最小变更集
仅审核指定范围；相邻问题单独标记

Handoffs

任务转交

Need to update AGENTS, README, or other repo docs beyond the skill surface -> use
```
docs
```
Need to prove a product or code change works on real surfaces -> use
```
verify
```
Need to review general code or a PR instead of a skill package -> use
```
review
```

若需要更新AGENTS、README或技能表层之外的其他仓库文档 -> 使用
```
docs
```
工具
若需要验证产品或代码变更在实际场景中的有效性 -> 使用
```
verify
```
工具
若需要评审通用代码或PR而非技能包 -> 使用
```
review
```
工具

Before You Start

开始前准备

Define scope: one skill folder or the whole skills repo
Load the target repo's guidance files such as
```
AGENTS.md
```
,
```
CLAUDE.md
```
, or repo rules, when present
Read the target
```
SKILL.md
```
first, then nearby
```
references/
```
,
```
scripts/
```
, and
```
agents/openai.yaml
```
only as needed
Pick the right Tessl loop:
- single skill:
```
npx tessl skill review --json skills/<name>
```
- full repo batch: use a repo wrapper such as
```
./scripts/review-skills.sh
```
  if one exists; otherwise run direct Tessl reviews per skill
- optimizer only when explicitly requested:
```
npx tessl skill review --optimize --yes --max-iterations 1 skills/<name>
```

定义范围：单个技能文件夹或整个技能仓库
加载目标仓库的指南文件（如
```
AGENTS.md
```
、
```
CLAUDE.md
```
或仓库规则，若存在）
先阅读目标
```
SKILL.md
```
，仅在需要时查看附近的
```
references/
```
、
```
scripts/
```
和
```
agents/openai.yaml
```
文件
选择合适的Tessl流程：
- 单个技能：
```
npx tessl skill review --json skills/<name>
```
- 全仓库批量审核：若存在仓库封装脚本（如
```
./scripts/review-skills.sh
```
  ）则使用该脚本；否则为每个技能单独运行Tessl评审
- 仅在明确要求时使用优化器：
```
npx tessl skill review --optimize --yes --max-iterations 1 skills/<name>
```

Workflow

工作流程

1. Run Tessl first

1. 首先运行Tessl

Capture the score, summary, and concrete suggestions before proposing edits. Prefer per-skill

--json

when you need a narrow audit loop or structured output. If Tessl is missing, use

npx tessl ...

first or follow the official docs before continuing.

在提出编辑建议前，先获取评分、摘要和具体建议。当需要窄范围审核流程或结构化输出时，优先使用单技能的

--json

参数。若Tessl未安装，请先运行

npx tessl ...

或遵循官方文档，再继续后续操作。

2. Audit discovery

2. 审核发现环节

Use references/scorecard.md to check:

whether
```
name
```
is specific and memorable
whether
```
description
```
states what the skill does, when to use it, and its main boundary
whether likely user phrasing would activate the skill without extra prompting

Quick example:

weak:
```
helper
```
— "Helps with skills"
stronger:
```
skill-audit
```
— "Audits existing skills with Tessl scoring, metadata checks, and repo conventions"

使用references/scorecard.md检查：

```
name
```
是否具体且易于记忆
```
description
```
是否明确说明技能功能、适用场景及主要边界
用户常用表述是否无需额外提示即可激活该技能

快速示例：

不佳：
```
helper
```
— "Helps with skills"（协助处理技能相关事务）
更佳：
```
skill-audit
```
— "Audits existing skills with Tessl scoring, metadata checks, and repo conventions"（使用Tessl评分、元数据检查及仓库规范审核现有技能）

3. Audit workflow shape

3. 审核工作流程结构

Check that the skill tells the agent how to start, what evidence to gather, what not to change, and what "done" looks like.

Concrete failure signs:

vague verbs like "help" without a workflow
missing output expectations
commands or paths that cannot be run as written
a fragile task described with high-level prose instead of tighter guardrails

检查技能是否告知Agent如何启动、需收集哪些证据、哪些内容不可更改，以及“完成”的标准是什么。

常见问题迹象：

使用模糊动词（如“帮助”）却未明确工作流程
缺失输出预期
命令或路径无法按原文运行
用笼统描述替代严格约束来定义易出错的任务

4. Audit progressive disclosure

4. 审核渐进式披露

Check whether detail belongs in

SKILL.md

references/

, or executable scripts:

keep core workflow in
```
SKILL.md
```
move dense doctrine, examples, or score rubrics into
```
references/
```
use scripts for repeated deterministic work instead of asking the model to recreate them

Use references/best-practices.md when the skill feels bloated, under-specified, or hard to trigger.

检查细节内容应放在

SKILL.md

、

references/

目录还是可执行脚本中：

将核心工作流程保留在
```
SKILL.md
```
中
将密集的准则、示例或评分标准移至
```
references/
```
目录
重复的确定性工作使用脚本实现，而非让模型重新生成

当技能显得臃肿、规格不足或难以触发时，可参考references/best-practices.md。

5. Audit repo fit

5. 审核仓库适配性

Check for repo-relative links, stale paths, duplicated guidance, and conflicts with the source repo's conventions.

检查仓库相对链接、过时路径、重复指南以及与源码仓库规范的冲突。

6. Synthesize the smallest useful change set

6. 整合最小实用变更集

Separate blockers from polish. If edits are requested, fix the highest-leverage issues first, rerun Tessl, and report what improved.

区分阻塞性问题与优化性问题。若需要编辑，优先修复影响最大的问题，重新运行Tessl并报告改进情况。

Output

输出结果

After an audit, report:

scope audited
Tessl command and score
strongest parts worth keeping
prioritized findings with file references
smallest recommended changes
rerun status if edits were made

审核完成后，需报告：

审核范围
使用的Tessl命令及评分
值得保留的优势部分
带有文件引用的优先级发现问题
推荐的最小变更内容
若进行了编辑，需报告重新运行后的状态

References

参考资料

references/scorecard.md — audit dimensions, severity, and a compact review template
references/best-practices.md — distilled skill-authoring guidance from common repo conventions and Claude's skill best-practices guide

references/scorecard.md — 审核维度、严重程度及简洁评审模板
references/best-practices.md — 基于通用仓库规范及Claude技能最佳实践指南提炼的技能编写指导