skill-registry

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.

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)

What to Do

Step 1: Scan User Skills

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

Step 2: Scan Project Conventions

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.

Step 3: Write the Registry

Build the registry markdown:

markdown

# 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} |
| ... | ... | ... |

## 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.

Step 4: Persist the Registry

This step is MANDATORY — do NOT skip it.

A. Always write the file (guaranteed availability):

Create the

.atl/

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

.atl/skill-registry.md

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

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.

Step 5: Return Summary