Agent skill

Lsp Architecture

by blackwell-systems in blackwell-systems/agent-lsp

Generate a structural architecture overview of a codebase: languages, package map, entry points, dependency graph, and hotspots.

MITAuto-check passedDevelopment

Install Lsp Architecture

skills CLI
$ npx skills add blackwell-systems/agent-lsp --skill lsp-architecture -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install blackwell-systems/agent-lsp lsp-architecture --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/blackwell-systems/agent-lsp.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/lsp-architecture .claude/skills/lsp-architecture && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
lsp-architecture
GitHub stars
160
Token cost
~2.3k tokens
SKILL.md length
595 words
Files
1
Skills in repo
24
Repo updated
First seen
Licence
MIT

At a glance

Generate a structural architecture overview of a codebase: languages, package map, entry points, dependency graph, and hotspots.

  • Works in 6 steps: Initialize → Language Detection → Package Structure → …
  • Development work in your project
  • SKILL.md covers Depth Controls (hard limits), Step 0 — Initialize, Step 1 — Language Detection and Step 2 — Package Structure, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Lsp Architecture is an agent skill from blackwell-systems/agent-lsp. Generate a structural architecture overview of a codebase: languages, package map, entry points, dependency graph, and hotspots. One call for the big picture.

Its SKILL.md is about 2.3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts. Compatibility notes: Requires the agent-lsp MCP server (github.com/blackwell-systems/agent-lsp)

It sits in Development. The repository describes itself as: MCP server that orchestrates language servers into agent-native workflows. 65 tools, 30 CI-verified languages. The licence is MIT.

When your agent uses it

  • Development work in your project

Example prompts

  • “/lsp-architecture”

Requirements

  • Compatibility (from SKILL.md): Requires the agent-lsp MCP server (github.com/blackwell-systems/agent-lsp)
  • Pre-approved tools (allowed-tools): mcp__lsp__start_lsp, mcp__lsp__list_symbols, mcp__lsp__blast_radius, mcp__lsp__detect_lsp_servers, mcp__lsp__find_symbol

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Initialize
  2. Language Detection
  3. Package Structure
  4. Entry Points
  5. Hotspot Analysis
  6. Output

What it can do on your machine

Read from SKILL.md and the folder at commit 38ca488. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • mcp__lsp__start_lsp
    • mcp__lsp__list_symbols
    • mcp__lsp__blast_radius
    • mcp__lsp__detect_lsp_servers
    • mcp__lsp__find_symbol

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    Requires the agent-lsp MCP server (github.com/blackwell-systems/agent-lsp)

    From compatibility in the SKILL.md frontmatter.

Context cost

Lsp Architecture loads about 2.3k tokens when it runs. Until then it costs about 44 tokens; SKILL.md has 595 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~44
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from blackwell-systems/agent-lsp at commit 38ca488, republished under its MIT licence (© blackwell-systems). 595 words, ~2,273 tokens.

Download SKILL.mdSave it as .claude/skills/lsp-architecture/SKILL.md (or your agent's skills folder).
name
lsp-architecture
description
Generate a structural architecture overview of a codebase: languages, package map, entry points, dependency graph, and hotspots. One call for the big picture.
allowed-tools
mcp__lsp__start_lsp, mcp__lsp__list_symbols, mcp__lsp__blast_radius, mcp__lsp__detect_lsp_servers, mcp__lsp__find_symbol
compatibility
Requires the agent-lsp MCP server (github.com/blackwell-systems/agent-lsp)
argument-hint
[workspace-root-path]
user-invocable
true
license
MIT
metadata.required-capabilities
documentSymbolProvider
metadata.optional-capabilities
workspaceSymbolProvider referencesProvider

Requires the agent-lsp MCP server.

lsp-architecture

Generate a structural architecture overview of any codebase: language distribution, package hierarchy, entry points, dependency flow, and hotspot files. One invocation for the big picture.

Read-only; does not modify any files.

Invocation: User provides the workspace root path (e.g. "/home/user/myproject"). If omitted, use the current working directory.


Depth Controls (hard limits)

These limits are strict constraints. Never exceed them:

  • Package enumeration: cap at 30 packages
  • Hotspot analysis: cap at 10 files
  • Workspace symbol queries: cap at 5 queries
  • Do NOT recurse into vendor/, node_modules/, .git/, or other dependency directories

Step 0 — Initialize

If LSP is not yet running, start it with the workspace root:

mcp__lsp__start_lsp({
  "workspace_root": "<workspace-root>"
})

Then detect which language servers are available:

mcp__lsp__detect_lsp_servers({
  "workspace_root": "<workspace-root>"
})
→ returns: list of detected servers with language names and file patterns

Record the available languages and their file globs. This determines which queries to run in later steps.


Step 1 — Language Detection

Scan the workspace to determine language distribution. Use file extension counts from the detected servers and supplement with a filesystem scan (via Glob tool) to count files per language.

For each detected language, report:

  • Language name
  • File count
  • Estimated lines of code (sample 3-5 representative files and extrapolate)

Skip files in vendor/, node_modules/, .git/, dist/, build/, and other common dependency or output directories.


Step 2 — Package Structure

Use find_symbol with broad queries to discover the package and module hierarchy. Tailor queries by language:

Go:

mcp__lsp__find_symbol({
  "query": "",
  "symbol_kind_filter": "Package"
})

Also query for top-level types and functions to fill in package-level detail:

mcp__lsp__find_symbol({
  "query": "",
  "symbol_kind_filter": "Function"
})

Python:

mcp__lsp__find_symbol({
  "query": "",
  "symbol_kind_filter": "Class"
})

TypeScript/JavaScript:

mcp__lsp__find_symbol({
  "query": "",
  "symbol_kind_filter": "Function"
})

From the returned symbols, extract the directory paths and build a tree of the package hierarchy. Group symbols by their containing directory. For each package/directory, note:

  • Path relative to workspace root
  • Brief description (inferred from symbol names and directory name)
  • Approximate symbol count

Cap at 30 packages. If more than 30 directories contain symbols, keep only the top 30 by symbol count and note that others were omitted.

Cap workspace symbol queries at 5 total across all of Step 2.


Step 3 — Entry Points

Use find_symbol to search for common entry point patterns:

mcp__lsp__find_symbol({
  "query": "main"
})

Also search for other common entry point names (use a single additional query if needed): "Run", "Serve", "Handler", "App", "Main".

Identify and categorize:

  • CLI entrypoints: main functions, Run or Execute commands
  • HTTP handlers: Handler, Serve, ListenAndServe patterns
  • Test suites: top-level test files (note count only, do not list individually)

List each entry point with file:line.


Show full SKILL.md (211 more words)Show less

Step 4 — Hotspot Analysis

Identify the files with the highest symbol density (most exports), then measure their blast radius.

4a — Find candidate files

From the symbols discovered in Step 2, count exported symbols per file. Select the top 10 files by exported symbol count.

4b — Measure blast radius

For each candidate file, call blast_radius:

mcp__lsp__blast_radius({
  "changed_files": ["<absolute-path-to-file>"],
  "include_transitive": false
})
→ returns: affected_symbols, test_callers, non_test_callers

This tool uses a persistent cache, so repeated calls on the same file are instant.

4c — Rank hotspots

Rank files by total non_test_callers count (descending). Files with the most non-test callers are the architectural hotspots: changing them has the widest blast radius.


Step 5 — Output

Produce the architecture report in this format:

## Architecture Overview: <project-name>

### Languages
- Go: 150 files (~15K lines)
- TypeScript: 30 files (~3K lines)

### Package Map
cmd/agent-lsp/     (entrypoint, CLI routing)
internal/lsp/      (LSP client, process management)
internal/tools/    (MCP tool handlers)
internal/session/  (speculative execution sessions)
...

### Entry Points
- cmd/agent-lsp/main.go:55 (main)
- cmd/agent-lsp/server.go:276 (Run)

### Hotspots (most referenced files)
1. internal/lsp/client.go: 150+ callers across 30 files
2. internal/tools/helpers.go: 80 callers across 20 files
...

### Dependency Flow
cmd/ -> internal/tools/ -> internal/lsp/ -> (gopls subprocess)
         |-> internal/session/ -> internal/lsp/
Report sections

Languages: One line per language with file count and estimated LOC.

Package Map: Directory tree with a parenthetical description of each package's role. Cap at 30 entries.

Entry Points: Each with file:line and a parenthetical label (e.g. (main), (HTTP handler), (CLI command)).

Hotspots: Ranked list of the most-referenced files. For each, show the total non-test caller count and the number of distinct files containing callers.

Dependency Flow: A simple ASCII arrow diagram showing how the top-level packages depend on each other. Infer this from the hotspot caller data and package structure. Keep it concise: show the primary flow paths, not every edge.


Example

Goal: architecture overview of /home/user/agent-lsp

Step 0 — Initialize
  start_lsp: workspace_root="/home/user/agent-lsp"
  detect_lsp_servers:
  → Go (gopls): *.go
  → detected 1 language server

Step 1 — Language Detection
  Glob: **/*.go (excluding vendor/) → 85 files
  Sample 5 files, average 180 lines → estimate ~15K total lines
  → Go: 85 files (~15K lines)

Step 2 — Package Structure
  find_symbol: query="", symbol_kind_filter="Package"
  → 12 packages found

  find_symbol: query="", symbol_kind_filter="Function"
  → 240 functions across 12 packages

  Package map:
    cmd/agent-lsp/       (entrypoint, CLI routing, 15 symbols)
    internal/lsp/        (LSP client lifecycle, 45 symbols)
    internal/tools/      (MCP tool handlers, 60 symbols)
    internal/session/    (speculative execution, 25 symbols)
    internal/protocol/   (LSP protocol types, 30 symbols)
    skills/              (embedded skill definitions, 5 symbols)

Step 3 — Entry Points
  find_symbol: query="main"
  → cmd/agent-lsp/main.go:55 main()

  find_symbol: query="Run"
  → cmd/agent-lsp/server.go:276 Run()
  → cmd/agent-lsp/daemon.go:40 RunDaemon()

  Entry points:
  - cmd/agent-lsp/main.go:55 (main)
  - cmd/agent-lsp/server.go:276 (Run, server lifecycle)
  - cmd/agent-lsp/daemon.go:40 (RunDaemon, background mode)

Step 4 — Hotspot Analysis
  Top files by symbol count:
    1. internal/lsp/client.go (22 exported symbols)
    2. internal/tools/helpers.go (18 exported symbols)
    3. internal/protocol/types.go (15 exported symbols)

  blast_radius on each:
    internal/lsp/client.go → 150 non-test callers across 30 files
    internal/tools/helpers.go → 80 non-test callers across 20 files
    internal/protocol/types.go → 60 non-test callers across 15 files

Step 5 — Output

## Architecture Overview: agent-lsp

### Languages
- Go: 85 files (~15K lines)

### Package Map
cmd/agent-lsp/       (entrypoint, CLI routing)
internal/lsp/        (LSP client, process management)
internal/tools/      (MCP tool handlers)
internal/session/    (speculative execution sessions)
internal/protocol/   (LSP protocol types)
skills/              (embedded skill definitions)

### Entry Points
- cmd/agent-lsp/main.go:55 (main)
- cmd/agent-lsp/server.go:276 (Run)
- cmd/agent-lsp/daemon.go:40 (RunDaemon)

### Hotspots (most referenced files)
1. internal/lsp/client.go: 150 callers across 30 files
2. internal/tools/helpers.go: 80 callers across 20 files
3. internal/protocol/types.go: 60 callers across 15 files

### Dependency Flow
cmd/agent-lsp/ -> internal/tools/ -> internal/lsp/ -> (gopls subprocess)
                    |-> internal/session/ -> internal/lsp/
                    |-> internal/protocol/

© blackwell-systems, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/lsp-architecture of blackwell-systems/agent-lsp.

Open the folder on GitHubat commit 38ca488

Compare with similar skills

Lsp Architecture next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Lsp Architecture compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Lsp Architecture this skillblackwell-systems/agent-lsp160—~2.3kAutomated safety check: PassMIT
Vercel Composition Patternssupabase/supabase111k58 repos~726Automated safety check: PassMIT
Finishing a Development Branchobra/superpowers297k5 repos~1.9kAutomated safety check: PassMIT
Typescript Advanced Typesrolling-scopes/rsschool-app10k25 repos~4.2kAutomated safety check: PassMPL-2.0
PR Babysitteropeninterpreter/openinterpreter69k3 repos~4.2kAutomated safety check: PassApache-2.0
Code Review ChecklistshareAI-lab/learn-claude-code78k4 repos~1.1kAutomated safety check: PassMIT

Similar skills

  • Official

    React composition patterns that scale. An agent skill from supabase/supabase.

    111k GitHub starsUsed in 58 repos~726 tokens
    DevelopmentAuto-check passed
  • Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.

    297k GitHub starsUsed in 5 repos~1.9k tokens
    DevelopmentAuto-check passed
  • Typescript Advanced Types

    rolling-scopes/rsschool-app

    Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications.

    10k GitHub starsUsed in 25 repos~4.2k tokens
    DevelopmentAuto-check passed
  • PR Babysitter

    openinterpreter/openinterpreter

    Watches an open GitHub pull request until it merges, handling review comments, diagnosing CI failures and retrying flaky checks along the way.

    69k GitHub starsUsed in 3 repos~4.2k tokens
    DevelopmentAuto-check passed
  • Code Review Checklist

    shareAI-lab/learn-claude-code

    Reviews code against a five-part checklist covering security, correctness, performance, maintainability and testing, and reports findings in a fixed format.

    78k GitHub starsUsed in 4 repos~1.1k tokens
    DevelopmentAuto-check passed
  • Greploop

    onyx-dot-app/onyx

    Iteratively improves a PR (GitHub), MR (GitLab), or shelved changelist (Perforce) until Greptile gives it a 5/5 confidence score with zero unresolved comments.

    32k GitHub starsUsed in 4 repos~3.3k tokens
    DevelopmentAuto-check passed

More from blackwell-systems/agent-lsp

All 24 skills in this repo
  • Lsp Dead Code

    blackwell-systems/agent-lsp

    Enumerate exported symbols in a file and surface those with zero references across the workspace.

    160 GitHub stars~2.4k tokensUpdated yesterday
    Auto-check passed
  • Lsp Edit Export

    blackwell-systems/agent-lsp

    Safe workflow for editing exported symbols or public APIs. An agent skill from blackwell-systems/agent-lsp.

    160 GitHub stars~1.9k tokensUpdated yesterday
    Auto-check passed
  • Lsp Fix All

    blackwell-systems/agent-lsp

    Apply available quick-fix code actions for all current diagnostics in a file, one at a time with re-collection between each fix.

    160 GitHub stars~1.6k tokensUpdated yesterday
    Auto-check passed
  • Lsp Generate

    blackwell-systems/agent-lsp

    Trigger language server code generation — implement interface stubs, generate test skeletons, add missing methods, generate mock types.

    160 GitHub stars~1.4k tokensUpdated yesterday
    Auto-check passed
  • Lsp Impact

    blackwell-systems/agent-lsp

    Blast-radius analysis for a symbol or file — shows all callers, type supertypes/subtypes, and reference count before you change it.

    160 GitHub stars~1.8k tokensUpdated yesterday
    Auto-check passed
  • Lsp Rename

    blackwell-systems/agent-lsp

    Two-phase safe rename across the entire workspace. An agent skill from blackwell-systems/agent-lsp.

    160 GitHub stars~1.9k tokensUpdated yesterday
    Auto-check passed

Categories

Questions about Lsp Architecture

What does Lsp Architecture do?

Generate a structural architecture overview of a codebase: languages, package map, entry points, dependency graph, and hotspots. Lsp Architecture is an agent skill from blackwell-systems/agent-lsp. Generate a structural architecture overview of a codebase: languages, package map, entry points, dependency graph, and hotspots.

When should I use Lsp Architecture?

Lsp Architecture fits situations like: development work in your project.

How do I install Lsp Architecture in Claude Code?

Run `npx skills add blackwell-systems/agent-lsp --skill lsp-architecture -a claude-code`. Or copy the skill folder (skills/lsp-architecture in blackwell-systems/agent-lsp) into .claude/skills/lsp-architecture in your project. Claude Code loads it when a task matches its description.

How do I install Lsp Architecture in Codex?

Run `npx skills add blackwell-systems/agent-lsp --skill lsp-architecture -a codex`. Or copy the skill folder (skills/lsp-architecture in blackwell-systems/agent-lsp) into .agents/skills/lsp-architecture in your project. Codex loads it when a task matches its description.

Can I use Lsp Architecture in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add blackwell-systems/agent-lsp --skill lsp-architecture -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/lsp-architecture, .gemini/skills/lsp-architecture, .github/skills/lsp-architecture and .opencode/skills/lsp-architecture in your project.

What does Lsp Architecture need to run?

SKILL.md names no scripts, command-line tools or credentials: Lsp Architecture is instructions for the agent only. Its frontmatter pre-approves these tools: mcp__lsp__start_lsp, mcp__lsp__list_symbols, mcp__lsp__blast_radius, mcp__lsp__detect_lsp_servers, mcp__lsp__find_symbol. Compatibility (from SKILL.md): Requires the agent-lsp MCP server (github.com/blackwell-systems/agent-lsp).

Does Lsp Architecture access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Lsp Architecture safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Lsp Architecture use?

Lsp Architecture is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Lsp Architecture use?

About 2.3k tokens (SKILL.md is roughly 9.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Lsp Architecture?

Skills that share tags, products or a category with Lsp Architecture: Vercel Composition Patterns (supabase/supabase, 111k stars), Finishing a Development Branch (obra/superpowers, 297k stars), Typescript Advanced Types (rolling-scopes/rsschool-app, 10k stars) and PR Babysitter (openinterpreter/openinterpreter, 69k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Lsp Architecture?

blackwell-systems (a GitHub user) maintains it in blackwell-systems/agent-lsp, which has 160 GitHub stars. The repository holds 24 skills in this directory. The repository was last updated on October 10, 2026.

Source: blackwell-systems/agent-lsp on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.