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