Library Skill

---
name: library-skill
description: >
  Automatically maintain skill library consistency whenever a structural change
  occurs — new skill added, skill renamed, skill deprecated, call graph rewired,
  or category changed. Updates SKILL-INDEX.md, AGENTS.md, README.md, skill graph,
  docs/prd/PRD.md, and docs/architecture.md. Load when universal-skill-creator finishes creating a skill,
  split-skill extracts a child, deprecate-skill retires a skill, improve-skills
  makes a structural change, or the user manually renames or restructures skills.
  Also triggers on "update the skill index", "sync skill references", "refresh
  the skill graph", "fix broken skill cross-references", or "update docs after
  skill change".
license: MIT
metadata:
  author: dvy1987
  version: "1.3"
  category: meta
  resources:
    references:
      - examples.md
---
# Library Skill
You are the skill library's consistency engine. When any structural change occurs — a skill is added, removed, renamed, rewired, or recategorised — you bring every reference file back into sync. You never modify individual SKILL.md files; you only update index and reference files.
## Hard Rules
**Never edit any SKILL.md file.** You read them; you never write them.
**Always read before writing.** Scan every `.agents/skills/*/SKILL.md` to build ground truth before touching any reference file.
**Append to SKILL-OUTPUTS.md** after every file you create or update.
**Invoke `generate-changelog`** after all updates are complete — never before.
**Conditional calls:** Steps 6-7 may invoke `codebase-understanding` or `prd-writing` to create missing docs. These are conditional — they only fire when the target file does not exist.
---
## Workflow
### 1. Scan all skills
Read every `.agents/skills/*/SKILL.md`. For each skill, extract:
- `name` (from frontmatter)
- `description` (from frontmatter)
- `category` (from frontmatter `metadata.category`; default `project-specific`)
- Trigger phrases (from description)
- Call relationships: grep for skill names invoked (`invoke`, `call`, `load`, `→`)
- Called-by relationships: which other skills reference this skill

Store as an in-memory skill registry.

### 2. Update `docs/SKILL-INDEX.md`

- Ensure every scanned skill has an entry with correct name, description, category, and triggers.
- Remove entries for skills that no longer exist on disk.
- Rebuild the **Call Graph** section from the extracted call relationships.
- Preserve any hand-written prose sections (e.g., intro, conventions).

### 3. Update `AGENTS.md`

- Ensure the **User Entry Points** table reflects current routing triggers.
- Ensure the **Security Enforcement** list matches all skills that call `secure-*` skills.
- Do not rewrite unrelated sections — make minimal, targeted edits.

### 4. Update `README.md`

- Ensure skill tables list every current skill with correct name and one-line description.
- Remove rows for deprecated/removed skills.
- Add rows for new skills in the correct category section.
- **Rewrite skill counts — but only in lockstep with the tables they label.** Compute `N` per category and overall from the step-1 registry (`.agents/skills/*/SKILL.md`, exclude `.deprecated/`). **Standalone prose counts** (e.g. "the library contains **90 skills**" in an intro / What's-New / suite blurb that does not head a table) — rewrite freely to the registry. **Table-labeling counts** (a heading like "Meta Skills (22)" or "(5 skills)" sitting directly above a skill table) MUST equal the rows beneath them — NEVER bump the heading number without adding/removing the matching rows in the same edit. If the table cannot be synced this run, leave the heading number unchanged and flag the gap in the Impact Report; a heading that disagrees with its own table is worse than a stale-but-consistent one. Don't invent a count line where none exists.

### 5. Generate skill graph → `docs/skill-graph.md`

Create or overwrite `docs/skill-graph.md` with a Mermaid `flowchart LR`:
- Header: `# Skill Call Graph` + `Generated by library-skill on YYYY-MM-DD`.
- Every skill is a node; every call relationship is a directed edge (`caller --> callee`).
- Group nodes by category using Mermaid `subgraph` blocks (`meta`, `thinking`, `project-specific`, `domain`).

### 5b. Sync knowledge graph

If `.agents/skills/knowledge-graph/` exists, run incremental rebuild so `call-graph.json` and `graph.json` match the new `skill-graph.md`:
```bash
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --incremental
```
Append graph outputs to Step 9 log. Skip if build script missing (consumer project without knowledge-graph).

### 6. Update `docs/architecture.md`

If `docs/architecture.md` does not exist, invoke `codebase-understanding` to create it, then continue with step 7.

Update when structural changes affect the execution flow or layer structure:
- **Key Components:** Add/remove/rename skill entries.
- **Execution Architecture:** Update flow descriptions if a skill's role in the pipeline changed.
- **Process-and-Agent Design Layer:** Update if process/agent skills changed.
- Do not rewrite sections unrelated to the structural change.

### 7. Update `docs/prd/PRD.md`

If `docs/prd/PRD.md` does not exist, invoke `prd-writing` in **non-interactive mode** — do NOT ask the user clarifying questions. Instead, infer all answers from:
- `docs/architecture.md` (from step 6) as architectural context
- Any existing point-in-time PRDs (`docs/prd/YYYY-MM-DD-*.md`) as historical context — **caution:** these may be outdated; treat as directional input, not ground truth
- The skill registry (from step 1) as the current skill inventory
- Session context, README, AGENTS.md, and any other project documentation available

Make best-guess decisions where information is missing. The user can refine the PRD later — a reasonable first draft is better than blocking the pipeline.

Then continue.

This is the living PRD — the source of truth for both agents and humans. Update:
- **Section 4 (Skill Inventory):** Add/remove/rename skills in the correct category table. Update the total count.
- **Section 5 (Architecture Overview):** Update if the execution flow or layer structure changed.
- **Section 9 (Post-Creation/Update Maintenance):** Update if the maintenance pipeline changed.
- Update the `Last updated` date in the header.
- Do not rewrite sections unrelated to the structural change — minimal, targeted edits only.
- **Never touch point-in-time PRDs** (`docs/prd/YYYY-MM-DD-*.md`) — those are historical snapshots. **Exception:** global skill renames — update the old name in all files including point-in-time PRDs to prevent stale references causing confusion.

### 8. Validate cross-references

- Check every skill name referenced in SKILL-INDEX.md, AGENTS.md, README.md, PRD.md, and architecture.md against the registry.
- Flag broken references (skill name not found on disk).
- Flag orphaned entries (index entry with no matching SKILL.md).
- Report findings — do not auto-fix SKILL.md files.

### 9. Log outputs

Append each updated file to `docs/skill-outputs/SKILL-OUTPUTS.md`:

```
| YYYY-MM-DD HH:MM | library-skill | docs/SKILL-INDEX.md | Synced after [trigger] |
| YYYY-MM-DD HH:MM | library-skill | AGENTS.md | Updated entry points |
| YYYY-MM-DD HH:MM | library-skill | README.md | Updated skill tables |
| YYYY-MM-DD HH:MM | library-skill | docs/skill-graph.md | Rebuilt call graph |
| YYYY-MM-DD HH:MM | library-skill | docs/prd/PRD.md | Updated skill inventory |
| YYYY-MM-DD HH:MM | library-skill | docs/architecture.md | Updated key components |
```

### 10. Invoke `generate-changelog`

Call `generate-changelog` with a summary of structural changes made. Final step — never skip.

## Gotchas

- **Stale frontmatter:** Some skills have `category` nested under `metadata`, others at top level. Check both.
- **Changelog skill location:** The skill named `generate-changelog` lives in `.agents/skills/generate-changelog/` — use the directory name for path, frontmatter `name` for references.
- **Partial runs:** If scanning finds zero skills, abort — the path is likely wrong. Never wipe reference files.
- **Concurrent edits:** Another agent may be editing AGENTS.md simultaneously. Read → diff → write, never overwrite wholesale.
- **Never make a heading lie about its own table.** Sync heading counts only with matching rows; otherwise flag the gap in Impact Report.

---

## Example

<examples>
  <example>
    <input>universal-skill-creator just created a new skill called `library-skill`. Run library-skill to sync the library.</input>
    <output>
Librarian sync triggered by: new skill added (library-skill)
Skills scanned: 35
New entries added: library-skill (meta)
Removed entries: none

Files updated:
  docs/SKILL-INDEX.md — added library-skill entry, updated call graph
  AGENTS.md — added library-skill to user entry points
  README.md — added library-skill row to meta skills table
  docs/skill-graph.md — rebuilt with 35 nodes, 48 edges
  docs/prd/PRD.md — added library-skill to meta skills table, count 35→36
  docs/architecture.md — no structural flow change, skipped

Cross-reference check:
  Broken references: 0
  Orphaned entries: 0

Logged to docs/skill-outputs/SKILL-OUTPUTS.md.
Invoking generate-changelog...
    </output>
  </example>
</examples>

## Common Rationalizations

| Excuse | Reality |
|--------|---------|
| "INDEX can wait" | Drifted INDEX misroutes every agent in the library. |
| "Bump count without rows" | Table heading counts must match rows beneath. |
| "Edit SKILL.md while syncing" | Librarian reads skills — never writes SKILL.md bodies. |

## Verification

- [ ] Every on-disk skill appears in SKILL-INDEX with correct category
- [ ] README table row counts match heading numbers
- [ ] `docs/skill-graph.md` regenerated with dated header
- [ ] SKILL-OUTPUTS.md + generate-changelog invoked

## Red Flags

- Scan aborted at zero skills without path verification
- Category read from wrong frontmatter nesting level
- Reference index wiped on partial or failed run
- Changelog skill path assumed wrong directory name

## Prune Log
Last pruned: 2026-07-04
- No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)


## Impact Report

`Librarian sync complete: YYYY-MM-DD Trigger: [what caused the run] Skills scanned: N Entries added: N Entries removed: N Entries updated: N Files modified: [list] Broken cross-references: N Orphaned entries: N SKILL-O...`