skill-registry

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Purpose

用途

You generate or update the skill registry — a catalog of all available skills (user-level and project-level) that the orchestrator reads once per session and uses to pass pre-resolved skill paths to sub-agents. Sub-agents do NOT read the registry themselves; the orchestrator resolves all paths and injects them into each sub-agent's launch prompt.

你需要生成或更新技能注册表——这是一个包含所有可用技能（用户级和项目级）的目录，orchestrator会在每个会话中读取一次，并将预解析的技能路径传递给sub-agents。Sub-agents不会自行读取注册表；orchestrator会解析所有路径并将其注入到每个sub-agent的启动提示中。

When to Run

运行时机

After installing or removing skills
After setting up a new project
When the user explicitly asks to update the registry
As part of
```
sdd-init
```
(it calls this same logic)

在安装或移除技能之后
在新建项目完成设置之后
当用户明确要求更新注册表时
作为
```
sdd-init
```
的一部分（它会调用相同的逻辑）

What to Do

执行步骤

Step 1: Scan User Skills

步骤1：扫描用户技能

Glob for
```
*/SKILL.md
```
files across ALL known skill directories. Check every path below — scan ALL that exist, not just the first match:
User-level (global skills):
- ```
~/.claude/skills/
```
  — Claude Code
- ```
~/.config/opencode/skills/
```
  — OpenCode
- ```
~/.gemini/skills/
```
  — Gemini CLI
- ```
~/.cursor/skills/
```
  — Cursor
- ```
~/.copilot/skills/
```
  — VS Code Copilot
- The parent directory of this skill file (catch-all for any tool)
Project-level (workspace skills):
- ```
{project-root}/.claude/skills/
```
  — Claude Code
- ```
{project-root}/.gemini/skills/
```
  — Gemini CLI
- ```
{project-root}/.agent/skills/
```
  — Antigravity (workspace)
- ```
{project-root}/skills/
```
  — Generic
SKIP
sdd-*
and
_shared
— those are SDD workflow skills, not coding/task skills
Also SKIP
skill-registry
— that's this skill
Deduplicate — if the same skill name appears in multiple locations, keep the project-level version (more specific). If both are user-level, keep the first found.
For each skill found, read only the frontmatter (first 10 lines) to extract:
- ```
name
```
  field
- ```
description
```
  field → extract the trigger text (after "Trigger:" in the description)
Build a table of: Trigger | Skill Name | Full Path

在所有已知技能目录中全局查找
```
*/SKILL.md
```
文件。检查以下所有路径——扫描所有存在的路径，而非仅第一个匹配项：
用户级（全局技能）：
- ```
~/.claude/skills/
```
  — Claude Code
- ```
~/.config/opencode/skills/
```
  — OpenCode
- ```
~/.gemini/skills/
```
  — Gemini CLI
- ```
~/.cursor/skills/
```
  — Cursor
- ```
~/.copilot/skills/
```
  — VS Code Copilot
- 此技能文件的父目录（适用于任意工具的兜底路径）
项目级（工作区技能）：
- ```
{project-root}/.claude/skills/
```
  — Claude Code
- ```
{project-root}/.gemini/skills/
```
  — Gemini CLI
- ```
{project-root}/.agent/skills/
```
  — Antigravity（工作区）
- ```
{project-root}/skills/
```
  — 通用路径
跳过
sdd-*
和
_shared
——这些是SDD工作流技能，而非编码/任务技能
同时跳过
skill-registry
——这正是当前技能本身
去重——若同一技能名称出现在多个位置，保留项目级版本（更具针对性）。若均为用户级，则保留第一个找到的版本
对于每个找到的技能，仅读取其前置元数据（前10行）以提取：
- ```
name
```
  字段
- ```
description
```
  字段 → 提取触发文本（description中"Trigger:"之后的内容）
构建表格：触发词 | 技能名称 | 完整路径

Step 2: Scan Project Conventions

步骤2：扫描项目约定

Check the project root for convention files. Look for:

```
agents.md
```
or
```
AGENTS.md
```
```
CLAUDE.md
```
(only project-level, not
```
~/.claude/CLAUDE.md
```
)
```
.cursorrules
```
```
GEMINI.md
```
```
copilot-instructions.md
```

If an index file is found (e.g.,
```
agents.md
```
,
```
AGENTS.md
```
): READ its contents and extract all referenced file paths. These index files typically list project conventions with paths — extract every referenced path and include it in the registry table alongside the index file itself.
For non-index files (
```
.cursorrules
```
,
```
CLAUDE.md
```
, etc.): record the file directly.
The final table should include the index file AND all paths it references — zero extra hops for sub-agents.

检查项目根目录下的约定文件，查找：

```
agents.md
```
或
```
AGENTS.md
```
```
CLAUDE.md
```
（仅项目级，非
```
~/.claude/CLAUDE.md
```
）
```
.cursorrules
```
```
GEMINI.md
```
```
copilot-instructions.md
```

若找到索引文件（如
```
agents.md
```
、
```
AGENTS.md
```
）：读取其内容并提取所有引用的文件路径。这些索引文件通常会列出带有路径的项目约定——提取所有引用路径，并将其与索引文件本身一同纳入注册表表格
对于非索引文件（
```
.cursorrules
```
、
```
CLAUDE.md
```
等）：直接记录该文件
最终表格应包含索引文件及其所有引用的路径——sub-agents无需额外跳转即可获取信息

Step 3: Write the Registry

步骤3：编写注册表

Build the registry markdown:

markdown

undefined

构建注册表Markdown内容：

markdown

undefined

Skill Registry

Orchestrator use only. Read this registry once per session to resolve skill paths, then pass pre-resolved paths directly to each sub-agent's launch prompt. Sub-agents receive the path and load the skill directly — they do NOT read this registry.

User Skills

Trigger	Skill	Path
{trigger from frontmatter}	{skill name}	{full path to SKILL.md}
...	...	...

Trigger	Skill	Path
{trigger from frontmatter}	{skill name}	{full path to SKILL.md}
...	...	...

Project Conventions

File	Path	Notes
{index file}	{path}	Index — references files below
{referenced file}	{extracted path}	Referenced by {index file}
{standalone file}	{path}

Read the convention files listed above for project-specific patterns and rules. All referenced paths have been extracted — no need to read index files to discover more.

undefined

File	Path	Notes
{index file}	{path}	Index — references files below
{referenced file}	{extracted path}	Referenced by {index file}
{standalone file}	{path}

Read the convention files listed above for project-specific patterns and rules. All referenced paths have been extracted — no need to read index files to discover more.

undefined

Step 4: Persist the Registry

步骤4：持久化注册表

This step is MANDATORY — do NOT skip it.

此步骤为必填项——请勿跳过。

A. Always write the file (guaranteed availability):

A. 始终写入文件（确保可用性）：

Create the

.atl/

directory in the project root if it doesn't exist, then write:

.atl/skill-registry.md

若项目根目录下不存在

.atl/

目录则创建它，然后写入：

.atl/skill-registry.md

B. If engram is available, also save to engram (cross-session bonus):

B. 若engram可用，同时保存至engram（跨会话额外功能）：

mem_save(
  title: "skill-registry",
  topic_key: "skill-registry",
  type: "config",
  project: "{project}",
  content: "{registry markdown from Step 3}"
)

topic_key

ensures upserts — running again updates the same observation.

mem_save(
  title: "skill-registry",
  topic_key: "skill-registry",
  type: "config",
  project: "{project}",
  content: "{registry markdown from Step 3}"
)

topic_key

确保会执行更新操作——再次运行时会覆盖同一记录。

Step 5: Return Summary

步骤5：返回摘要

markdown

undefined

markdown

undefined

Skill Registry Updated

Project: {project name} Location: .atl/skill-registry.md Engram: {saved / not available}

User Skills Found

Skill	Trigger
{name}	{trigger}
...	...

Skill	Trigger
{name}	{trigger}
...	...

Project Conventions Found

File	Path
{file}	{path}

File	Path
{file}	{path}

Next Steps

The orchestrator reads this registry once per session and passes pre-resolved skill paths to sub-agents via their launch prompts. To update after installing/removing skills, run this again.

undefined

The orchestrator reads this registry once per session and passes pre-resolved skill paths to sub-agents via their launch prompts. To update after installing/removing skills, run this again.

undefined

Rules

规则

ALWAYS write
```
.atl/skill-registry.md
```
regardless of any SDD persistence mode
ALWAYS save to engram if the
```
mem_save
```
tool is available
SKIP
```
sdd-*
```
,
```
_shared
```
, and
```
skill-registry
```
directories when scanning
Only read frontmatter (first 10 lines) — do NOT read full skill files
Include ALL convention index files found (not just the first)
If no skills or conventions are found, write an empty registry (so sub-agents don't waste time searching)
Add
```
.atl/
```
to the project's
```
.gitignore
```
if it exists and
```
.atl
```
is not already listed

无论SDD持久化模式如何，始终要写入
.atl/skill-registry.md
若
```
mem_save
```
工具可用，始终要保存至engram
扫描时跳过
sdd-*
、
_shared
和
skill-registry
目录
仅读取前置元数据（前10行）——请勿读取完整技能文件
纳入所有找到的约定索引文件（而非仅第一个）
若未找到任何技能或约定，写入空注册表（避免sub-agents浪费时间搜索）
若项目的
```
.gitignore
```
已存在且未列出
```
.atl
```
，则将
```
.atl/
```
添加进去