index-knowledge_skill

Overview

This skill generates a hierarchical AGENTS.md knowledge base for a codebase, producing a root AGENTS.md and complexity-scored subdirectory files. It balances discovery, scoring, parallel generation, and review to produce concise, non-redundant documentation for onboarding and maintenance.

How this skill works

The tool inspects the repository with fast bash scans, optional LSP codemap queries, and parallel explore agents that detect entry points, conventions, tests, CI, and anti-patterns. It scores directories with a weighted matrix (file counts, symbols, exports, centrality) to decide AGENTS.md locations, generates the root file first, then produces subdirectory AGENTS.md files in parallel, and finally deduplicates and trims outputs. It tracks phase state (discovery → scoring → generate → review) in real time.

When to use it

• Onboarding to a new or unfamiliar codebase
• Running /init to bootstrap project documentation
• Regenerating stale or missing AGENTS.md files
• Preparing a codebase overview before architectural changes
• When creating consistent, machine-friendly docs for monorepos

Best practices

• Always create a root AGENTS.md; create subdocs only where score > threshold
• Run discovery first and read existing AGENTS.md to preserve context
• Prefer parallel Task calls for explore and generation to speed analysis
• Keep files telegraphic: remove generic advice and never repeat parent content
• Limit subdirectory docs to concise 30–80 lines; root can be 50–150 lines

Example use cases

• Bootstrap documentation after cloning a large monorepo to surface domains and entry points
• Regenerate AGENTS.md after refactors so docs reflect new module boundaries
• Create compact onboarding guides for new engineers focused on conventions and anti-patterns
• Automate knowledge-base updates in CI when significant symbol centrality or file counts change
• Produce a quick code map for maintainers using LSP symbol density and reference centrality