|
|
@@ -0,0 +1,75 @@
|
|
|
+---
|
|
|
+name: codebase-summarizer
|
|
|
+description: Use codebase_summarizer to generate and maintain a codebase map. Trigger this skill when exploring a new or unfamiliar codebase, when working across multiple files in a large project, or after making changes to function signatures, docstrings, class definitions, or other exported symbols. The agent should consult codebase_summary.md as a map before reading individual files, and re-run `codebase_summarizer` in the project root after any structural changes.
|
|
|
+---
|
|
|
+
|
|
|
+## Tool: codebase_summarizer
|
|
|
+
|
|
|
+A CLI tool that extracts a concise summary of a codebase — public symbols, their types, signatures, and documentation — into `codebase_summary.md`.
|
|
|
+
|
|
|
+**Available at:** `codebase_summarizer` (installed globally) or `cargo run --release` from the project directory.
|
|
|
+
|
|
|
+## When to Use
|
|
|
+
|
|
|
+### At the start of a multi-file task
|
|
|
+Before reading multiple files to understand a codebase, check if `codebase_summary.md` already exists. If it doesn't, or if the project has changed significantly, run:
|
|
|
+
|
|
|
+```bash
|
|
|
+codebase_summarizer --directory <project-root>
|
|
|
+```
|
|
|
+
|
|
|
+Use the summary to identify which files contain the logic you need, then deep-dive into those specific files.
|
|
|
+
|
|
|
+### After making structural changes
|
|
|
+Re-run the tool when you've changed any of the following:
|
|
|
+- Function or method signatures
|
|
|
+- Docstrings / documentation comments
|
|
|
+- Class, struct, enum, or interface definitions
|
|
|
+- Type aliases or trait definitions
|
|
|
+- Exported symbols in general
|
|
|
+
|
|
|
+From the project root:
|
|
|
+```bash
|
|
|
+codebase_summarizer
|
|
|
+```
|
|
|
+
|
|
|
+If `codebase_summary.md` already exists, the tool updates it in place. It also creates or updates `AGENTS.md` with navigation instructions.
|
|
|
+
|
|
|
+## Reading the Summary
|
|
|
+
|
|
|
+`codebase_summary.md` is organized by file. Each section lists the symbols in that file with their kind, name, signature, and documentation. Use it to:
|
|
|
+
|
|
|
+1. **Find the right file** — identify which file contains the function or type you need
|
|
|
+2. **Understand intent** — read the doc comments without reading the full implementation
|
|
|
+3. **Know the API surface** — see what a module exports before diving into it
|
|
|
+
|
|
|
+## How It Works
|
|
|
+
|
|
|
+1. Scans the directory, filtering out `target/`, `node_modules/`, `.git/`, and other build/generated directories
|
|
|
+2. Extracts symbols from code files using language-aware parsers
|
|
|
+3. Outputs `codebase_summary.md` with the file tree and symbol documentation
|
|
|
+4. Creates `AGENTS.md` with navigation protocol (if it doesn't exist)
|
|
|
+
|
|
|
+## Supported Languages
|
|
|
+
|
|
|
+Go, Rust, Python, Dart, R, TypeScript/JavaScript, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, and more.
|
|
|
+
|
|
|
+## Output Format
|
|
|
+
|
|
|
+The tool generates a markdown file with this structure:
|
|
|
+
|
|
|
+```markdown
|
|
|
+# Codebase Architecture Map
|
|
|
+
|
|
|
+## File: src/main.rs
|
|
|
+
|
|
|
+### func main
|
|
|
+**Doc:**
|
|
|
+Entry point for the application.
|
|
|
+
|
|
|
+### struct Config
|
|
|
+**Doc:**
|
|
|
+Configuration for the application.
|
|
|
+```
|
|
|
+
|
|
|
+Each symbol shows its kind (func, struct, method, etc.), name, and any associated doc comments.
|
