Back to Details

workleap-skill-optimizer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Optimizer

Skill优化器

Reduce skill token cost without losing coverage. Every token in SKILL.md body is paid per conversation — references/ files are loaded on-demand.
在不损失覆盖范围的前提下降低Skill的Token成本。SKILL.md主体中的每个Token都会按对话次数计费——参考文件是按需加载的。

Optimization Workflow

优化工作流

Phase 1: Analyze

第一阶段：分析

Measure the current skill before changing anything.
  1. Count SKILL.md body lines (exclude frontmatter) and estimate tokens (~4.5 tokens/line for mixed code/prose).
  2. Count description characters.
  3. List every 
    references/
    file with line counts.
  4. Identify duplication: for each body section (at any heading level), check if the same concept or procedure is also covered in a reference file. Count those body lines and divide by total body lines for the overlap percentage.
  5. List nouns from the description that appear verbatim in a sibling skill's description — these need domain-qualifying in Phase 2.
If the skill has no 
references/
directory, optimization may require creating reference files first. See the playbook for guidance on this edge case.
Output a table:
| Metric              | Current |
|---------------------|---------|
| Description chars   | ???     |
| Body lines          | ???     |
| Body tokens (est.)  | ???     |
| Duplication %       | ???     |
| Reference files     | ???     |
在进行任何修改前，先评估当前Skill的状态。
  1. 统计SKILL.md主体内容的行数（排除前置元数据frontmatter），并估算Token数量（混合代码与 prose 内容约为每行4.5个Token）。
  2. 统计描述字符数。
  3. 列出每个
    references/
    目录下的文件及其行数。
  4. 识别重复内容：检查主体中的每个章节（无论标题层级），确认相同的概念或流程是否也在参考文件中有所覆盖。统计这些重复的主体行数，并除以主体总行数得到重复率。
  5. 列出描述中与同类型Skill的描述完全重复的名词——这些需要在第二阶段进行领域限定。
如果Skill没有
references/
目录，优化前可能需要先创建参考文件。相关特殊场景的指导请参考操作手册。
输出如下表格：
| Metric              | Current |
|---------------------|---------|
| Description chars   | ???     |
| Body lines          | ???     |
| Body tokens (est.)  | ???     |
| Duplication %       | ???     |
| Reference files     | ???     |

Phase 2: Plan

第二阶段：规划

Decide what stays in the body, what moves to references, and what gets compressed.
Body retention criteria — keep a section in the body ONLY if it meets at least one:
  • Complex multi-step pattern requiring coordination across multiple sections or files
  • Non-obvious logic, parameters, or decision rules that agents frequently get wrong without inline guidance
  • A concept unique to this skill with no external documentation
  • Primary use case the skill exists for (the thing agents reach for most often)
Everything else belongs in the appropriate 
references/
file. See the playbook decision tree for concrete examples of what typically stays vs. moves.
Description compression rules:
  1. Lead with the package/tool name and a one-line identity
  2. Replace enumerations of 4+ specific names (APIs, checks, steps) with category-based phrasing (e.g., "hooks for auth, sessions, tokens" instead of listing each hook name)
  3. Qualify generic keywords with the skill's domain to reduce false positives (e.g., "MyLib integrations with Redis" not "Redis integration")
  4. Merge items that share a theme into a single line (e.g., "error handling" + "retry logic" → "Error handling and retry logic in MyLib")
  5. Verify every original trigger category maps 1:1 to the compressed version — no categories dropped
Plan the Reference Guide section — for each reference file, write a one-line description of when to read it. This section is load-bearing: it tells agents which file to consult.
Target metrics:
  • Body: under ~250 lines
  • Description: under ~700 characters
  • Duplication with references: 0%
决定哪些内容保留在主体中，哪些移至参考文件，以及哪些内容需要压缩。
主体内容保留标准——只有满足以下至少一个条件的章节，才保留在主体中：
  • 需要跨多个章节或文件协调的复杂多步骤流程
  • 无明确逻辑、参数或决策规则，若不内嵌指导Agent极易出错的内容
  • 该Skill独有的、无外部文档可参考的概念
  • Skill存在的核心用例（Agent最常调用的功能）
其他所有内容都应移至对应的
references/
文件中。具体哪些内容适合保留或迁移，请参考操作手册决策树中的示例。
描述压缩规则：
  1. 以工具/包名称和一行定位语开头
  2. 将4个及以上具体名称（API、检查项、步骤）的枚举替换为基于类别的表述（例如，用“认证、会话、令牌相关钩子”替代逐个列出每个钩子名称）
  3. 为通用关键词添加Skill领域限定，以减少误判（例如，用“MyLib与Redis的集成”而非“Redis集成”）
  4. 将同一主题的内容合并为一行（例如，“错误处理” + “重试逻辑” → “MyLib中的错误处理与重试逻辑”）
  5. 确保所有原始触发类别与压缩后的版本一一对应——不得遗漏任何类别
规划参考指南章节——为每个参考文件编写一行描述，说明何时需要查阅该文件。此章节至关重要：它会告知Agent应查阅哪个文件。
目标指标：
  • 主体内容：约250行以内
  • 描述：约700字符以内
  • 与参考文件的重复率：0%

Phase 3: Execute

第三阶段：执行

Apply the plan. Work in this order:
  1. Compress the description — rewrite the YAML 
    description
    field. Keep all trigger categories; do not remove any "when to use" signals.
  2. Remove duplicate sections from body — delete sections already covered in references.
  3. Add the Reference Guide section — add explicit pointers to each reference file with descriptions. See the playbook for the recommended format.
  4. Add a Maintenance Note — add a note at the bottom of the body with: (a) the body-line budget (~250 lines), (b) a pointer to the ADR if one exists, and (c) a one-sentence rationale for the split. See the playbook template.
  5. Bump version — increment 
    metadata.version
    minor if the skill uses versioning.
Do NOT:
  • Move "when to use" triggers from description to body (description is the only field read for triggering)
  • Remove code examples from retained body sections (they are the value)
  • Create new reference files just to move content — use existing files when possible
  • Add content that duplicates what is already in references
按照规划实施。请遵循以下顺序：
  1. 压缩描述——重写YAML的
    description
    字段。保留所有触发类别；不得移除任何“适用场景”相关信号。
  2. 移除主体中的重复章节——删除已在参考文件中覆盖的章节。
  3. 添加参考指南章节——添加指向每个参考文件的明确链接及描述。推荐格式请参考操作手册。
  4. 添加维护说明——在主体末尾添加说明，包含：(a) 主体行数预算（约250行），(b) 若有ADR则添加其链接，(c) 拆分决策的一句话理由。模板请参考操作手册。
  5. 版本升级——如果Skill使用版本控制，将
    metadata.version
    的次要版本号递增。
请勿：
  • 将描述中的“适用场景”触发条件移至主体中（只有描述字段会被用于触发判断）
  • 移除保留在主体中的代码示例（这些是核心价值）
  • 只为迁移内容而创建新的参考文件——尽可能使用现有文件
  • 添加与参考文件重复的内容

Phase 4: Validate

第四阶段：验证

Use the 
Task
tool to spawn a subagent (opus model) to challenge coverage. Provide it:
  1. The full SKILL.md (body + frontmatter)
  2. All reference files
  3. A list of 15-25 validation questions. Prompt the user (via 
    AskUserQuestion
    ) to provide questions the skill must answer. If the user declines or has none, derive them from the description trigger categories — see the playbook for derivation rules.
The subagent evaluates each question:
  • From SKILL.md alone: YES / PARTIAL / NO
  • From SKILL.md + references: YES / PARTIAL / NO
  • Gap: content missing from ALL files
Pass criteria:
  • 0 regressions (nothing answerable before that isn't answerable after)
  • All trigger categories in the description still present
  • Body under ~250 lines
If gaps are found, determine whether they are pre-existing (never covered) or regressions (lost during optimization). Only regressions require fixes — restore or rewrite the missing content in the body or appropriate reference file, then re-evaluate only the affected questions.
Fallback: If subagent spawning is unavailable, self-evaluate: for each question, attempt to answer it using only the optimized files and rate confidence as HIGH / MEDIUM / LOW. Any LOW-confidence answer on a question that was previously answerable is a regression.
使用
Task
工具生成一个子Agent（opus模型）来验证覆盖范围。需提供：
  1. 完整的SKILL.md（主体+前置元数据）
  2. 所有参考文件
  3. 15-25个验证问题。请通过
    AskUserQuestion
    提示用户    提供Skill必须能回答的问题。若用户拒绝提供或没有问题，则从描述的触发类别中推导——推导规则请参考操作手册。
子Agent会对每个问题进行评估：
  • 仅使用SKILL.md：是/部分/否
  • 使用SKILL.md + 参考文件：是/部分/否
  • 缺口：所有文件中均缺失的内容
通过标准：
  • 0回归（优化前能回答的内容，优化后仍能回答）
  • 描述中的所有触发类别仍全部存在
  • 主体内容在约250行以内
若发现缺口，需判断其为原有缺口（从未被覆盖）还是回归缺口（优化过程中丢失）。仅回归缺口需要修复——在主体或对应参考文件中恢复或重写缺失的内容，然后仅重新评估受影响的问题。
**备选方案：**若无法生成子Agent，则自行评估：针对每个问题，尝试仅使用优化后的文件作答，并将置信度评为高/中/低。任何之前能回答但现在置信度为低的问题均属于回归。

Output

输出

After validation, produce a summary table:
| Metric            | Before | After  | Change |
|-------------------|--------|--------|--------|
| Description chars | ???    | ???    | -??%   |
| Body lines        | ???    | ???    | -??%   |
| Body tokens (est.)| ???    | ???    | -??%   |
| Duplication %     | ???    | 0%     | -??%   |
| Regressions       | n/a    | 0      |        |
验证完成后，生成如下汇总表格：
| Metric            | Before | After  | Change |
|-------------------|--------|--------|--------|
| Description chars | ???    | ???    | -??%   |
| Body lines        | ???    | ???    | -??%   |
| Body tokens (est.)| ???    | ???    | -??%   |
| Duplication %     | ???    | 0%     | -??%   |
| Regressions       | n/a    | 0      |        |

Reference

参考

For detailed checklists, before/after examples, and the full validation methodology, see optimization-playbook.md.
详细的检查清单、前后对比示例及完整验证方法，请参考optimization-playbook.md。

Maintenance Note

维护说明

Body budget: ~120 lines (general target for optimized skills: ~250). The optimization workflow and decision rules are the core value and stay in the body; expanded examples, checklists, and the decision tree live in the playbook reference.
主体行数预算：约120行（优化后Skill的通用目标为约250行）。优化工作流与决策规则为核心内容，保留在主体中；扩展示例、检查清单及决策树则存放于操作手册参考文件中。