v1.0 to v1.0

- description: "Create or update the project skill registry. Trigger: update skills, skill registry, actualizar skills, or after skill changes."

- ## 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):**

- - `~/.pi/agent/skills/` — Pi/Gentle AI user skills

- - `~/.config/agents/skills/`, `~/.agents/skills/`, `~/.kimi/skills/` — generic Agent Skills / Kimi-compatible locations

- - `~/.config/opencode/skills/` — OpenCode

- - `~/.config/kilo/skills/` — Kilo Code

- - `~/.claude/skills/` — Claude Code

- - `~/.gemini/skills/` — Gemini CLI

- - `~/.gemini/antigravity/skills/` — Antigravity

- - `~/.cursor/skills/` — Cursor

- - `~/.copilot/skills/` — VS Code Copilot

- - `~/.codex/skills/` — Codex

- - `~/.codeium/windsurf/skills/` — Windsurf

- - `~/.qwen/skills/` — Qwen Code

- - `~/.kiro/skills/` — Kiro

- - `~/.openclaw/skills/` — OpenClaw

-

- **Project-level (workspace skills):**

- - `{project-root}/skills/` — Generic repo skills

- - `{project-root}/.opencode/skills/` — OpenCode workspace skills

- - `{project-root}/.claude/skills/` — Claude Code workspace skills

- - `{project-root}/.gemini/skills/` — Gemini CLI workspace skills

- - `{project-root}/.cursor/skills/` — Cursor workspace skills

- - `{project-root}/.github/skills/` — VS Code Copilot workspace skills

- - `{project-root}/.codex/skills/` — Codex workspace skills

- - `{project-root}/.qwen/skills/` — Qwen Code workspace skills

- - `{project-root}/.kiro/skills/` — Kiro workspace skills

- - `{project-root}/.openclaw/skills/` — OpenClaw workspace skills

- - `{project-root}/.pi/skills/`, `{project-root}/.agent/skills/`, `{project-root}/.agents/skills/`, `{project-root}/.atl/skills/` — Gentle AI/Pi and generic workspace skills

-

- 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}",

- capture_prompt: false,

- content: "{registry markdown from Step 3}"

- )

- ```

-

- `capture_prompt: false` is required because the skill registry is an automated artifact, not a human/proactive memory save. Set it when the Engram tool schema supports it; if an older schema rejects or does not expose the field, omit it rather than failing.

-

- `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 listed