# Knowledge > Project Knowledge Expert — Total Mapping - Skill: `ekajto/knowledge` (Agent Skill) - Install (CLI): `npx skillmds@latest add ekajto/knowledge` - Raw SKILL.md: https://api.skillmd.com/api/skills/ekajto/knowledge/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Ekajto (https://skillmd.com/u/ekajto) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/ekajto/knowledge --- # Project Knowledge Expert — Total Mapping You are the absolute expert of this repository. You don't summarize — you map with surgical precision. Every source file is read, every important function is noted, every endpoint is documented. You produce an exhaustive source of truth that allows any developer to understand the project without opening a single file. ## ABSOLUTE RULE: ZERO SHORTCUTS You are not allowed to: - Skip a source file because it's "similar to the others" - Write `...` or `etc.` in the tables — every row must be complete - Summarize in one line what deserves a detailed table - Infer the content of a file without having read it - Limit yourself to a predefined list of files If a file exceeds 300 lines → read in multiple passes (`offset` + `limit`). Never truncated. --- ## Phase 0 — Dynamic repository detection Before any code reading, map the repo structure. The goal is to discover: - The languages present - The framework(s) used - The folder structure (monorepo, single service, multi-package…) - The root configuration files - The existing documentation files ### Inventory commands (all mandatory) ```bash # 1. General tree (2 levels, excluding .git / node_modules / .venv / __pycache__ / dist / build) find . -maxdepth 2 \ -not -path './.git/*' \ -not -path '*/node_modules/*' \ -not -path '*/.venv/*' \ -not -path '*/__pycache__/*' \ -not -path '*/dist/*' \ -not -path '*/build/*' \ -not -path '*/.next/*' \ | sort # 2. Detect languages present find . -name "*.py" -not -path '*/.venv/*' -not -path '*/__pycache__/*' | wc -l find . \( -name "*.ts" -o -name "*.tsx" \) -not -path '*/node_modules/*' -not -path '*/.next/*' | wc -l find . -name "*.go" | wc -l find . -name "*.rs" | wc -l find . -name "*.java" | wc -l find . -name "*.rb" | wc -l # 3. Dependency files (framework detection) find . -maxdepth 3 \( \ -name "package.json" -o \ -name "requirements.txt" -o \ -name "pyproject.toml" -o \ -name "Cargo.toml" -o \ -name "go.mod" -o \ -name "Gemfile" -o \ -name "pom.xml" -o \ -name "build.gradle" \ \) -not -path '*/node_modules/*' | sort # 4. Root configuration files find . -maxdepth 1 \( \ -name "*.json" -o \ -name "*.toml" -o \ -name "*.yaml" -o \ -name "*.yml" -o \ -name "*.env.example" -o \ -name "Dockerfile" -o \ -name "docker-compose*.yml" -o \ -name "*.config.*" \ \) | sort # 5. Existing documentation files find . -name "*.md" \ -not -path '*/node_modules/*' \ -not -path '*/.venv/*' \ | sort # 6. Migrations / DB schemas find . \( -name "*.sql" -o -name "schema.*" \) \ -not -path '*/node_modules/*' | sort find . -path "*/migrations/*.py" -not -path '*/.venv/*' | sort find . -path "*/alembic/versions/*.py" | sort # 7. Complete source files (for Phase 1) # Python find . -name "*.py" \ -not -path '*/.venv/*' \ -not -path '*/__pycache__/*' \ -not -path '*/migrations/*' \ | sort # TypeScript / TSX find . \( -name "*.ts" -o -name "*.tsx" \) \ -not -path '*/node_modules/*' \ -not -path '*/.next/*' \ -not -path '*/dist/*' \ | sort # Go find . -name "*.go" -not -path '*/vendor/*' | sort # 8. CI/CD and infra files find . \( \ -name "*.github" -o \ -path "*/.github/workflows/*.yml" -o \ -name "Dockerfile*" -o \ -name "docker-compose*.yml" -o \ -name "*.tf" \ \) -not -path '*/node_modules/*' | sort ``` ### After the inventory: determine the repository's architecture From the results, identify: 1. **Repo type**: monorepo / single service / multi-package / polyglot 2. **Main languages** (sort by file count) 3. **Detected frameworks**: - Python → FastAPI / Django / Flask / standalone scripts - TypeScript/JS → Next.js / Express / NestJS / React SPA / Node scripts - Go → gin / echo / stdlib - Rust → actix / axum / CLI 4. **Database**: PostgreSQL (SQLAlchemy/asyncpg) / SQLite / MongoDB / Redis / none 5. **Folder structure**: name each sub-project or package identified **This analysis ENTIRELY guides Phase 1 and Phase 2.** Never apply a hardcoded structure — adapt to the realities of the repo. --- ## Phase 1 — Full reading of every source file ### Reading order (adapt to the structure detected in Phase 0) **Group A — Documentation and configuration (always first)** - All `.md` files found: `CLAUDE.md`, `README.md`, `ARCHITECTURE.md`, `CONTEXT.md`, `TODO.md`, `LOGS.md`, and all those detected - All `.env.example` files (never the real `.env`) - All dependency files: `requirements.txt`, `pyproject.toml`, `package.json`, `go.mod`, `Cargo.toml`… - All root config files: `docker-compose.yml`, `Dockerfile`, CI/CD workflows **Group B — Schemas and migrations** - All `.sql` files found - All Alembic migration files (`alembic/versions/*.py`) or Django - ORM schema definition files (`models.py`, `schema.py`, `entities/*.ts`…) **Group C — Entrypoints and application configuration** - The `main.py` / `app.py` / `__main__.py` / `server.py` / `index.ts` / `main.ts` files - The `config.py` / `settings.py` / `config.ts` / `.env.example` files - The global routing files: `routes.py`, `router.ts`, `app/layout.tsx` **Group D — Full source code** (read EVERY file identified in Phase 0) - All Python `.py` files except `.venv` / `__pycache__` / migrations - All TypeScript `.ts` / `.tsx` files except `node_modules` / `.next` / `dist` - All Go `.go` files except `vendor` - All other source files according to detected languages **Group E — Memory and skills files** - All files in `memory/` (if present) - All files in `.claude/commands/` (the other skills) - `tasks/todo.md` or any task tracking file ### Reading rules - Each file: read **in full**, not as an excerpt - File > 300 lines → successive passes with `offset` + `limit` - Use `Grep` to find patterns when in doubt (`grep -rn "pattern" .`) - Count exactly how many files were read — report it in Phase 4 --- ## Phase 2 — Generate / update `CONTEXT.md` **Location**: check if a `CONTEXT.md` already exists in the repo (root, `.claude/`, `docs/`). If it exists, **rewrite it entirely**. If not, **create it at the root** (or in `.claude/` if that folder exists). This file must be complete enough that a developer who has never seen the project understands in detail how everything works without opening a single source file. ### Mandatory structure (adapt the sections to the real architecture) ``` # [Project name] — Complete Context > Updated on [DATE] by /knowledge — [N] source files read --- ## 0. Project snapshot ([DATE]) ┌──────────────────────────────────────────────────────┬──────────┬──────────────────────────────────────────┐ │ Feature / Module │ State │ Notes │ ├──────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────┤ │ [every real feature/module found in the code] │ ✅/🟡/🔴 │ [what blocks, what is WIP, mocks] │ └──────────────────────────────────────────────────────┴──────────┴──────────────────────────────────────────┘ --- ## 1. Vision & functional scope [Narrative description of the project: what it does, for whom, why. At least 3 paragraphs. Complete sentences, no vague bullet points.] --- ## 2. Global architecture [ASCII diagram of the full flow: services, ports, protocols, external dependencies] [Narrative explanation of each component] --- ## 3. Repository structure [ASCII tree of the repo (excluding node_modules / .venv / dist / build / .git)] Each file/folder annotated with its role on the same line. Example: monrepo/ ├── backend/ — Python FastAPI API │ ├── api/ — FastAPI routers │ ├── models/ — SQLAlchemy models │ ├── services/ — business logic │ ├── alembic/ — PostgreSQL migrations │ └── main.py — entrypoint, CORS, lifespan ├── web/ — Next.js frontend │ ├── app/ — App Router pages │ ├── components/ — React components │ └── lib/ — utilities, types, API client ├── agent/ — background workers/agents └── tasks/todo.md — task tracking --- ## 4. [Sub-project / Service A] — Complete architecture > Adapt this section for each sub-project or service detected. > E.g., "Backend FastAPI", "Frontend Next.js", "Agent Worker", "CLI", "Package shared"… ### 4.1 Annotated file tree [ASCII tree of all files in the sub-project with annotations] ### 4.2 Configuration and environment variables ┌──────────────────────────┬──────────┬────────────────────┬────────────────────────────────────────┐ │ Variable / Parameter │ Type │ Default │ Usage │ ├──────────────────────────┼──────────┼────────────────────┼────────────────────────────────────────┤ │ [each real env var] │ str/int… │ [value or —] │ [what it controls in the code] │ └──────────────────────────┴──────────┴────────────────────┴────────────────────────────────────────┘ ### 4.3 API endpoints (if applicable) > One table per router/route group. ┌────────────────────────────────────────┬────────┬──────────────────────────────┬────────────────────────────────────────────┬──────┐ │ Path │ Method │ Parameters │ Real behavior │ State│ ├────────────────────────────────────────┼────────┼──────────────────────────────┼────────────────────────────────────────────┼──────┤ │ [each route found in the code] │ GET… │ [query/path/body params] │ [what the function REALLY does] │ ✅/🟡│ └────────────────────────────────────────┴────────┴──────────────────────────────┴────────────────────────────────────────────┴──────┘ ### 4.4 Data models / Types > One table per Pydantic model / TypeScript interface / Go struct / entity… ┌──────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Model / Type │ Fields (name: type [= default / nullable]) │ ├──────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────┤ │ [ModelName] │ [field1: type1, field2: type2, ...] │ └──────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────┘ ### 4.5 Database schema (if applicable) > One section per table / collection. #### Table `[table_name]` ┌──────────────────┬─────────────────┬──────────────────────────────────────────────────────────┐ │ Column │ SQL type │ Description + constraints │ ├──────────────────┼─────────────────┼──────────────────────────────────────────────────────────┤ │ [column] │ [type] │ [role + nullable/unique/FK/default] │ └──────────────────┴─────────────────┴──────────────────────────────────────────────────────────┘ Indexes: [list] Relations: [FKs and their target table] ### 4.6 Services / Key functions > For each service/utility file: list all exposed functions. #### `[path/file]` ┌───────────────────────────────────────────┬────────────────────────────────────────────────────────────┐ │ Function / Export │ What it does │ ├───────────────────────────────────────────┼────────────────────────────────────────────────────────────┤ │ functionName(param: Type) → ReturnType │ [precise description of the logic] │ └───────────────────────────────────────────┴────────────────────────────────────────────────────────────┘ ### 4.7 Pages / Screens (if frontend) ┌──────────────────────────────────┬────────────────────┬──────────────────────────────────────────────────────────────────┐ │ File │ URL route │ Role + data loaded + API calls │ ├──────────────────────────────────┼────────────────────┼──────────────────────────────────────────────────────────────────┤ │ [page file] │ /[route] │ [what the page does, its fetches, its key states] │ └──────────────────────────────────┴────────────────────┴──────────────────────────────────────────────────────────────────┘ ### 4.8 Dependencies ┌─────────────────────────────────┬─────────────────┬──────────────────────────────────────────────────┐ │ Package │ Version │ Usage in the project │ ├─────────────────────────────────┼─────────────────┼──────────────────────────────────────────────────┤ │ [package] │ [version] │ [what it brings concretely] │ └─────────────────────────────────┴─────────────────┴──────────────────────────────────────────────────┘ > Repeat Section 4 for each sub-project / service identified in Phase 0. --- ## 5. Data flows & interactions between services [ASCII diagrams of the main flows: who calls whom, in what order, with what data] [E.g.: Frontend → API → Service → DB; Worker → Redis → API; etc.] --- ## 6. Authentication & security (if applicable) [Auth stack: JWT / OAuth2 / sessions / API keys / mTLS] [Full flow with ASCII diagram] [Auth-related env variables] [What is implemented vs. what is planned] --- ## 7. Infrastructure & deployment (if applicable) [Docker / docker-compose: defined services, exposed ports, volumes] [CI/CD: triggers, steps, artifacts] [Production vs. dev env variables] --- ## 8. State of mocks / WIP / technical debt > For each not-yet-finalized element found in the code. ┌─────────────────────────────────────────────────┬──────────────┬───────────────────────────────────────────────────────┐ │ Feature / Endpoint / Component │ State │ Reason / Blocker / TODO │ ├─────────────────────────────────────────────────┼──────────────┼───────────────────────────────────────────────────────┤ │ [element] │ 🟡 WIP/Mocked│ [why, what's missing, external dependency] │ └─────────────────────────────────────────────────┴──────────────┴───────────────────────────────────────────────────────┘ --- ## 9. Task tracking — TODO summary > Structured summary of the task tracking file (tasks/todo.md or equivalent). ┌──────────────────────────────────────────────┬───────────┬──────────────────────────────────────────────────┐ │ Task / Feature │ State │ Remaining sub-tasks │ ├──────────────────────────────────────────────┼───────────┼──────────────────────────────────────────────────┤ │ [section title] │ ❌/🟡/✅ │ [what remains to do] │ └──────────────────────────────────────────────┴───────────┴──────────────────────────────────────────────────┘ --- ## 10. Open questions & pending decisions > Everything marked `[?]`, `TODO`, `FIXME`, `to confirm`, `to define` in the code and the doc. 1. [Question / decision] — *Context: [file:line or doc where it's mentioned]* 2. … ``` --- ## Phase 3 — Memory update Create or update the memory files in `memory/` (look for this folder dynamically — it may be at the root, in `.claude/`, or to be created). ### Files to write or update **`memory/project_status.md`** - ✅/🟡/🔴 state of each feature/module - Precise list of what is mocked/WIP and why - Active bugs and identified blockers **`memory/project_architecture.md`** - Complete tech stack with versions - Data flow schematized (ASCII) - DB structure (tables + key columns) - Services and their responsibilities **`memory/backend_routes.md`** (or equivalent depending on stack) - Exhaustive catalog of all API routes - Method, path, parameters, real behavior, state for each route **`memory/frontend_screens.md`** (if frontend present) - All screens/pages with their URL routes - Key components and their roles - API calls made by component **`memory/open_questions.md`** - Open questions found in the code and the doc - Pending decisions - Blocking dependencies (external or internal) Mandatory frontmatter format for each file: ```markdown --- name: [short explicit name] description: [one sentence — file content, used to decide if relevant] type: project --- ``` ### Update `memory/MEMORY.md` Rebuild the full index. One line per memory file, format: ``` - [Title](file.md) — [short hook describing the content in < 100 chars] ``` --- ## Phase 4 — Summary report Display this report in the conversation at the end: ``` ╔══════════════════════════════════════════════════════════════════════╗ ║ /knowledge — [PROJECT] — [DATE] ║ ╠══════════════════════════════════════════════════════════════════════╣ ║ Files read : [exact N — per language] ║ ║ Files written : [N — CONTEXT.md + memories] ║ ╠══════════════════════════════════════════════════════════════════════╣ ║ DETECTED STACK ║ ║ [Language 1] : [N] files — [detected framework] ║ ║ [Language 2] : [N] files — [detected framework] ║ ║ DB: [DB type + ORM if applicable] ║ ╠══════════════════════════════════════════════════════════════════════╣ ║ FEATURE STATE ║ ║ ✅ Operational : [list] ║ ║ 🟡 WIP / Mocked: [list with short reason] ║ ║ 🔴 Blocker : [list] ║ ╠══════════════════════════════════════════════════════════════════════╣ ║ READING COVERAGE ║ ║ [Language] : [N read] / [N found] files ║ ╠══════════════════════════════════════════════════════════════════════╣ ║ NOTABLE DISCOVERIES ║ ║ [Undocumented points, doc vs code divergences, ║ ║ technical debt, unexpected behaviors] ║ ╠══════════════════════════════════════════════════════════════════════╣ ║ UPDATED DOCUMENTS ║ ║ [path/file] — [created / updated] ║ ╚══════════════════════════════════════════════════════════════════════╝ ``` --- ## Absolute rules **Reading:** - Read EACH source file identified in Phase 0 — no exception - File > 300 lines → read in multiple passes — never truncated - Never infer content without having read it - Use `Grep` to find patterns if in doubt **Writing:** - `...` and `etc.` forbidden in tables - Every table = as many rows as real elements found in the code - The described behaviors must match the code read, not what the doc says - Mark `[?]` anything ambiguous rather than inventing **Adaptation to the repo:** - No hardcoded structure — everything is discovered dynamically in Phase 0 - If the repo has no frontend → remove the frontend sections - If it's a monorepo with 5 services → create one Section 4 per service - If it's a CLI with no API → adapt the "Endpoints" sections to "CLI commands" - If it's a library package → document the public exported API - The section names, file paths and structures ALWAYS adapt to the reality of the repo **Never read:** - `.env` files (secrets) - `node_modules/`, `.venv/`, `__pycache__/`, `dist/`, `build/`, `.next/`, `.git/` folders - Lock files: `package-lock.json`, `yarn.lock`, `poetry.lock`