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:

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...