# Skill Registry

> Indexes all available skills in the current project and stores them in Engram for lazy loading. Any subagent can then search for the right skill before executing a task instead of loading all skills upfront. Run once per project setup, then again when skills change. Triggered by: 'index skills', 'skill registry', 'register skills', 'update skill index', '/skill-registry'.

- Skill: `elihuvillaraus/skill-registry` (Agent Skill)
- Install (CLI): `npx skillmds@latest add elihuvillaraus/skill-registry`
- Raw SKILL.md: https://api.skillmd.com/api/skills/elihuvillaraus/skill-registry/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: elihuvillaraus (https://skillmd.com/u/elihuvillaraus)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/elihuvillaraus/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

```bash
# 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)

```bash
# 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:

```markdown
# 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:
```bash
mkdir -p .atl
```

### Step 4 — Store in Engram

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

```bash
# 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

```bash
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:
```bash
# 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
}
```