skill-perfection

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Perfection

Skill 完善流程

A systematic process for auditing and fixing plugin skills in a single pass.

一套可一次性完成插件Skill审核与修复的系统化流程。

Core Principle

核心原则

Audit + Fix in One Pass: When you find an issue, fix it immediately, then continue. This eliminates redundant research and multiple iterations.

审核+修复一步到位：发现问题后立即修复，然后继续审核。这能避免重复调研和多次迭代。

Process Overview

流程概览

[Optional Preflight] → Audit+Fix (single pass) → Verify (spot-check) → Report

[可选预检查] → 审核+修复（一次性完成）→ 验证（抽样检查）→ 生成报告

Phase 1: Preflight (Optional, Advisory)

阶段1：预检查（可选，仅供参考）

A Python-based preflight script is bundled for Python-heavy skills only.

仅针对以Python为主的Skill，我们提供了一个基于Python的预检查脚本。

When to Use Preflight

何时使用预检查

Skill Content	Use Preflight?
Mostly Python code blocks	✅ Yes
Mixed Python + other languages	⚠️ Optional (Python blocks only)
Non-Python (JS, Rust, Go, etc.)	❌ Skip, go to Phase 2
Skill about the preflight script itself	❌ Skip (conflict of interest)

Skill内容	是否使用预检查？
主要为Python代码块	✅ 是
Python与其他语言混合	⚠️ 可选（仅检查Python代码块）
非Python语言（JS、Rust、Go等）	❌ 跳过，直接进入阶段2
Skill本身是关于预检查脚本的	❌ 跳过（存在利益冲突）

Running Preflight

运行预检查

bash

uv run python ${SKILL_DIR}/scripts/preflight.py <path-to-skill.md> --no-urls

bash

uv run python ${SKILL_DIR}/scripts/preflight.py <path-to-skill.md> --no-urls

Interpreting Results

结果解读

Result	Action
`✅ PASSED`	Good signal. Proceed to Phase 2, trust syntax is valid.
`❌ FAILED` with clear errors (syntax error at line X)	Fix those specific issues, then proceed to Phase 2.
`❌ FAILED` with confusing/many errors	Ignore preflight entirely. Proceed to Phase 2, let LLM verify.
Script crashes or hangs	Ignore preflight entirely. Proceed to Phase 2.

结果	操作
`✅ PASSED`	结果可靠。进入阶段2，可信任语法有效性。
`❌ FAILED` 且错误明确（如第X行语法错误）	修复这些特定问题，然后进入阶段2。
`❌ FAILED` 且错误混乱/数量多	完全忽略预检查结果。进入阶段2，由LLM进行验证。
脚本崩溃或挂起	完全忽略预检查结果。进入阶段2。

Key Rule: Preflight is Advisory

关键规则：预检查仅供参考

The preflight script is a helper, not a gatekeeper. If it produces confusing output, skip it. The LLM-based Phase 2 is always authoritative.

Signs to ignore preflight:

More than 10 errors on a skill that "looks fine"
Errors that don't make sense (line numbers don't match)
Python tracebacks from the script itself
Timeouts or hanging

When in doubt, skip preflight and let the LLM verify everything.

预检查脚本仅为辅助工具，而非准入门槛。如果输出内容混乱，请直接跳过。基于LLM的阶段2始终是权威验证方式。

需忽略预检查的情况：

看起来正常的Skill却出现10个以上错误
无意义的错误（如行号不匹配）
脚本自身抛出Python回溯信息
超时或挂起

如有疑问，跳过预检查，让LLM验证所有内容。

Phase 2: Audit + Fix (Single Pass) - THE CORE

阶段2：审核+修复（一次性完成）—— 核心环节

This is the main phase. Work through the skill file section by section.

这是核心阶段。逐段处理Skill文件。

2.1 Identify the Technology

2.1 确定技术栈

From the skill's content, identify:

Primary technology/framework (e.g., LangGraph, React, Axum, Go-kit)
Version constraints if mentioned
Official documentation domain

从Skill内容中明确：

核心技术/框架（如LangGraph、React、Axum、Go-kit）
提及的版本限制
官方文档域名

2.2 Research Strategy

2.2 调研策略

Batch similar lookups to minimize web calls:

Example: For a skill with 10 import statements from the same package,
do ONE search that covers them all, not 10 separate searches.

Documentation priority:

Official docs (use
```
site:
```
filter)
Official GitHub repo (examples, tests, README)
Package registry (PyPI, npm, crates.io, pkg.go.dev)
Official blog/changelog

批量处理同类查询，减少网络请求次数：

示例：对于包含10条同一包导入语句的Skill，
只需进行一次覆盖所有导入的搜索，而非10次单独搜索。

文档优先级：

官方文档（使用
```
site:
```
筛选）
官方GitHub仓库（示例、测试、README）
包管理平台（PyPI、npm、crates.io、pkg.go.dev）
官方博客/更新日志

2.3 For Each Verifiable Item

2.3 可验证项检查清单

Item Type	What to Verify
Import/require statement	Package exists, path is current, not deprecated
API call	Signature matches official docs, parameters correct
Code example	Would execute, complete imports, correct syntax
URL/link	Accessible (WebFetch), points to claimed content
Version claim	Current/accurate
Best practice claim	Aligned with official recommendations

项类型	验证内容
导入/require语句	包是否存在、路径是否为当前最新、未被弃用
API调用	签名与官方文档匹配、参数正确
代码示例	可正常执行、导入完整、语法正确
URL/链接	可访问（通过WebFetch）、指向声明的内容
版本声明	最新且准确
最佳实践声明	与官方建议一致

2.4 Fix-As-You-Go

2.4 发现即修复

When you find an issue:

STOP auditing that section
FIX the issue immediately (Edit tool)

LOG the change in memory:

{location, old, new, reason, source_url}

CONTINUE auditing

All severities get fixed in one pass - don't defer anything.

发现问题时：

暂停当前段落的审核
立即修复问题（使用编辑工具）

在内存中记录变更：

{位置, 旧内容, 新内容, 原因, 来源URL}

继续审核

所有严重程度的问题都要在本次流程中修复——不要推迟任何问题。

2.5 Syntax Verification (LLM-based)

2.5 语法验证（基于LLM）

For code blocks, verify syntax by reading carefully:

Python: Check for matching parentheses, correct indentation, valid syntax JavaScript/TypeScript: Check for matching braces, valid syntax, correct imports
Rust: Check for matching braces, semicolons, valid syntax Go: Check for matching braces, correct package structure Any language: Apply your knowledge of that language's syntax rules

If unsure about syntax validity, note it but don't block on it - focus on semantic correctness against official docs.

对于代码块，通过仔细阅读验证语法：

Python：检查括号匹配、缩进正确、语法有效 JavaScript/TypeScript：检查大括号匹配、语法有效、导入正确
Rust：检查大括号匹配、分号使用、语法有效 Go：检查大括号匹配、包结构正确 任意语言：应用你对该语言语法规则的了解

如果不确定语法是否有效，可记录但不要停滞——重点关注是否符合官方文档的语义正确性。

Phase 3: Verification (Spot-Check)

阶段3：验证（抽样检查）

After completing Phase 2:

Re-read the modified skill file
Spot-check 3-5 items you fixed (not everything)
Verify URLs you added/modified (WebFetch)

If spot-checks pass → Proceed to Phase 4 If spot-checks fail → Fix those specific items, re-check only those

Do NOT do a full re-audit. You already verified everything in Phase 2.

完成阶段2后：

重新阅读修改后的Skill文件
抽样检查3-5个你修复的问题（无需全部检查）
验证你添加/修改的URL（通过WebFetch）

如果抽样检查通过 → 进入阶段4 如果抽样检查失败 → 修复这些特定问题，仅重新检查这些问题

不要进行完整的重新审核。你已经在阶段2中完成了所有验证。

Phase 4: Generate Report

阶段4：生成报告

Create a concise report (<100 lines):

markdown

undefined

创建一份简洁的报告（少于100行）：

markdown

undefined

Skill Perfection Report

Skill 完善报告

Skill: {skill-name} Date: {date}
Version: {old} → {new} Status: ✅ PERFECTED | ⚠️ NEEDS REVIEW

Skill名称：{skill-name} 日期：{date}
版本：{旧版本} → {新版本} 状态：✅ 已完善 | ⚠️ 需复查

Summary

摘要

Items verified: {N}
Issues found and fixed: {N}

验证项数量：{N}
发现并修复的问题数量：{N}

Changes Made

变更记录

High Priority

高优先级

Location	Change	Reason	Source
line 45	`old` → `new`	why	docs

位置	变更内容	原因	来源
第45行	`旧内容` → `新内容`	原因说明	文档

Medium/Low Priority

中/低优先级

Location	Change	Reason	Source
line 12	`old` → `new`	why	docs

位置	变更内容	原因	来源
第12行	`旧内容` → `新内容`	原因说明	文档

Verification

验证情况

All imports verified against official docs
All API signatures match current documentation
Code examples are complete and correct
All URLs accessible

所有导入项均已对照官方文档验证
所有API签名与当前文档匹配
代码示例完整且正确
所有URL均可访问

Sources

参考来源

{url}
{url}


Save to: `{skill-directory}/PERFECTION_REPORT.md`

{url}
{url}


保存至：`{skill-directory}/PERFECTION_REPORT.md`

Efficiency Guidelines

效率指南

Metric	Target
Web searches	<20 per skill (batch similar items)
Iterations	1 audit+fix pass + 1 spot-check
Report length	<100 lines

指标	目标
网络搜索次数	每个Skill少于20次（批量处理同类项）
迭代次数	1次审核+修复流程 + 1次抽样检查
报告长度	少于100行

Anti-Patterns

反模式

❌ Run preflight on non-Python skills ✅ Skip preflight, let LLM verify

❌ Trust confusing preflight output
✅ Ignore preflight when output doesn't make sense

❌ Separate audit pass, then separate update pass ✅ Fix issues as you find them

❌ Full re-audit after fixes ✅ Spot-check only changed items

❌ Research same API multiple times
✅ Batch similar lookups, cache results

❌ 对非Python Skill运行预检查 ✅ 跳过预检查，由LLM进行验证

❌ 信任混乱的预检查输出
✅ 当输出无意义时忽略预检查

❌ 先单独进行审核，再单独进行更新 ✅ 发现问题立即修复

❌ 修复后进行完整重新审核 ✅ 仅抽样检查变更项

❌ 多次调研同一API
✅ 批量处理同类查询，缓存结果

Bundled Scripts

内置脚本

scripts/preflight.py

Purpose: Quick syntax check for Python-heavy skills Limitation: Only useful for Python; advisory only

bash

undefined

用途：快速检查以Python为主的Skill的语法 局限性：仅对Python Skill有用，仅供参考

bash

undefined

Use for Python skills

针对Python Skill使用

uv run python ${SKILL_DIR}/scripts/preflight.py skill.md --no-urls

Skip for non-Python skills or if output is confusing

非Python Skill或输出混乱时跳过


**If preflight causes problems, ignore it entirely.** The LLM-based audit is always the authoritative verification.


**如果预检查出现问题，请完全忽略它。基于LLM的审核始终是权威的验证方式。**