skill-organizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Organizer

Reads all installed skills, identifies overlaps and confusability, merges where appropriate, and produces a compact

SKILL_REGISTRY.md

that serves as a routing guide in agent system prompts.

读取所有已安装的Skill，识别重叠和易混淆的Skill，在合适的情况下进行合并，最终生成精简的

SKILL_REGISTRY.md

文件，作为Agent系统提示中的路由指南。

Why This Exists

设计初衷

Models have a skill selection capacity (kappa) of approximately 50-100 items. Beyond that, selection accuracy degrades. As skills accumulate through log analysis and manual creation, the skill library can cross this threshold. This skill keeps the library organized and the routing guide compact.

Reference: Scaling LLM Agents with Skill Libraries

模型的Skill选择容量（kappa）约为50-100项，超过这个阈值后选择准确率就会下降。随着通过日志分析和手动创建的Skill不断积累，Skill库很容易突破这个阈值。这个Skill可以保持Skill库井然有序，同时让路由指南保持精简。

参考资料：Scaling LLM Agents with Skill Libraries

Workflow

工作流程

Step 1: Inventory

步骤1：清点库存

List all skill directories in the .agent/skills/ folder.

Then read each skill's SKILL.md to understand scope, quality, and overlap. Each skill lives in a subdirectory of .agent/skills/ with a SKILL.md file.

列出.agent/skills/文件夹下的所有Skill目录，然后读取每个Skill的SKILL.md文件，了解其适用范围、质量和重叠情况。每个Skill都存放在.agent/skills/的子目录中，且都包含一个SKILL.md文件。

Step 2: Identify overlapping or confusable skills

步骤2：识别重叠或易混淆的Skill

Look for:

Skills that do the same thing with slightly different names
Skills whose scopes significantly overlap (one is a subset of another)
Skills that could be combined into a single broader skill with multiple sections
Near-duplicate skills created from different log analysis sessions

需要排查的情况包括：

功能相同但名称略有差异的Skill
适用范围高度重叠的Skill（其中一个是另一个的子集）
可以合并为一个涵盖多个模块的更宽泛Skill的多个Skill
不同日志分析会话生成的近乎重复的Skill

Step 3: Merge into hierarchical parent skills

步骤3：合并为层级化的父Skill

For each group of overlapping or related skills, create a single parent skill with sections covering each sub-capability:

Choose a broader parent name and directory (e.g.,
```
web-app-dev
```
instead of separate
```
react-frontend
```
,
```
nodejs-backend
```
,
```
web-testing
```
)
Write one comprehensive SKILL.md with clearly labeled sections for each sub-capability. Each section should be self-contained enough that an agent can read just that section for a focused task.
Move bundled resources (templates, examples, configs) from merged skills into subdirectories of the parent skill directory.
Remove the redundant skill directories.

When merging, prefer the skill with:

Better-quality instructions and examples
More complete bundled resources
A more descriptive, general name

The goal is fewer, richer skills — a parent skill with 4 well-written sections is better than 4 separate shallow skills.

针对每一组重叠或相关的Skill，创建一个唯一的父Skill，其下的不同模块覆盖所有子能力：

选择一个更宽泛的父级名称和目录（例如使用
```
web-app-dev
```
作为父目录，而不是单独的
```
react-frontend
```
、
```
nodejs-backend
```
、
```
web-testing
```
）
编写一份完整的SKILL.md，为每个子能力标注清晰的模块。每个模块应该足够独立，Agent可以仅读取对应模块即可完成特定任务。
将被合并Skill中的捆绑资源（模板、示例、配置文件）移动到父Skill目录的子目录中。
删除冗余的Skill目录。

合并时优先保留符合以下条件的Skill：

指令和示例质量更高
捆绑资源更完整
名称更具描述性、更通用

目标是减少Skill数量、提升单个Skill的丰富度——一个包含4个编写精良模块的父Skill，要好过4个独立的浅度Skill。

Step 4: Generate SKILL_REGISTRY.md

步骤4：生成SKILL_REGISTRY.md

Write

.agent/skills/SKILL_REGISTRY.md

as a compact routing guide:

markdown

undefined

编写

.agent/skills/SKILL_REGISTRY.md

作为精简的路由指南：

markdown

undefined

Skill Registry

<Category> (<count>)

skill-name: What it does in one sentence. Use when: <trigger condition — when should the agent read this skill?> Sections: <comma-separated list of sections/sub-capabilities within the skill>
skill-name: What it does in one sentence. Use when: <trigger condition>

skill-name: What it does in one sentence. Use when: <trigger condition — when should the agent read this skill?> Sections: <comma-separated list of sections/sub-capabilities within the skill>
skill-name: What it does in one sentence. Use when: <trigger condition>

Recently Added

new-skill (project): Frontmatter description — not yet categorized


The registry should:
- Group skills by purpose/domain (not alphabetically)
- For each skill, include: what it does, when to read it, and what sections it contains
- The "Use when" line is critical — it tells agents when to load the full SKILL.md
- The "Sections" line (when applicable) shows what sub-capabilities live inside the skill
- Stay under 50 entries total (merge aggressively if needed)
- Include a "Recently Added" section for skills created since last organization
- NOT duplicate full skill content, just enough for selection routing

new-skill (project): Frontmatter description — not yet categorized


该注册表应该满足以下要求：
- 按用途/领域对Skill分组（而非按字母顺序排序）
- 每个Skill需要包含：功能说明、适用场景、包含的模块列表
- “Use when”行至关重要——它告诉Agent什么时候需要加载完整的SKILL.md
- “Sections”行（如果有）展示Skill内部包含的子能力
- 总条目数保持在50条以内（必要时可以激进合并）
- 包含“最近新增”模块，用于存放上次整理后新创建的Skill
- 不要复制完整的Skill内容，只保留足够用于选择路由的信息即可

Step 5: Report

步骤5：生成报告

Summarize what you did:

How many skills were found
Which skills were merged (old names -> new name)
Which skills were kept as-is
The final registry structure

总结你的操作：

共清点到多少个Skill
哪些Skill被合并（旧名称 -> 新名称）
哪些Skill保持原样保留
最终的注册表结构

Constraints

约束条件

Do NOT use keyword matching, Jaccard similarity, or heuristic categorization. Use your understanding of what each skill does.
Be aggressive about merging: fewer high-quality skills beats many overlapping ones.
Preserve all bundled resources (templates, examples, configs) during merges.
The SKILL_REGISTRY.md is a routing guide, not documentation. Keep it concise.
Skills in
```
massgen/skills/
```
(builtin) should not be merged or deleted, only cataloged in the registry.

不要使用关键词匹配、Jaccard相似度或启发式分类，要基于你对每个Skill功能的理解进行操作。
合并时可以更激进：少量高质量的Skill远好于大量重叠的Skill。
合并过程中要保留所有捆绑资源（模板、示例、配置文件）。
SKILL_REGISTRY.md是路由指南，不是文档，请保持精简。
```
massgen/skills/
```
中的内置Skill不能合并或删除，仅需在注册表中进行分类收录。