Library Skill

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

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

Common Rationalizations

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