Skill Registry

Skill Registry

Role: Skill Indexer. You scan all available skills (project-level and global) and build a searchable index stored in Engram. Subagents query this index to lazy-load skills on demand — they load only what they need, when they need it.

This is the difference between loading all skills upfront (expensive context) vs loading the right skill at the right moment (clean context).

Process

Step 1 — Discover skills

# Project-level skills (takes priority)
find .claude/skills .agents/skills .copilot/skills -name "SKILL.md" 2>/dev/null

# Global skills
ls ~/.agents/skills/
ls ~/.copilot/skills/ 2>/dev/null

Step 2 — Extract metadata from each SKILL.md

For each skill found, extract:

• name — from frontmatter
• description — from frontmatter (this is the search trigger text)
• path — full absolute path to SKILL.md
• source — project (local) or global (user-level)

# Example: extract frontmatter from a skill
head -10 ~/.agents/skills/ralph/SKILL.md

Step 3 — Build the registry file

Create .atl/skill-registry.md in the project root:

# Skill Registry
# Auto-generated by skill-registry. Do not edit manually.
# Last updated: <date>

## Available Skills

| name | description | path | source |
|------|-------------|------|--------|
| ralph | Autonomous dev subagent that implements... | ~/.agents/skills/ralph/SKILL.md | global |
| spec-writer | Spec Driven Development agent... | ~/.agents/skills/spec-writer/SKILL.md | global |
| evaluator | Adversarial QA evaluator... | ~/.agents/skills/evaluator/SKILL.md | global |
...

Create the .atl/ directory if it doesn't exist:

mkdir -p .atl

Step 4 — Store in Engram

Save the registry to Engram so any agent in any session can query it:

# Save the full registry as a single memory
engram save "skill-registry: <project-name>" \
  "$(cat .atl/skill-registry.md)" \
  --type context

# Also save each skill individually for targeted search
# (do this for the 10 most commonly needed skills)
engram save "skill: ralph — autonomous dev implementer" \
  "Path: ~/.agents/skills/ralph/SKILL.md. Use when: implementing user stories, parallel dev, Generator→Evaluator loop." \
  --type context

engram save "skill: spec-writer — SDD technical spec" \
  "Path: ~/.agents/skills/spec-writer/SKILL.md. Use when: need formal spec before coding, SDD, API contracts, type definitions." \
  --type context

# ... repeat for key skills

Step 5 — Commit to repo

git add .atl/skill-registry.md
git commit -m "chore: update skill registry

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"

How subagents use the registry

Any agent that needs a skill but doesn't know which one:

# Query Engram first
engram search "how to write technical specs" --type context --limit 3
# → returns "skill: spec-writer" memory with path
# → agent loads that specific SKILL.md

# Or read the registry file directly (no Engram needed)
cat .atl/skill-registry.md | grep -i "spec\|tdd\|implement"

Lazy loading pattern

Instead of: "Load all skills at session start" (expensive)

Do this:

1. Orchestrator starts — loads skill-registry only (tiny file)
2. When a task needs implementation → query registry → load ralph
3. When a task needs specs → query registry → load spec-writer
4. When build breaks → query registry → load tester
5. Each subagent loads ONLY its own skill

This keeps the orchestrator context clean (~1-4% usage) regardless of how many skills exist.

Completion Signal

SKILL_REGISTRY_DONE: {
  "total_skills": <N>,
  "project_skills": <N>,
  "global_skills": <N>,
  "registry_path": ".atl/skill-registry.md",
  "engram_saved": true
}