tursodatabase/turso
Overview
This skill generates a hierarchical AGENTS.md knowledge base for a codebase, producing a root file plus complexity-scored subdirectory documents. It detects directories that warrant their own AGENTS.md, scores them by code and structural signals, and writes concise, non-redundant docs in parallel. Use update or create-new modes to preserve or regenerate existing content.
How this skill works
The tool discovers project structure using parallel explore agents, bash probes, and LSP codemaps where available, then merges findings with any existing AGENTS.md content. It scores directories using a weighted matrix (file counts, symbol density, exports, references, etc.) and selects locations to document. Finally it generates a root AGENTS.md and per-directory AGENTS.md files in parallel, then deduplicates and trims to meet quality gates.
When to use it
- Onboarding new contributors to quickly surface project structure and conventions
- Before major refactors to map module boundaries and hotspots
- When a repo lacks centralized, context-aware documentation
- To maintain up-to-date docs after large merges or architecture changes
- For multi-package repos where some folders deserve focused knowledge files
Best practices
- Always read existing AGENTS.md files first; preserve useful context before regenerating
- Prefer concise, project-specific notes — avoid generic advice and duplicates from parent files
- Run discovery with LSP when possible; fall back to AST-grep and bash probes if unavailable
- Tune max-depth and spawn thresholds for large repos to control doc granularity
- Generate root first, then subdir files in parallel and run a final dedupe/trim pass
Example use cases
- Generate a root AGENTS.md for a Rust-based embedded SQL engine and add AGENTS.md for high-complexity modules (storage, sql parser)
- Run in update mode to refresh docs after introducing WebAssembly bindings or new API layers
- Create-new mode to rebuild the entire knowledge base when structure was heavily reorganized
- Identify deep modules with many symbols and produce focused AGENTS.md for them without repeating root content
- Spawn additional explore agents automatically for big repos (many files/lines/depth) to uncover hidden hotspots
FAQ
By default it updates existing files and creates new ones where warranted. Use --create-new to read, then remove and regenerate all files.
How does the tool decide which directories get AGENTS.md?
It uses a weighted scoring matrix (file count, subdirs, symbol density, exports, references, unique configs) and thresholds to classify directories as root, high complexity, distinct domain, or skip.
Can it run without LSP?
Yes. LSP improves symbol and reference accuracy, but the discovery phase falls back to bash analysis and AST-grep when LSP is unavailable.
7 skills
This skill generates a hierarchical AGENTS.md knowledge base for a codebase, creating root and subdirectory documentation with complexity scoring.
This skill helps you understand and navigate SQLite-like on-disk storage structures, including pages, B-trees, and overflow handling.
This skill explains Turso's transaction correctness with WAL, checkpointing, and recovery to ensure durable, isolated, and consistent SQL data.
This skill synthesizes PR workflow guidelines for commits, PRs, CI, security, and dependencies to help teams maintain clean history and focused changes.
This skill guides you in writing and running tests across .sqltest and Rust, enabling reliable SQL compatibility and regression coverage.
This skill enforces robust Rust code quality by promoting correctness, exhaustive patterns, and clear documentation to prevent crashes and bugs.
This skill helps you debug tursodb by guiding bytecode comparison, logging, threading sanitizer, deterministic simulation, and corruption analysis.
