skill-registry
Create or update the skill registry for the current project. Scans user skills and project conventions, writes .atl/skill-registry.md, and saves to engram if available. Trigger: When user says "update skills", "skill registry", "actualizar skills", "update registry", or after installing/removing skills.
Best use case
skill-registry is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Create or update the skill registry for the current project. Scans user skills and project conventions, writes .atl/skill-registry.md, and saves to engram if available. Trigger: When user says "update skills", "skill registry", "actualizar skills", "update registry", or after installing/removing skills.
Teams using skill-registry should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/skill-registry/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How skill-registry Compares
| Feature / Agent | skill-registry | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Create or update the skill registry for the current project. Scans user skills and project conventions, writes .atl/skill-registry.md, and saves to engram if available. Trigger: When user says "update skills", "skill registry", "actualizar skills", "update registry", or after installing/removing skills.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
## Purpose
You generate or update the **skill registry** — a catalog of all available skills with **compact rules** (pre-digested, 5-15 line summaries) that any delegator injects directly into sub-agent prompts. Sub-agents do NOT read the registry or individual SKILL.md files — they receive compact rules pre-resolved in their launch prompt.
This is the foundation of the **Skill Resolver Protocol** (see `_shared/skill-resolver.md`). The registry is built ONCE (expensive), then read cheaply at every delegation.
## 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
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
2. **SKIP `sdd-*` and `_shared`** — those are SDD workflow skills, not coding/task skills
3. Also **SKIP `skill-registry`** — that's this skill
4. **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.
5. For each skill found, read the **full SKILL.md** (if a SKILL.md exceeds 200 lines, focus on the frontmatter and Critical Patterns / Rules sections only) to extract:
- `name` field (from frontmatter)
- `description` field → extract the trigger text (after "Trigger:" in the description)
- **Compact rules** — the actionable patterns and constraints (see Step 1b)
6. Build a table of: Trigger | Skill Name | Full Path
### Step 1b: Generate Compact Rules
For each skill found in Step 1, generate a **compact rules block** (5-15 lines max) containing ONLY:
- Actionable rules and constraints ("do X", "never Y", "prefer Z over W")
- Key patterns with one-line examples where critical
- Breaking changes or gotchas that would cause bugs if missed
**DO NOT include**: purpose/motivation, when-to-use, full code examples, installation steps, or anything the sub-agent doesn't need to APPLY the skill.
Format per skill:
```markdown
### {skill-name}
- Rule 1
- Rule 2
- ...
```
**Example** — compact rules for a React 19 skill:
```markdown
### react-19
- No useMemo/useCallback — React Compiler handles memoization automatically
- use() hook for promises/context, replaces useEffect for data fetching
- Server Components by default, add 'use client' only for interactivity/hooks
- ref is a regular prop — no forwardRef needed
- Actions: use useActionState for form mutations, useOptimistic for optimistic UI
- Metadata: export metadata object from page/layout, no <Head> component
```
**The compact rules are the MOST IMPORTANT output of this skill.** They are what sub-agents actually receive. Invest time making them accurate and concise.
### Step 2: Scan Project Conventions
1. 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`
2. **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.
3. For non-index files (`.cursorrules`, `CLAUDE.md`, etc.): record the file directly.
4. 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
**Delegator use only.** Any agent that launches sub-agents reads this registry to resolve compact rules, then injects them directly into sub-agent prompts. Sub-agents do NOT read this registry or individual SKILL.md files.
See `_shared/skill-resolver.md` for the full resolution protocol.
## User Skills
| Trigger | Skill | Path |
|---------|-------|------|
| {trigger from frontmatter} | {skill name} | {full path to SKILL.md} |
| ... | ... | ... |
## Compact Rules
Pre-digested rules per skill. Delegators copy matching blocks into sub-agent prompts as `## Project Standards (auto-resolved)`.
### {skill-name-1}
- Rule 1
- Rule 2
- ...
### {skill-name-2}
- Rule 1
- Rule 2
- ...
{repeat for each skill}
## 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
```markdown
## Skill Registry Updated
**Project**: {project name}
**Location**: .atl/skill-registry.md
**Engram**: {saved / not available}
### User Skills Found
| Skill | Trigger |
|-------|---------|
| {name} | {trigger} |
| ... | ... |
### Project Conventions Found
| 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.
```
## 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
- Read SKILL.md files (respecting the 200-line guard in Step 1) to generate accurate compact rules — this is a build-time cost, not a runtime cost
- Compact rules MUST be 5-15 lines per skill — concise, actionable, no fluff
- 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 listedRelated Skills
skill-creator
Creates new AI agent skills following the Agent Skills spec. Trigger: When user asks to create a new skill, add agent instructions, or document patterns for AI.
sdd-verify
Validate that implementation matches specs, design, and tasks. Trigger: When the orchestrator launches you to verify a completed (or partially completed) change.
sdd-tasks
Break down a change into an implementation task checklist. Trigger: When the orchestrator launches you to create or update the task breakdown for a change.
sdd-spec
Write specifications with requirements and scenarios (delta specs for changes). Trigger: When the orchestrator launches you to write or update specs for a change.
sdd-propose
Create a change proposal with intent, scope, and approach. Trigger: When the orchestrator launches you to create or update a proposal for a change.
sdd-init
Initialize Spec-Driven Development context in any project. Detects stack, conventions, testing capabilities, and bootstraps the active persistence backend. Trigger: When user wants to initialize SDD in a project, or says "sdd init", "iniciar sdd", "openspec init".
sdd-explore
Explore and investigate ideas before committing to a change. Trigger: When the orchestrator launches you to think through a feature, investigate the codebase, or clarify requirements.
sdd-design
Create technical design document with architecture decisions and approach. Trigger: When the orchestrator launches you to write or update the technical design for a change.
sdd-archive
Sync delta specs to main specs and archive a completed change. Trigger: When the orchestrator launches you to archive a change after implementation and verification.
sdd-apply
Implement tasks from the change, writing actual code following the specs and design. Trigger: When the orchestrator launches you to implement one or more tasks from a change.
judgment-day
Parallel adversarial review protocol that launches two independent blind judge sub-agents simultaneously to review the same target, synthesizes their findings, applies fixes, and re-judges until both pass or escalates after 2 iterations. Trigger: When user says "judgment day", "judgment-day", "review adversarial", "dual review", "doble review", "juzgar", "que lo juzguen".
issue-creation
Issue creation workflow for Agent Teams Lite following the issue-first enforcement system. Trigger: When creating a GitHub issue, reporting a bug, or requesting a feature.