| name | extract-api-surface |
| description | Extracts the public API of a codebase — class names, function signatures, exported types, module docstrings — without loading every file. Use this skill whenever the user asks to understand, explore, navigate, or describe a codebase, library, repository, or package at the overview level. Trigger phrases include "help me understand this codebase", "what does this library do", "what's the API of X", "how is this project structured", "give me an overview of Y", "explain this repo". Calls gotcontext's AST-aware skeleton extraction so you read the shape of the code, not the implementation bodies. |
| version | 1.1.0 |
extract-api-surface
When this skill is the preferred path
The user wants to get oriented in a codebase quickly — they need to
know what's there, not how each function is implemented. Reading every
file just to answer "what does this library do" wastes context and
misses the forest for the trees.
How to use it
- Identify the target: a local directory (
./src), a repo root, or a
GitHub URL the user linked to.
- Call
read_skeleton (free-tier MCP tool) on the target path. You'll
get function/class signatures, type definitions, module-level
docstrings, and import maps — bodies stripped. Compression is
adaptive: smaller files keep most of their structure; larger files
compress harder. Sections not anchored come back as short summaries
you can expand on demand with modulate_region. For cross-file
understanding across a larger tree, compress_codebase (Pro+)
returns the same AST-aware digest for every file in the corpus at
once.
- If the skeleton is still too large (rare, large monorepos), pipe it
through
ingest_context at fidelity=balanced.
- Present a structured overview:
- Top-level exports grouped by module
- Key types / interfaces
- Entry points (CLI, main, server)
- One-sentence purpose per module
- Total signature count (so the user knows the coverage)
When the raw read is actually fine
- You're actively editing a specific file — you need the body.
- You're debugging a specific function — skeleton hides it.
- Configs, data fixtures, generated code — skeleton isn't meaningful;
either skip or run
ingest_context on them.
Language support
AST-native: Python, JavaScript, TypeScript. Line-based fallback: Java,
Go, Rust, C++. Other languages fall back to regex slicing — surface
that caveat to the user if you hit a non-native language.
See references/overview-template.md for the reporting format.
