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

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

Create or overwrite docs/skill-graph.md with a Mermaid flowchart:

# Skill Call Graph

Generated by `library-skill` on YYYY-MM-DD.

```mermaid
flowchart LR
  universal-skill-creator --> validate-skills
  universal-skill-creator --> library-skill
  split-skill --> library-skill
  deprecate-skill --> library-skill
  improve-skills --> library-skill
  library-skill --> generate-changelog
  ...
```​

• Every skill is a node.
• Every call relationship is a directed edge (caller --> callee).
• Group nodes by category using Mermaid subgraph blocks.

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. This is the final step — never skip it.

---

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.

---

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>

---

Impact Report

After completing, always 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-OUTPUTS.md updated: yes
generate-changelog invoked: yes