Publish Sign in

Codebase Scanner

Scans the codebase to generate project-doc.md and AGENTS.md.

You say
Install this skill Read the source first Free Written by wshobson · unverified publisher
Context cost
2.2k tokensestimated from the bundle, loaded when it triggers
Bundle
1 file · 8.9 kBtext throughout, nothing executable
Licence
MITfree to use
Last change
—no release on file
Servers it uses
Noneruns standalone

What it does

Scans the codebase to generate project-doc.md and AGENTS.md. Use when bootstrapping a new agent-driven repo, refreshing project documentation after architectural changes, or running a delta scan to detect drift. Runs a full scan on first use and a smart delta scan on subsequent runs. Uses understand-anything + context-mode when available, falls back to native tools otherwise. Only updates AGENTS.md on detected architectural changes with human confirmation.

Installed, it changes the agent in these ways.

What this skill changes about the agent is not written down here yet. The listing was collected from its source, and the description is in its own SKILL.md.

Workflow

Runs a procedure end to end.

documentation
Filed under

Learning & Documentation

The skill itself

This is the whole product. A skill is instructions the model reads, so there is nothing behind the listing you cannot see first — the front matter loads with every session, and the body below it loads when the skill triggers.

SKILL.md8.9 kB · 219 lines
--- name: scan description: Scans the codebase to generate project-doc.md and AGENTS.md. Use when bootstrapping a new agent-driven repo, refreshing project documentation after architectural changes, or running a delta scan to detect drift. Runs a full scan on first use and a smart delta scan on subsequent runs. Uses understand-anything + context-mode when available, falls back to native tools otherwise. Only updates AGENTS.md on detected architectural changes with human confirmation. ---
6# Codebase Scanner
7
8You are a technical analyst. Your job is to scan the project codebase and produce accurate, project-specific documentation used by all downstream agents.
9
10## Step 1: Check Optional Plugin Dependencies
11
12Check whether the two optional enhancement plugins are available:
13
14```
15understand-anything → /plugin list | grep understand-anything
16context-mode → /plugin list | grep context-mode
17```
18
19These plugins are **optional**. They improve scan quality but are not required:
20
21- **understand-anything** (Lum1104/Understand-Anything) — provides deeper semantic code analysis
22- **context-mode** (mksglu/context-mode) — routes large outputs through a sandbox to protect the context window
23
24If both are present, use them in Steps 3–4 as described below. If either or both are missing, proceed with the **native fallback** approach: use find, grep, cat, and git commands directly, routing large outputs through ctx_execute / ctx_execute_file if context-mode is available, otherwise summarise inline.
25
26> **Note:** To install the optional plugins manually:
27> ```
28> /plugin marketplace add Lum1104/Understand-Anything && /plugin install understand-anything
29> /plugin marketplace add mksglu/context-mode && /plugin install context-mode@context-mode
30> ```
31
32## Step 2: Determine Scan Mode
33
34Check if .claude/pipeline/project-doc.md exists.
35
36- **Does not exist** → FULL SCAN (first run)
37- **Exists** → DELTA SCAN
38
39## Step 3A: Full Scan
40
41Use understand-anything to analyse the entire codebase. If **context-mode** is available (verified in Step 1), route ALL output through its tools (ctx_batch_execute / ctx_execute_file) — never dump raw file contents into the main context window. If context-mode is not available, summarise each file's findings inline and avoid printing raw file contents.
42
43Produce .claude/pipeline/project-doc.md using the following structure (based on the architecture-blueprint-generator pattern):
44
45```md
46# Project Documentation
47> Generated: [timestamp] | Mode: FULL
48
49## Tech Stack
50- Runtime: [e.g. Node.js 20, Python 3.11]
51- Language: [e.g. TypeScript, Python]
52- Framework: [e.g. Next.js 14 App Router, FastAPI]
53- Database: [e.g. PostgreSQL via Prisma]
54- Styling: [e.g. Tailwind CSS]
55- State Management: [e.g. Zustand, Redux]
56
57## Dependencies
58[Key libraries with versions, grouped by: core / dev / testing]
59
60## Architecture Pattern
61[e.g. Feature-based, Layered MVC, Clean Architecture]
62[Describe how the project is structured and why]
63
64## Folder Structure
65[Top-level directory map with purpose of each folder]
66
67## Code Style Conventions
68[Naming patterns, file naming, import ordering, export patterns]
69[Inferred from actual code — not guessed]
70
71## Modularity Practices
72[How concerns are separated, shared module locations, service patterns]
73
74## Data Architecture
75[Entity relationships, data access patterns, ORM usage]
76
77## Cross-Cutting Concerns
78[Auth/authz approach, error handling patterns, logging, validation]
79
80## Service Communication
81[REST / GraphQL / event-driven — document what actually exists]
82
83## Test Coverage
84- Overall coverage: [X%]
85- Testing framework: [e.g. Jest, Vitest, Pytest]
86- Key untested areas: [list]
87- Test patterns used: [unit / integration / e2e]
88
89## Entry Points
90[Main files, key config files, environment setup]
91
92## Changed Files
93[Only present in delta scans — list of files re-scanned]
94
95## Last Scanned
96[ISO timestamp]
97```
98
99After writing project-doc.md, proceed to **Step 4** to generate AGENTS.md.
100
101## Step 3B: Delta Scan
102
1031. Run git diff HEAD~1 --name-only to get changed files
1042. If no changed files, report "No changes detected — project-doc.md is current" and exit
1053. Use understand-anything to re-analyse only the changed files; route output through ctx_execute_file if context-mode is available, otherwise summarise inline
1064. Patch only the affected sections of .claude/pipeline/project-doc.md
1075. Update the Last Scanned and Changed Files fields
1086. Proceed to **Step 4B** (architectural change detection)
109
110## Step 4A: Generate AGENTS.md (First Run Only)
111
112Write AGENTS.md to the repo root. This is NOT a copy of project-doc.md — it is rewritten as agent instructions, tailored to this specific project. Every agent reads this file first.
113
114Structure:
115
116```md
117# AGENTS.md — [Project Name]
118> Auto-generated by the dev pipeline scanner. Do not edit manually.
119> Last updated: [timestamp]
120> ⚠️ To update this file, architectural changes must be detected by the scanner and confirmed by a human.
121
122## How to Read This File
123Every agent in this pipeline reads this file before doing any work.
124It defines the rules, patterns, and guardrails specific to this project.
125
126## Stack Context
127[One-line summary: e.g. "Next.js 14 App Router + Prisma + PostgreSQL + Tailwind + Vitest"]
128
129## Code Style Rules
130[Written as DO/DON'T instructions inferred from actual codebase patterns]
131Example:
132- DO use named exports. Default exports are not used in this project.
133- DON'T add business logic to API route handlers — delegate to /lib/services/
134- DO use [naming convention] for [file type]
135
136## Architecture Guardrails
137[Rules derived from the actual architecture — not generic advice]
138Example:
139- This project uses the Repository pattern. Never query the DB directly from components.
140- All API responses must go through the [ResponseWrapper] utility.
141
142## Testing Requirements
143[Coverage stat + specific rules for this project]
144Example:
145- Current coverage: 67%. All new code must include unit tests.
146- QA agent: flag any feature with <80% coverage on new code.
147- Integration tests use [real DB / mock DB] — do not change this.
148
149## Modularity Conventions
150[Specific rules about where code goes]
151Example:
152- Shared UI components → /components/ui
153- Business logic → /lib/services/[domain]/
154- Types → /types/[domain].ts
155
156## Security Rules (All Agents)
157- Never hardcode secrets, tokens, or credentials
158- Use environment variables for all sensitive config
159- Flag any auth-adjacent code changes immediately
160
161## Agent-Specific Instructions
162
163### Orchestrator
164[Project-specific questions to always ask — e.g. "Does this touch the payment flow?"]
165
166### Architect
167[Known complexity areas, performance constraints, patterns to prefer]
168[e.g. "This project has a known N+1 issue in /lib/services/orders — avoid adding more eager loading"]
169
170### Developer
171[Specific libraries to use, anti-patterns banned in this codebase]
172[e.g. "Use dayjs — moment is banned", "Use React Query for all data fetching — no raw fetch()"]
173
174### PR Reviewer
175[What counts as 🔴 Critical vs 🟡 Should Fix in this project]
176[e.g. "Any change to /lib/auth/ is automatically 🔴 Critical — requires human approval"]
177
178### QA Agent
179[Known edge cases for this domain, critical user paths to always test]
180[e.g. "Always test empty state, loading state, and error state for every UI feature"]
181```
182
183If the project is MERN stack (MongoDB + Express + React + Node.js — detected from package.json / requirements), append a ### MERN Stack Notes section to AGENTS.md covering: use Mongoose middleware over raw queries, handle async errors in Express with a central error handler, avoid storing JWT tokens in localStorage (use httpOnly cookies), and never expose Mongoose error objects directly in API responses.
184
185## Step 4B: Architectural Change Detection (Delta Runs Only)
186
187After patching project-doc.md, compare the new version against the previous. Check for:
188- New framework or major library added
189- New architectural directory pattern created (e.g. new /lib/hooks/, /services/)
190- Major dependency swap (e.g. axios → fetch, moment → dayjs)
191- New auth or session handling pattern
192
193If any detected, show:
194
195```
196⚠️ Architectural change detected in delta scan:
197 [List specific changes found]
198
199AGENTS.md may need updating. Review and confirm:
200 [y] Update AGENTS.md — patch affected sections only
201 [n] Skip — this is not an architectural change
202```
203
204Only on [y] confirmation: patch the relevant sections of AGENTS.md. Never rewrite the full file.
205
206## Step 5: Report
207
208Print a summary:
209
210```
211✅ Scan complete ([FULL/DELTA])
212 project-doc.md → updated
213 AGENTS.md → [generated / patched / unchanged]
214 Changed files → [N files re-scanned / N/A for full scan]
215 Coverage → [X%]
216```
217
218Update state.json field checkpoints.scan = "completed".
219
In the file
SKILL.md1,293 words
Files1
LicenceMIT
Why you can read it

Nothing in a skill executes. The client loads the text and the model follows it, so a skill can be audited the way a runbook is — by reading it.

What it costs in context

Skills are not billed by the call. They are paid for in context: every token the instructions occupy is a token your code, your diff and your conversation cannot use. Here is what this one takes and when it takes it.

≈120
always loaded
The name and description, so the model knows the skill exists and when to reach for it.
2,105
on trigger
The instruction body, read only when the skill fires.
1.1%
of a 200k window
Ten skills this size would take about 11% of the window before you open a file.
050k100k150k200k context window

2.2k tokens, estimated from the bundle at four bytes to the token, held for the rest of the session once it triggers. Middling. Fine to keep on in a project where you use it weekly, worth unloading in one where you never do.

Servers bill, skills cost

A server charges by the month. A skill charges once per session, in context, and then keeps charging it for as long as the session lives.

Before and after

The same question, put to the same model twice: once as it comes, and once with these instructions loaded.

No worked example has been published for this skill yet.

Adoption
Installsnone yet
Ratingno reviews yet

The procedure it runs

The procedure has not been published here. It is in the skill’s own SKILL.md, which its author has not sent to the marketplace yet.

Prose, not code

These steps are written for a model to follow, not executed by a runtime. It can still be told to skip one, and it will say so when it does.

Servers it uses

None. This skill calls no MCP servers at all.

Everything it needs is in the instructions, so it works in a project with nothing connected — the model reads the file and changes how it works with what it can already reach.

It writes no files and reaches no network. All it changes is how the model reasons and writes.

What it asks for
Writes filesno
Network accessno

Read from the allowed-tools line of this skill’s own SKILL.md. A skill grants no permissions of its own — it can only ask for tools your client already has.

What it will not do

Every skill is narrow, and the useful ones say where they stop. These are the jobs this one is the wrong tool for.

What this skill is not for has not been published here. Nothing is implied by that: it is a section the author has not filled in.

What is in the bundle

1 file, 8.9 kB on disk. A bundle is text throughout: the instructions the model reads, plus the templates it fills in.

  • SKILL.md8.9 kB
What is not in it

No dependencies and nothing executable: a skill is text the agent reads, so the bundle is 1 file you can review in full before installing. The MIT licence covers the templates and examples as well as the instructions.

Install

Installing copies the bundle into your project. Nothing runs at install time — the files sit on disk until the model reads them.

# Codebase Scanner · 2.2k tokens when loaded npx mcprush@latest skill add wshobson/codebase-scanner

Writes to .claude/skills/codebase-scanner/ in the current project. Add --global to put it in your home directory instead, for every project.

Which clients pick it up on their own

A skill is a folder of text. A client with a skills folder reads it without being told; everywhere else the same text works, it is just handed to the model rather than found.

Claude Code.claude/skills/
Claude Desktop
ChatGPT
Cursor.cursor/skills/
VS Code.github/skills/
Codex CLI.agents/skills/
Gemini CLI.gemini/skills/
Grok.grok/skills/
Zed.agents/skills/
Windsurf.windsurf/skills/
Agent SDK.claude/skills/
HTTP / API
This release
Versionnot versioned
Publishedno release date on file
PriceFree
Referencewshobson/codebase-scanner

Versions

Its author publishes no version number, so there is nothing here to pin to: what you install is the folder as it stands today. Instructions change more often than APIs do — a skill can be rewritten entirely without anything it depends on moving.

v
  • No earlier releases have been published to the marketplace.
Pinning

Nothing to pin to: this skill carries no version number of its own. What you install is what the folder holds on the day you install it.

Reviews

—no reviews yet · no installs yet

Nobody has reviewed this skill yet. The rating is the mean of the reviews written here, so there is none until somebody writes the first.

Who can post

Only accounts that have had the skill installed for fourteen days, so a review is written after living with it rather than after reading it. Publishers may reply once.

Who wrote it

WS
wshobson

Publishes on mcprush.

0 servers listed11 skills listednot claimed
Profile
Publisher
Servers0