code-wiki

Files (8)

• SKILL.md
• __init__.py
• __init__.py · scripts/
• core.py · scripts/
• README.md · templates/
• architecture.md · templates/
• getting-started.md · templates/
• module.md · templates/

SKILL.md (first lines)

# Code Wiki Skill

Generate a comprehensive wiki for any codebase — overview, architecture, per-module deep-dives, Mermaid class and sequence diagrams. Inspired by Google CodeWiki, but works on local repos, private repos, and any language. Uses only standard tools (shell, file reading/writing, search); no Docker, no external services, no extra dependencies.

This skill produces **reference documentation** (what/how). It does not produce strategic narrative (why — that's a different skill).

## When to Use

- User says "document this codebase", "generate a wiki", "make architecture diagrams"
- Onboarding to an unfamiliar repo and wants a structured reference
- User points at a GitHub URL and asks for documentation
- Need a stable artifact (markdown + Mermaid) that renders on GitHub

Do NOT use this for:
- Single-file or single-function documentation — just answer directly
- API reference for one specific endpoint — answer inline
- Strategic "why does this exist" narrative — different purpose
- Codebases the user is actively developing in this session — just answer questions as they come

## Quick Reference

| Step | Action |
|---|---|
| 0 | **Try the deterministic export** from a code_intel index (no LLM); fall back to the procedure below only when it reports `fallback` |
| 1 | Resolve target — local cwd, given path, or `git clone --depth 50 <url>` to a temp dir |
| 2 | Scan structure — `ls`, `find -maxdepth 3`, manifest files, README |
| 3 | Pick 8–10 modules to document |
| 4 | Write `README.md` (overview + module map) |
| 5 | Write `architecture.md` with Mermaid flowchart |
| 6 | Write per-module docs in `modules/` |
| 7 | Write `diagrams/class-diagram.md` (Mermaid classDiagram) |
| 8 | Write `diagrams/sequences.md` (Mermaid sequenceDiagram, 2–4 workflows) |
| 9 | Write `getting-started.md` |
| 10 | Write `api.md` if applicable, else skip |
| 11 | Write `.codewiki-state.json` |
| 12 | Report paths to user |

## Procedure

### 0. Prefer the deterministic export (code_intel index)

When the target repository is Python / TypeScript / TSX / JavaScript / Rust / Go,
build (or refresh) its code_intel index and export the wiki from it. This path is
deterministic, makes zero LLM calls, and produces `README.md`,
`architecture.md`, `modules/*.md`, `diagrams/class-diagram.md` and
`diagrams/sequences.md` from the symbol/edge tables. It also writes
`.codewiki-state.json` with `"generator": "code_intel_export"`.

```python
from pathlib import Path
from agent.tools.code_intel import CodeIndexer
from config.features.agent_side import CODE_INTEL
from skills.builtin.code_wiki.scripts.core import export_wiki_from_index

root = Path("<repo path>").resolve()
db_path = root / ".codeintel" / "index.db"  # honored only when SHERRY_CODE_INTEL_DB is unset
CodeIndexer(str(db_path), CODE_INTEL).index_directory(root)  # incremental
result = export_wiki_from_index("<repo_name>", str(db_path))
if result.get("fallback"):
    print(result["reason"])  # index_not_found / empty_index / unsupported_language
    # → continue with the LLM-driven procedure below
```

`export_wiki_from_index` never overwrites the existing path-management helpers
(`init_repo_wiki` / `get_repo_wiki_path` / ...); it is an independent entry point.
`diagrams/sequences.md` is intentionally a note: runtime call flow is not
representable from a static AST, so sequence diagrams stay LLM-generated.
Communities come from networkx Louvain when available; without networkx the
exporter falls back to connected components and records `community_engine`.

### 1. Resolve the target

Capture this agent project's root first — it anchors where output is written. If
the host exports `REPO_ROOT`, use it; otherwise it is the cwd at skill entry
(never the repo being documented):

```bash
REPO_ROOT="${REPO_ROOT:-$PWD}"
```

For a GitHub URL:

```bash
WIKI_TMP=$(mktemp -d)
git clone --depth 50 <url> "$WIKI_TMP/repo"
cd "$WIKI_TMP/repo"
REPO_SHA=$(git rev-parse HEAD)
REPO_NAME=$(basename <url> .git)
```

For a local path (or cwd if none given):

```bash
cd <path>
REPO_SHA=$(git rev-parse HEAD 2>/dev/null || echo "uncommitted")
REPO_NAME=$(basename "$PWD")
```

Then set the output dir — inside this agent project, under `src/data/`:

```bash
WIKI_ROOT="$REPO_ROOT/src/data/wiki"
OUTPUT_DIR="$WIKI_ROOT/$REPO_NAME"
mkdir -p "$OUTPUT_DIR/modules" "$OUTPUT_DIR/diagrams"
```

### 2. Scan repo structure

```bash
# Shallow tree first
ls -la

# Deeper tree, noise filtered
find . -type d \
  -not -path './src/data/wiki*' \
  -not -path './wiki*' \
  -not -path './graphify-out*' \
  -not -path '*/\.*' \
  -not -path '*/node_modules*' \

From lasertsole/sherry_agent, MIT.

More from lasertsole/sherry_agent