# Codewiki

> >

- **Type:** Skill
- **Install:** `agentstack add skill-ekuttan-codewiki-codewiki`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ekuttan](https://agentstack.voostack.com/s/ekuttan)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ekuttan](https://github.com/ekuttan)
- **Source:** https://github.com/ekuttan/codewiki

## Install

```sh
agentstack add skill-ekuttan-codewiki-codewiki
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# CodeWiki — Product Knowledge Base Generator

Scan code, fetch product context, discover user flows, and generate a structured `codewiki/` knowledge base.

Output templates are in this skill's `templates/` directory. Read each template only when generating that specific file — do NOT load all templates at once.

## HARD RULES

1. **Phase 1 is not optional.** Product context is the difference between a useful wiki and a mechanical code listing. Complete it before scanning. If user can't answer, use the code-first fallback.
2. **Multi-repo workspace must be verified before scanning.** If repos aren't in a shared parent folder, stop and help the user set it up.
3. **Never scan all repos simultaneously.** Use Scan → Write to `_scratch/` → Carry 30-line summary → Next. This is how you survive large multi-repo projects.
4. **Never skip a service in microservices.** User flows that touch 5 services are useless if one is undocumented. Every service gets at least a lightweight scan.
5. **Scan in priority order.** Infrastructure/contracts → gateway → frontends → core business services → supporting services.
6. **Report progress between repos.** Tell the user what you found and which repo is next. Do not ask for permission between repos — just continue. Only pause on errors or contradictions.
7. **On startup, check if `codewiki/_scratch/` exists.** If it does, offer to resume from previous scan data.
8. **Always use `codewiki/` (no dot prefix).** Ensures visibility in file explorers and default git tracking.
9. **Adaptive detection.** If hardcoded grep patterns don't match anything for a component, read the entry point file and trace outward. Don't report "no endpoints found" without trying alternative approaches.
10. **WebFetch failures.** Report the specific error (401, 404, timeout) and continue. Never silently skip a URL.

---

## Phase 1: Product Context Gathering (MANDATORY — DO NOT SKIP)

> **STOP. You MUST complete Phase 1 before scanning any code.**
> Do not run `ls`, `grep`, or read any files until Phase 1 is done.
> If the user says "just scan the code" or tries to skip, explain that
> the wiki quality depends heavily on product context and ask them to
> answer at least questions 1–3 before proceeding.

### Step 1a: Ask the User

Ask all of these in a single message. Mark which are required vs. optional:

1. **Product name** *(required)* — What is this product called?
2. **One-liner** *(required)* — Describe it in one sentence. What does it do and for whom?
3. **Target users** *(required)* — Who uses this? (e.g., developers, marketers, internal ops team)
4. **Product URLs** *(optional but strongly recommended)* — Provide any of:
   - Marketing website / landing page
   - Documentation site
   - API docs URL
   - App Store / Play Store listing
   - README or repo URL (if different from the working directory)
5. **Repo list** *(required for multi-repo)* — If this is a multi-repo product:
   - List all repos (backend, frontend, mobile app, comms, infra, etc.)
   - Are they all cloned into a single parent folder? If not, I'll ask you to set that up.
   - Provide git clone URLs for any not yet cloned.
6. **Anything the code won't tell me?** *(optional)* — Business context, upcoming changes, non-obvious terminology, areas of tech debt, inter-service communication patterns, etc.

**Code-first fallback:** If user says they can't answer 1–3, say: "No problem — I'll scan the code first and come back with my best guess for you to correct." Infer product name from package.json `name` field or README title, one-liner from package.json `description` or README first paragraph, users from UI/API patterns (admin dashboard = internal ops, public signup = consumers, API-only = developers). Present guesses for confirmation before continuing to Phase 2.

### Step 1b: Multi-Repo Workspace Setup

> **For multi-repo products, all repos MUST be cloned into a single parent folder.**
> This is how CodeWiki discovers cross-repo relationships.

Expected structure:
```
/              ← master folder
├── backend/                 ← git clone 
├── frontend/                ← git clone 
├── mobile-app/              ← git clone 
├── comms-service/           ← git clone 
├── shared-libs/             ← git clone 
└── infra/                   ← git clone 
```

**If repos are not yet organized this way**, give the user exact commands:
```bash
mkdir -p ~/projects/ && cd ~/projects/
git clone  
git clone  
# ... etc
```

Then ask the user to `cd` into the master folder and run CodeWiki from there.

**Verify the setup:**
```bash
ls -la
for dir in */; do echo "$dir: $(git -C "$dir" remote get-url origin 2>/dev/null || echo 'not a git repo')"; done
```

If any repos are missing, tell the user which ones and provide the clone command. Do NOT proceed to Phase 2 until the workspace is verified.

### Step 1c: Fetch External Context

For each URL provided, use WebFetch to extract product context.

**Error handling:** If a URL fails (auth wall, 404, timeout), tell the user which URL failed and why, then continue with the rest. Do not silently skip.

For each successful fetch, extract:
- Landing page copy, feature descriptions, value propositions
- App store descriptions and key metadata
- Documentation structure (table of contents, section names)
- API documentation overview (auth method, base URL, resource groups)

### Step 1d: Summarize Before Proceeding

Present a short summary back to the user:
> "Here's what I understand about [Product Name] before I look at the code: ..."

Ask: **"Is this accurate? Anything to correct or add?"**

Only after the user confirms, proceed to Phase 2.

After confirmation, estimate scope:
> "Based on [N repos/components], this will take [several phases]. I'll report progress after each repo/component."

---

## Context Window Management (Multi-Repo Strategy)

> **CRITICAL: Do NOT scan all repos at once.** Scanning multiple repos simultaneously
> will exhaust the context window. Instead, use the Scan → Summarize → Flush → Next
> pattern described below.

### Scan Priority Order

Scan in this order. The goal is top-down: infrastructure first (the "map"), then entry points, then services behind them.

**Priority 1 — Infrastructure & contracts (scan first)**
- `infra/`, `deploy/`, `platform/` — docker-compose, k8s manifests, terraform
- Shared proto/OpenAPI/AsyncAPI specs
- Shared libraries / type packages

*Why first:* Gives you the full service map, ports, dependencies, and contracts before any individual service. It's the table of contents.

**Priority 2 — API gateway / BFF (Backend-for-Frontend)**
- The service that receives external traffic and routes it internally
- Often named: `gateway`, `api-gateway`, `bff`, `proxy`

*Why second:* Shows all user-facing endpoints and which internal service handles each one.

**Priority 3 — Frontend(s)**
- Web frontend, mobile app, admin dashboard
- Scan routes/screens, API client configuration, state management

*Why third:* Now you can map screens → gateway endpoints → internal services.

**Priority 4 — Core business services**
- Services that own primary business data (users, orders, payments, etc.)
- Prioritize by: how many user flows touch this service

**Priority 5 — Supporting services**
- Notifications, analytics, logging, search, file storage
- These are consumed by other services but rarely initiate flows

### The Scan → Summarize → Flush → Next Pattern

For each repo/service, follow this cycle:

```
1. SCAN      Read the repo: tech stack, endpoints, models, events, env vars
2. WRITE     Write findings to codewiki/_scratch/.md (on disk)
3. SUMMARIZE Create a compact summary (max 30 lines) of:
             - What this service does (1-2 sentences)
             - Endpoints it exposes (list)
             - Events it produces/consumes (list)
             - Data models it owns (list)
             - How it connects to other services (list)
4. CARRY     Keep ONLY the compact summary in working memory
5. NEXT      Move to the next repo — raw scan data is on disk, not in context
```

**The `_scratch/` folder:**
```
codewiki/
├── _scratch/                  ← temporary, per-repo scan notes
│   ├── backend.md
│   ├── frontend.md
│   ├── comms-service.md
│   └── ...
├── overview.md                ← final output files (generated in Phase 5)
├── architecture.md
└── ...
```

**Compact summary format** (carried between repo scans):
```markdown
##  |  | 
Purpose: 
Endpoints: GET /users, POST /users, GET /users/:id, ...
Produces: user.created, user.updated
Consumes: payment.completed
Models: User, Role, Session
Calls: payment-service (gRPC), notification-service (HTTP)
DB: postgres (users, roles, sessions tables)
```

### Progress Reporting

After scanning each repo, tell the user:
> "✓ Scanned **backend** (3/6 repos done). Found 14 endpoints, 3 event topics, 5 models.
> Next up: **comms-service**. Continuing..."

Do NOT ask for permission between each repo — just report progress and continue.

---

## Phase 2: Codebase Analysis

### Step 2a: Project Layout & Scoping

**Single-repo projects:**
```bash
ls -la
find . -maxdepth 2 -type f -name "*.json" -o -name "*.toml" -o -name "*.yaml" -o -name "*.yml" -o -name "*.mod" -o -name "*.lock" | head -50
```

**Multi-repo master folder:**
```bash
ls -la
for dir in */; do
  echo "=== $dir ==="
  ls "$dir"/*.json "$dir"/*.toml "$dir"/*.yaml "$dir"/*.yml "$dir"/*.mod "$dir"/Dockerfile 2>/dev/null
  echo ""
done
```

Identify:
- **Single repo:** Project type (monorepo, single app, library, CLI tool, etc.)
- **Multi-repo:** Map each folder to its role (backend, frontend, mobile, comms, infra, shared libs, etc.)

For multi-repo, present the inventory:
> "I found [N] repos in this workspace:
> | Folder | Likely role | Stack signals |
> |--------|------------|---------------|
> | backend/ | API server | go.mod, Dockerfile |
> | frontend/ | Web app | package.json (next), tsconfig.json |
> | ...
>
> I'll scan them in this order: [list in priority order]. Starting now."

#### Architecture Classification

Classify the project:
- **Single app** — one deployable unit (e.g., a Rails app, a Next.js full-stack app)
- **Modular monolith** — one deployable unit with clearly separated internal modules
- **Microservices** — multiple independently deployable services
- **Monorepo with shared packages** — multiple apps/services sharing code via a package manager workspace

Detection signals for **microservices**:
- `docker-compose.yml` defining multiple services with separate build contexts
- Multiple directories each with their own `Dockerfile`
- Multiple directories each with their own dependency files (separate `go.mod`, `package.json`, `requirements.txt`)
- Presence of API gateway, service mesh config, or message broker config
- Proto/OpenAPI/AsyncAPI spec files defining service contracts
- Kubernetes manifests or Helm charts with multiple deployments

State your classification to the user before proceeding.

#### Scoping Gate

**If microservices or multi-service architecture:**
Do NOT ask the user to skip services. Instead, use a two-tier scan:

> "This is a microservices project with [N] services. I found: [list them].
> I'll do a **lightweight scan** of all services first to map the full topology,
> then a **deep scan** of the [3–4] most critical ones.
> Which services are most critical to document in depth?"

**Lightweight scan** (ALL services): tech stack, exposed endpoints/topics/events, data models owned, env vars, Dockerfile/deployment config.
**Deep scan** (user-selected): internal code structure, handler logic, error handling, full file mapping, test coverage.

**If monolith or single app with many modules:**
> "This is a large project with [N] components. I found: [list them].
> Which ones should I focus on? I recommend starting with [top 3–4 by importance],
> and I can document the rest in a follow-up pass."

Wait for user to confirm scope before continuing.

#### Infrastructure-as-Architecture (Microservices only)

Before scanning individual services, read the infrastructure layer — it IS the architecture map:

```bash
# Docker compose — shows service dependencies, ports, networks
cat docker-compose*.yml 2>/dev/null

# Kubernetes — shows deployments, services, ingress
find . -path "*/k8s/*" -o -path "*/helm/*" -o -path "*/kubernetes/*" | head -30

# API gateway config
find . -name "nginx.conf" -o -name "kong.yml" -o -name "traefik.*" -o -name "envoy.*" | head -10

# Message broker config
find . -name "*.proto" -o -name "asyncapi.*" -o -name "*.avsc" | head -20
```

From this, build an initial **service topology** before looking at any service code:
- Which services exist and their ports
- Which services depend on which (links, depends_on, network policies)
- What shared infrastructure exists (databases, message brokers, caches, object storage)
- What the external entry points are (API gateway, load balancer, CDN)

Present this topology to the user for confirmation before deep-scanning individual services.

### Step 2b: Per-Component Analysis

For each component **in scope**, analyze:

**Tech stack** — Read dependency/config files:
- package.json, tsconfig.json (Node/TS)
- go.mod, go.sum (Go)
- requirements.txt, pyproject.toml, setup.py (Python)
- Cargo.toml (Rust)
- pubspec.yaml (Flutter/Dart)

If none of the above exist, check for other indicators (Gemfile, pom.xml, build.gradle, mix.exs, etc.) and adapt accordingly. Don't assume a fixed set of languages.

**Entry points** — Find main files:
- Look for `main.*`, `index.*`, `app.*`, `server.*` in src/ or root
- Check package.json `main`/`bin` fields, or `[tool.poetry.scripts]`, etc.

**Routes/Screens** — Discover user-facing paths:
- Web: Grep for route definitions in the framework's style (React Router, Next.js pages/app dir, Express `app.get`, etc.)
- Mobile: Look for screen/navigation definitions

**API endpoints** — Find all route/handler definitions:
- REST: Grep for HTTP method decorators/calls (`@Get`, `@Post`, `app.get(`, `router.`, etc.)
- GraphQL: Look for schema files, resolver definitions
- tRPC: Look for router definitions
- If no patterns match, read the main entry point and trace outward

**Data models** — Find schemas and types:
- Database migrations: `migrations/`, `db/migrate/`, `alembic/`
- ORM models: Look for model/entity definition patterns in the detected framework
- TypeScript types/interfaces: key type definition files
- Prisma schema, GraphQL type definitions, protobuf files

**Environment variables** — Find config:
- `.env.example`, `.env.sample`, `.env.template`
- Docker compose files for service-level env vars
- Config files that reference `process.env`, `os.environ`, `os.Getenv`, etc.

**Build/run/test commands** — Find all dev commands:
- package.json scripts section
- Makefile, Taskfile.yml, Justfile
- Docker and docker-compose files
- CI/CD configs (.github/workflows/, .gitlab-ci.yml, etc.)

#### Additional Fields for Microservices

If the project was classified as microservices, also capture for EACH service:

**Service identity:**
- Service name (as defined in docker-compose, k8s manifests, or code)
- Port(s) it listens on
- Whether it's user-facing (external) or internal-only

**Data ownership:**
- Which database(s) does this service own?
- Does it have its own DB, or share with another service?
- What are the primary tables/collections it manages?

**Events & messages (produced and consumed):**
- Message queue topics/channels this service publishes to
- Topics/channels it subscribes to / consumes from
- Look for: RabbitMQ channel/queue definitions, Kafka topic configs, Redis pub/sub, AWS SQS/SNS, NATS subjects, event emitter patterns
- Grep for: `publish(`, `emit(`, `produce(`, `subscribe(`, `consume(`, `on(`, queue/topic name strings in config files

**Synchronous service-to-service calls:**
- gRPC client stubs and proto imports
- HTTP calls to other internal services (look for internal base URLs, service discovery patterns, or hardcoded `localhost:` in dev

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ekuttan](https://github.com/ekuttan)
- **Source:** [ekuttan/codewiki](https://github.com/ekuttan/codewiki)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ekuttan-codewiki-codewiki
- Seller: https://agentstack.voostack.com/s/ekuttan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.