# Index Repo Py

> Create or update PROJECT_INDEX.md for python fastapi project

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

---


# Repository Index Creator

Create or update `PROJECT_INDEX.md` — a compact markdown index that gives the LLM full codebase navigation without reading every file.

## Why

- Reading all files costs ~58,000 tokens per session
- Reading the index costs ~1,000 tokens (98% reduction)
- Exports in the index save additional Read tool calls during discovery

## How to Run

**Create index**: `/index-repo`
**Update index**: `/index-repo update`

## Process

1. **Glob** all source and test files in parallel:
   - `src/**/*.py`, `tests/**/*.py`
   - `*.toml`, `Makefile`

2. **Read** each file, extract:
   - Purpose (1-line description)
   - Exports (public classes, functions, constants)
   - Status (only mark stubs — implemented is the default)
   - Endpoints (for routers)
   - Fixtures (for test conftest files)

3. **Write** `PROJECT_INDEX.md` using the compact format below.

## Output Format

Single file: `PROJECT_INDEX.md` (target: <3KB)

```
# {Project Name} | {Framework} | {Python version} | {Package manager}

## Commands
run: {command}
test: {command}
lint: {command}
fix: {command}

## Architecture
- key: value (one line per architectural decision)

## Modules

path/to/file.py — one-line purpose
  exports: Class1, Class2, function1

### path/to/package/ [STUB if not implemented]

file.py — purpose
  exports: ExportedName

## Tests ({count} total, {status})

conftest.py — fixtures: fixture1, fixture2
test_file.py ({count}), test_other.py ({count})
```

## Rules

- **One line per module**: `path — purpose`
- **Exports on indented line below**: `  exports: Name1, Name2`
- **Only mark exceptions**: stubs get `[STUB]`, implemented is assumed
- **Group by directory** with `###` headers to avoid repeating paths
- **Tests are compact**: `test_file.py (count)` on shared lines
- **No duplicated data**: skip deps (in pyproject.toml), CI config, test class names
- **Keep under 3KB**