# Project Scan

> Auto-populate context/project.md by reading the current codebase

- Skill: `andrem-sec/project-scan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add andrem-sec/project-scan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andrem-sec/project-scan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: andrem-sec (https://skillmd.com/u/andrem-sec)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/andrem-sec/project-scan

---


# Project Scan Skill

Reads the current codebase and auto-populates `context/project.md`. Run once on setup, re-run when the project's structure changes significantly.

## What Claude Gets Wrong Without This Skill

Without a scan, `context/project.md` stays as a template. Every skill that reads it gets nothing useful. The context layer is only as good as the data in it.

## Detection Protocol

### Stack Detection

Check for manifest files in order:

| File | Indicates |
|------|-----------|
| `package.json` | Node.js — check `dependencies` for framework (next, express, fastapi via py) |
| `pyproject.toml` / `setup.py` / `requirements.txt` | Python — check for FastAPI, Django, Flask, etc. |
| `go.mod` | Go — check module name and key imports |
| `Cargo.toml` | Rust |
| `pom.xml` / `build.gradle` | Java/Kotlin |
| `Gemfile` | Ruby |
| `composer.json` | PHP |
| `*.csproj` | .NET/C# |

Read the manifest. Extract: language, framework, key dependencies (non-obvious ones only — not lodash, not requests).

### Entry Points

| Stack | Look For |
|-------|---------|
| Node.js | `"main"` in package.json, `src/index.ts`, `app.ts`, `server.ts` |
| Python | `main.py`, `app.py`, `__main__.py`, `manage.py` (Django) |
| Go | `cmd/*/main.go`, `main.go` |
| Rust | `src/main.rs`, `src/lib.rs` |

Read the entry point file. Note what it initializes.

### Module Mapping

List directories at the top level of `src/`, `lib/`, `app/`, `pkg/`, or equivalent. For each:
- Read the directory listing
- If there's an `index.ts`, `__init__.py`, or equivalent, read the first 20 lines
- Write a one-line description of what that module does

Cap at 10 modules. If there are more, note the count and describe the most significant.

### Infrastructure Detection

| File/Pattern | Indicates |
|-------------|-----------|
| `docker-compose.yml` | Local Docker services — read service names |
| `Dockerfile` | Containerized deployment |
| `.github/workflows/` | GitHub Actions CI |
| `*.tf` files | Terraform infrastructure |
| `k8s/` or `kubernetes/` | Kubernetes deployment |
| `.env.example` | Read to understand required environment variables |

### Existing Docs

Read `README.md` (first 50 lines). Extract anything that describes architecture, constraints, or setup requirements not already captured.

## Output Format

Write directly to `context/project.md`, replacing template placeholders. Do not append — overwrite the template sections with real data.

Sections to populate:
- **Identity** — name, type (derived from stack), status (assume "active development" unless README says otherwise)
- **Tech Stack** — language, framework, database (from docker-compose or env vars), infrastructure
- **Architecture** — 2-3 sentences from README + entry point reading
- **Current State** — leave "In Progress" and "Known Issues" blank for user to fill — note this
- **Do Not** — leave blank for user to fill — note this

## After Writing

State: "context/project.md populated. Please review and fill in:
- Current State → In Progress and Known Issues
- Do Not → approaches specific to this project
- Constraints → anything that can't be changed"

## Anti-Patterns

Do not guess at framework from file extensions alone. Read the manifest.

Do not list every dependency — only the non-obvious ones that shape how the project works.

Do not overwrite anything the user has already filled in. If a section has real content (not template placeholder text), preserve it.

## Mandatory Checklist

1. Verify at least one manifest file was read (not guessed from extensions)
2. Verify entry points were read, not just listed
3. Verify key modules have one-line descriptions from reading, not inference
4. Verify context/project.md was written (not just displayed in chat)
5. Verify user was told which sections still need manual input