optimize-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Optimizing Skills

优化技能

Use this skill to create, review, or improve SKILL.md-based skills so they trigger correctly, stay concise, and execute reliably.

本技能用于创建、审查或改进基于SKILL.md的技能，使其能正确触发、保持简洁并可靠执行。

When to Use

适用场景

Creating a new reusable skill from repeated work patterns.
Updating an existing skill that under-triggers, over-triggers, or misfires.
Tightening a skill that is too long, redundant, or hard to execute.
Converting narrative guidance into concise, imperative instructions.
Rebalancing where content should live across
```
SKILL.md
```
,
```
references/
```
,
```
assets/
```
, and
```
scripts/
```
.

从重复的工作模式中创建新的可复用技能。
更新触发不足、触发过度或触发错误的现有技能。
精简过长、冗余或难以执行的技能。
将叙述性指导转换为简洁的命令式指令。
重新平衡内容在
```
SKILL.md
```
、
```
references/
```
、
```
assets/
```
和
```
scripts/
```
之间的存放位置。

Overview

概述

What is a Skill?

什么是Skill？

A skill is a reference guide for proven techniques, patterns, or tools, typically classed as procedural knowledge or best practices. Skills help future Agent instances find and apply effective approaches.

Skills are: Reusable techniques, patterns, tools, reference guides

Skills are NOT: Narratives about how you solved a problem once

Skill是经过验证的技术、模式或工具的参考指南，通常归类为程序性知识或最佳实践。Skill可帮助未来的Agent实例找到并应用有效的解决方法。

Skill的定义： 可复用的技术、模式、工具、参考指南

Skill不属于： 关于你一次性解决某个问题的叙述性内容

When to Create a Skill

何时创建Skill

Create when:

Technique wasn't intuitively obvious to you or required multiple iterations to get right.
You'd reference this again across projects / Others would benefit from knowing this.
Pattern applies broadly (not project-specific)
Triggerable by specific user intents or common failure modes.

Don't create for:

One-off solutions
Standard practices well-documented elsewhere
Project-specific conventions that aren't broadly applicable

创建时机：

该技术对你而言并非直观易懂，或需要多次迭代才能掌握。
你会在多个项目中再次参考它 / 其他人也会从了解它中获益。
该模式具有广泛适用性（而非特定项目专属）。
可被特定用户意图或常见故障场景触发。

无需创建的情况：

一次性解决方案
其他地方已有完善文档的标准实践
仅适用于特定项目的约定

Workflow

工作流

Phase 1: Preparation

阶段1：准备工作

Choose the path:
- New skill: initialize scaffold and baseline structure.
- Existing skill: load current
```
SKILL.md
```
  and related resources as baseline.
Define the target workflow first:
- List the execution steps in order, including prerequisites, gates, and outputs.
- Keep steps imperative and executable.
Determine trigger scenarios in working notes:
- Capture 2-3 scenarios that must trigger the skill.
- Capture up to 2 scenarios that must not trigger the skill.
Decide whether a flowchart is required:
- Use markdown-only workflow when flow is linear and obvious.
- Add a small DOT flowchart only when branching/loops are non-obvious.

选择路径：
- 新技能：初始化脚手架和基础结构。
- 现有技能：加载当前的
```
SKILL.md
```
  及相关资源作为基准。
先定义目标工作流：
- 按顺序列出执行步骤，包括先决条件、关卡和输出。
- 保持步骤为命令式且可执行。
在工作笔记中确定触发场景：
- 记录2-3个必须触发该技能的场景。
- 记录最多2个不得触发该技能的场景。
决定是否需要流程图：
- 当流程为线性且清晰时，仅使用Markdown格式的工作流。
- 仅当分支/循环逻辑不明显时，添加小型内联DOT流程图。

Phase 2: Draft

阶段2：起草

Draft metadata and usage guidance from preparation:
- Keep frontmatter to
```
name
```
  and
```
description
```
  .
- Encode trigger scenarios in
```
description
```
  and
```
## When to Use
```
  (and
```
## When Not to Use
```
  when helpful).
Draft the skill body in imperative form:
- Keep instructions short, specific, and ordered by execution.
- Move deep detail to
```
references/
```
  ,
```
assets/
```
  , or
```
scripts/
```
  and link from
```
SKILL.md
```
  .

根据准备工作起草元数据和使用指南：
- 仅保留
```
name
```
  和
```
description
```
  作为前置元数据。
- 在
```
description
```
  和
```
## 适用场景
```
  （必要时可添加
```
## 不适用场景
```
  ）中明确触发场景。
以命令式风格起草技能主体：
- 保持指令简短、具体，并按执行顺序排列。
- 将详细内容移至
```
references/
```
  、
```
assets/
```
  或
```
scripts/
```
  ，并在
```
SKILL.md
```
  中添加链接。

Phase 3: Review and Optimize

阶段3：审查与优化

Run scenario and functional checks against realistic prompts.
Review resource fit:
- Confirm references/assets/scripts are sufficient and scoped.
- Offload verbose
```
SKILL.md
```
  sections into resources where appropriate.
Optimize the draft:
- Tighten triggering (under/over-triggering).
- Remove redundancy and improve progressive disclosure.
- Re-check whether flowchart usage is still justified.
Iterate until trigger behavior and execution quality both pass.

针对真实提示运行场景和功能检查。
审查资源适配性：
- 确认参考资料/资源/脚本足够且范围合适。
- 必要时将
```
SKILL.md
```
  中冗长的部分移至外部资源。
优化草稿：
- 优化触发逻辑（解决触发不足/过度问题）。
- 移除冗余内容，改进渐进式披露方式。
- 重新检查是否仍需使用流程图。
迭代直至触发行为和执行质量均达标。

Core Principles

核心原则

Optimize for triggering: description must emphasize when to use the skill (
```
references/skills-search-optimization.md
```
).
Treat trigger scenarios as authoring scaffolding; the final skill should expose triggers through
```
description
```
and
```
## When to Use
```
.
Keep frontmatter metadata small (about 100 tokens combined).
Keep main
```
SKILL.md
```
under 500 lines and focused on action.
Use progressive disclosure: metadata -> SKILL.md -> references/scripts/assets.
Choose the right degree of freedom: text, pseudocode, or scripts depending on fragility.
Prefer reusable resources (scripts, templates) over repeated prose.

以触发优化为核心：描述必须强调技能的适用场景（参考
```
references/skills-search-optimization.md
```
）。
将触发场景作为创作脚手架；最终技能需通过
```
description
```
和
```
## 适用场景
```
呈现触发条件。
保持前置元数据精简（合计约100个token）。
主
```
SKILL.md
```
文件控制在500行以内，聚焦于操作指令。
使用渐进式披露：元数据 -> SKILL.md -> 参考资料/脚本/资源。
选择合适的自由度：根据脆弱性选择文本、伪代码或脚本。
优先使用可复用资源（脚本、模板）而非重复的文字说明。

Progressive Disclosure Targets

渐进式披露目标

Metadata (
```
name
```
+
```
description
```
): small startup footprint, ideally ~100 tokens.
```
SKILL.md
```
: keep actionable and concise, target <5000 tokens and <500 lines.
```
scripts/
```
,
```
references/
```
,
```
assets/
```
: loaded only when needed; keep files narrow so agents pull less context.

元数据（
```
name
```
+
```
description
```
）：启动占用空间小，理想约100个token。
```
SKILL.md
```
：保持可操作且简洁，目标为<5000个token且<500行。
```
scripts/
```
、
```
references/
```
、
```
assets/
```
：仅在需要时加载；保持文件范围狭窄，减少Agent需拉取的上下文。

Flowchart Guidance

流程图指南

dot

digraph when_flowchart {
    "Need to show process guidance?" [shape=diamond];
    "Non-obvious decision or loop?" [shape=diamond];
    "Use markdown (list/table/code)" [shape=box];
    "Use small inline DOT flowchart" [shape=box];

    "Need to show process guidance?" -> "Non-obvious decision or loop?" [label="yes"];
    "Need to show process guidance?" -> "Use markdown (list/table/code)" [label="no"];
    "Non-obvious decision or loop?" -> "Use small inline DOT flowchart" [label="yes"];
    "Non-obvious decision or loop?" -> "Use markdown (list/table/code)" [label="no"];
}

Use markdown lists/tables/code blocks by default.
Add DOT only when decision logic or loops are easy to misapply.
Avoid placeholder node labels; use concrete actions and conditions.
Follow
```
references/graphviz-conventions.dot
```
for node shapes and labels.
Keep flowcharts small and trigger-based; split large flows into focused subgraphs.

Render DOT to SVG with

scripts/render-dot.py

. Output SVGs are written to the target skill's

assets/

directory.

bash

scripts/render-dot.py skills/optimize-skills/references/skill-workflow.dot
scripts/render-dot.py skills/optimize-skills/SKILL.md
scripts/render-dot.py skills/optimize-skills/SKILL.md --force # overwrite existing SVGs

dot

digraph when_flowchart {
    "Need to show process guidance?" [shape=diamond];
    "Non-obvious decision or loop?" [shape=diamond];
    "Use markdown (list/table/code)" [shape=box];
    "Use small inline DOT flowchart" [shape=box];

    "Need to show process guidance?" -> "Non-obvious decision or loop?" [label="yes"];
    "Need to show process guidance?" -> "Use markdown (list/table/code)" [label="no"];
    "Non-obvious decision or loop?" -> "Use small inline DOT flowchart" [label="yes"];
    "Non-obvious decision or loop?" -> "Use markdown (list/table/code)" [label="no"];
}

默认使用Markdown列表/表格/代码块。
仅当决策逻辑或循环容易被误用时，添加DOT流程图。
避免使用占位符节点标签；使用具体的操作和条件。
遵循
```
references/graphviz-conventions.dot
```
中的节点形状和标签规范。
保持流程图小巧且基于触发场景；将大型流程拆分为基于触发的子图。

使用

scripts/render-dot.py

将DOT渲染为SVG。输出的SVG将写入目标技能的

assets/

目录。

bash

scripts/render-dot.py skills/optimize-skills/references/skill-workflow.dot
scripts/render-dot.py skills/optimize-skills/SKILL.md
scripts/render-dot.py skills/optimize-skills/SKILL.md --force # overwrite existing SVGs

Output

输出

SKILL.md Structure

SKILL.md结构

txt

skills/
  skill-name/
    SKILL.md      # Main reference (required)
    assets/       # (optional) Static reusable resources such as templates or figures
    references/   # (optional) On-demand documentation, organized by topic or variant
    scripts/      # (optional) Executable helpers for deterministic tasks;
                  # scripts should be self-contained or clearly declare dependencies,
                  # include clear errors, and handle edge cases.

txt

skills/
  skill-name/
    SKILL.md      # 主参考文件（必填）
    assets/       # （可选）静态可复用资源，如模板或图表
    references/   # （可选）按需加载的文档，按主题或变体组织
    scripts/      # （可选）用于确定性任务的可执行辅助脚本；
                  # 脚本应独立运行或明确声明依赖项，
                  # 包含清晰的错误处理，并能处理边缘情况。

Rules

规则

SKILL.md must be named exactly
```
SKILL.md
```
.
Folder name must be kebab-case, matching the
```
name
```
in frontmatter.
Do not add README.md inside the skill.
YAML frontmatter must include
```
name
```
and
```
description
```
fields.
```
name
```
must be kebab-case and match the folder name.
```
description
```
should emphasize when to use the skill and include triggers/symptoms.
Avoid workflow summaries in the description.
Keep descriptions short and specific.
Prefer
```
## When to Use
```
/
```
## When Not to Use
```
for trigger cues; do not add a dedicated trigger-scenarios section unless explicitly requested by the repo.
Refer to
```
assets/skill-template.md
```
for a suggested (but easily modified) template structure.

技能文件必须命名为
```
SKILL.md
```
。
文件夹名称必须为短横线分隔的小写格式（kebab-case），与前置元数据中的
```
name
```
一致。
技能文件夹内不得添加README.md。
YAML前置元数据必须包含
```
name
```
和
```
description
```
字段。
```
name
```
必须为kebab-case格式且与文件夹名称一致。
```
description
```
应强调技能的适用场景，并包含触发条件/症状。
避免在描述中总结工作流。
保持描述简短且具体。
优先使用
```
## 适用场景
```
/
```
## 不适用场景
```
提供触发提示；除非仓库明确要求，否则不要添加专门的触发场景章节。
参考
```
assets/skill-template.md
```
获取建议的（但可灵活修改的）模板结构。

Common Mistakes

常见错误

Summarizing workflow in
```
description
```
instead of stating actionable triggers and symptoms.
Copying working trigger scenarios directly into the final skill instead of converting them into
```
description
```
and
```
## When to Use
```
.
Keeping workflows as one giant graph instead of splitting into trigger-based subgraphs.
Repeating deep reference material in
```
SKILL.md
```
instead of linking to
```
references/
```
.
Leaving scripts implicit: deterministic steps should be executable where possible.

在
```
description
```
中总结工作流，而非陈述可操作的触发条件和症状。
将工作笔记中的触发场景直接复制到最终技能中，而非转换为
```
description
```
和
```
## 适用场景
```
的内容。
将工作流保留为单个大型图表，而非拆分为基于触发的子图。
在
```
SKILL.md
```
中重复详细的参考资料，而非链接到
```
references/
```
。
未明确脚本：确定性步骤应尽可能可执行。

References

参考资料

```
assets/skill-template.md
```
for a suggested SKILL.md structure.
```
references/best-practices.md
```
: checklists, structure guidance, testing, and troubleshooting patterns.
```
references/skills-search-optimization.md
```
: description and trigger optimization rules.
```
references/skill-workflow.dot
```
: canonical workflow for this skill.
```
references/graphviz-conventions.dot
```
: DOT style and semantics for workflow diagrams.

```
assets/skill-template.md
```
：SKILL.md的建议结构。
```
references/best-practices.md
```
：检查清单、结构指南、测试和故障排除模式。

references/skills-search-optimization.md

：描述和触发优化规则。

```
references/skill-workflow.dot
```
：本技能的标准工作流。
```
references/graphviz-conventions.dot
```
：工作流图的DOT样式和语义规范。