Code Wiki

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 existing Hermes tools (terminal, read_file, search_files, write_file); 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 — use read_file and answer inline
• Strategic "why does this exist" narrative — different skill, different purpose
• Codebases the user is actively developing in this session — just answer questions as they come

Prerequisites

• No env vars required.
• git on PATH for repo SHA tracking and remote clones.
• Optional: pygount for language-breakdown stats (see the codebase-inspection skill).

How to Run

Invoke through the terminal tool from the target repo's root, then use read_file / search_files / write_file to produce the wiki. Default output location is ~/.hermes/wikis/<repo-name>/. Only write into the repo (docs/wiki/) when the user explicitly requests it.

Quick Reference

Procedure

1. Resolve the target

For a GitHub URL:

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):

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

Then set the output dir:

OUTPUT_DIR="$HOME/.hermes/wikis/$REPO_NAME"
mkdir -p "$OUTPUT_DIR/modules" "$OUTPUT_DIR/diagrams"

2. Scan repo structure

Use the terminal tool for the shell work, read_file for manifests:

# Shallow tree first
ls -la

# Deeper tree, noise filtered
find . -type d \
  -not -path '*/\.*' \
  -not -path '*/node_modules*' \
  -not -path '*/venv*' \
  -not -path '*/__pycache__*' \
  -not -path '*/dist*' \
  -not -path '*/build*' \
  -not -path '*/target*' \
  -maxdepth 3 | sort

# Language breakdown (skip if pygount unavailable)
pygount --format=summary \
  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,target" \
  . 2>/dev/null || true

Then read_file the relevant manifests (package.json, pyproject.toml, setup.py, Cargo.toml, go.mod, pom.xml, build.gradle) and the project README. Use search_files target='files' to find them rather than guessing names.

3. Pick modules to document

Cap initial pass at 8–10 modules. Heuristics by language:

• Python: top-level packages (dirs with __init__.py), plus subsystem dirs
• JS/TS: src/<subdir>, top-level workspace dirs
• Rust: each crate in a workspace, or top-level src/<module> dirs
• Go: each top-level package directory
• Mixed/unfamiliar: top-level directories that contain source code (not config, not tests)

For very large repos, prioritize by: 1. Imported-from count (a module imported by many is core) 2. LOC (bigger modules usually warrant their own doc) 3. Mentions in README / top-level docs

State the module list to the user before generating per-module docs on big repos — gives them a chance to redirect.

4. Write README.md

read_file the actual project README plus the top 2–3 entry-point files. Then write_file:

````markdown

<Project Name>

<One paragraph: what it is and what it's for. Self-contained — don't assume the reader has the source README.>

Key Concepts

• <Concept 1> — <one line>
• <Concept 2> — <one line>

Entry Points

• `path/to/main.py` — <what runs when you start it>
• `path/to/cli.py` — <CLI surface>

High-Level Architecture

<2-3 sentences. Detail goes in architecture.md.>

See architecture.md.

Module Map

Getting Started

See getting-started.md. ````

For link targets in local mode use relative paths. For cloned repos use https://github.com/<owner>/<repo>/blob/<sha>/<path> so links survive future commits.

5. Write architecture.md

````markdown

Architecture

<2-3 paragraphs: shape of the system. What talks to what. Where data enters, where it exits, where state lives.>

Components

• <Component> — <1-2 sentences>. See `modules/<module>.md`.

System Diagram

flowchart TD
    User([User]) --> Entry[Entry Point]
    Entry --> Core[Core Engine]
    Core --> StorageA[(Database)]
    Core --> ExternalAPI{{External API}}

Data Flow

1. <Step> — `<file>` 2. <Step> — `<file>`

Key Design Decisions

• <Anything load-bearing the reader should know>

````

Mermaid shape semantics:

• [] = component
• [()] = database / storage
• {{}} = external service
• (()) = entry point or terminal
• --> = sync call, -.-> = async/event

Cap at ~20 nodes per diagram. Split into sub-diagrams if larger.

6. Write per-module docs in modules/

For each selected module, inspect its layout with ls, identify 3–5 most important files (by size, by being named core.py / main.py / __init__.py, by being imported a lot), then read_file those files (use offset / limit to read only what you need; prefer search_files for specific symbols).

````markdown

Module: <module>

<1-2 sentence purpose.>

Responsibilities

• <bullet>
• <bullet>

Key Files

• `<module>/<file>` — <what it does>

Public API

<Functions/classes/constants other code uses. Group related items. Show signatures, not full implementations.>

Internal Structure

<How the module is organized internally. State management.>

Dependencies

• Used by: <other modules>
• Uses: <other modules + external libs>

Notable Patterns / Gotchas

• <Anything non-obvious>

````

7. Write diagrams/class-diagram.md

Pick the 5–10 most important classes/types. read_file them, then write:

````markdown

Class Diagram

Core Types

classDiagram
    class Agent {
        +string name
        +list~Tool~ tools
        +chat(message) string
    }
    class Tool {
        <<interface>>
        +name string
        +execute(args) any
    }
    Agent --> Tool : uses
    Tool <|-- TerminalTool
    Tool <|-- WebTool

Notes

<Anything the diagram can't express — lifecycle, threading, etc.> ````

For languages without classes (Go, C, Rust): use the diagram for struct relationships, or skip class-diagram.md and explain it in prose in architecture.md. Don't force-fit.

8. Write diagrams/sequences.md

Pick 2–4 of the most important workflows. Trace each call path through the code (read entry point, follow function calls), then:

````markdown

Sequence Diagrams

Workflow: <Name>

<1 sentence describing what this does and when it runs.>

sequenceDiagram
    participant User
    participant CLI
    participant Agent
    participant LLM
    User->>CLI: types message
    CLI->>Agent: chat(message)
    Agent->>LLM: API call
    LLM-->>Agent: response + tool_calls
    Agent->>Agent: execute tools
    Agent-->>CLI: final response

Walkthrough

1. User input — `cli.py:HermesCLI.run_session` 2. Message dispatch — `run_agent.py:AIAgent.chat` ````

Don't invent participants. Every box must correspond to a real component the reader can find in the code.

9. Write getting-started.md

````markdown

Getting Started

Prerequisites

<From manifest files + README. Be specific — versions if pinned.>

Installation

<exact commands>

First Run

<minimum command to see the system do something useful>

Common Workflows

<Workflow 1>

<commands>

Configuration

• <config-file> — <what it controls>
• Env var <VAR> — <what it controls>

Where to Go Next

• Architecture: architecture.md
• Module reference: README.md#module-map

````

10. Write api.md (skip if not applicable)

Only write this if the project is a library or API server. If it is:

• Find the public API surface (__init__.py exports, OpenAPI specs, route handlers, exported types)
• Document each public entry with signature, parameters, return type, one-line description
• Group by category

11. Write the state file

cat > "$OUTPUT_DIR/.codewiki-state.json" <<EOF
{
  "repo_name": "$REPO_NAME",
  "source_path": "$PWD",
  "source_sha": "$REPO_SHA",
  "generated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "generator": "hermes-agent code-wiki skill v0.1.0",
  "modules_documented": []
}
EOF

12. Report to user

State exactly what was generated and where:

Generated wiki at ~/.hermes/wikis/<repo-name>/:
  README.md                   project overview, module map
  architecture.md             system architecture + flowchart
  getting-started.md          setup, first run, workflows
  modules/<N files>           per-module deep-dives
  diagrams/architecture.md    Mermaid flowchart
  diagrams/class-diagram.md   Mermaid class diagram
  diagrams/sequences.md       Mermaid sequence diagrams

If you cloned to a temp dir, remind the user it can be removed (rm -rf "$WIKI_TMP") after they've reviewed the wiki.

Scope Control

Generating a full wiki for a 500K-LOC monorepo is wildly token-expensive. Default to bounded scope:

• Initial scan: max depth 3 directories
• Per-module docs: cap at 10 modules unless user expands scope
• Per-file reads: prefer search_files for symbols + read_file with offset/limit over full reads
• Skip vendored code (vendor/, third_party/, generated code, _pb2.py, .min.js)

If the user says "do the whole thing exhaustively", believe them — but ballpark the cost first: "this repo has ~340 source files, comprehensive coverage will be expensive — confirm?"

Re-Run / Update

If .codewiki-state.json already exists at the target path:

• Read it for previous SHA and module list
• If source SHA matches: ask user if they want to regenerate or skip
• If SHA differs: offer to regenerate only modules with changed files (git diff --name-only <old-sha> HEAD)

Full incremental-regeneration is a future enhancement — for now, regenerating the whole thing is acceptable.

Pitfalls

• Fabricating components. Every diagram node and claimed function call must be in the source. read_file before writing. The single biggest failure mode for auto-generated docs is plausible-sounding fabrication.
• Generic AI prose. "This module is responsible for..." is content-free. Say what the module actually does in domain-specific terms.
• Restating code as prose. A module doc that says "the process function processes things by calling process_item on each item" is worse than just linking to the function.
• Mermaid > 50 nodes. They don't render legibly. Split them.
• Documenting tests, generated code, or vendored deps as if they were product code. Skip them.
• In-repo output without asking. Default is ~/.hermes/wikis/. Only write into the repo when the user explicitly requests it.
• Mermaid special chars need quotes: A["Tool / Agent"] not A[Tool / Agent]. <br> for line breaks inside a node.
• Nested code fences in SKILL.md. When writing a markdown example that contains a Mermaid block, use 4-backtick outer fences so the 3-backtick inner `mermaid doesn't close the outer. (This SKILL.md does it.)
• classDiagram generics render as ~T~ (e.g. List~Tool~), not <T>.
• GitHub Mermaid theme is fixed — don't include %%{init: ...}%% blocks; they're stripped on render.

Verification

After writing, verify:

1. Mermaid blocks balance — opens equal closes per file:

   for f in "$OUTPUT_DIR"/diagrams/*.md "$OUTPUT_DIR"/architecture.md; do
     opens=$(grep -c '^```mermaid' "$f")
     total=$(grep -c '^```' "$f")
     echo "$f: $opens mermaid blocks, $total total fences (expect total = opens*2)"
   done

2. All expected files exist —

   ls "$OUTPUT_DIR"/{README.md,architecture.md,getting-started.md,.codewiki-state.json} \
      "$OUTPUT_DIR"/modules/ "$OUTPUT_DIR"/diagrams/

3. Module count matches what you intended — ls "$OUTPUT_DIR/modules" | wc -l should equal the number of modules you committed to in Step 3. 4. No fabricated paths — sanity-check 2–3 source links resolve to real files.

Architecture

{{TWO_TO_THREE_PARAGRAPHS_SHAPE_OF_SYSTEM}}

Components

• {{COMPONENT_1}} — {{ONE_TO_TWO_SENTENCES}} See `modules/{{MODULE}}.md`.
• {{COMPONENT_2}} — {{ONE_TO_TWO_SENTENCES}}

System Diagram

flowchart TD
    User([User]) --> Entry[Entry Point]
    Entry --> Core[Core Engine]
    Core --> StorageA[(Database)]
    Core --> ExternalAPI{{External API}}

Data Flow

1. {{STEP_1}} — `{{FILE}}` 2. {{STEP_2}} — `{{FILE}}` 3. {{STEP_3}} — `{{FILE}}`

Key Design Decisions

• {{DECISION_1}}
• {{DECISION_2}}
• {{DECISION_3}}

Getting Started

Prerequisites

• {{LANGUAGE_RUNTIME_VERSION}}
• {{DEPENDENCY}}

Installation

{{INSTALL_COMMANDS}}

First Run

{{FIRST_RUN_COMMAND}}

You should see {{EXPECTED_OUTPUT}}.

Common Workflows

{{WORKFLOW_1}}

{{COMMANDS}}

{{WORKFLOW_2}}

{{COMMANDS}}

Configuration

Key config files and settings:

• {{CONFIG_FILE}} — {{WHAT_IT_CONTROLS}}
• Env var {{VAR}} — {{WHAT_IT_CONTROLS}}

Where to Go Next

• Architecture overview: architecture.md
• Module reference: README.md#module-map
• Diagrams: diagrams/

Module: {{MODULE_NAME}}

{{ONE_TO_TWO_SENTENCE_PURPOSE}}

Responsibilities

• {{BULLET_1}}
• {{BULLET_2}}
• {{BULLET_3}}

Key Files

• `{{PATH_1}}` — {{WHAT_IT_DOES}}
• `{{PATH_2}}` — {{WHAT_IT_DOES}}

Public API

{{FUNCTION_NAME}}({{SIGNATURE}})

{{ONE_LINE_DESCRIPTION}}

Parameters:

• {{PARAM}} ({{TYPE}}) — {{DESCRIPTION}}

Returns: {{TYPE}} — {{DESCRIPTION}}

Internal Structure

{{HOW_THE_MODULE_IS_ORGANIZED}}

Dependencies

• Used by: {{OTHER_MODULES}}
• Uses: {{OTHER_MODULES_AND_LIBS}}

Notable Patterns / Gotchas

• {{ANYTHING_NON_OBVIOUS}}

{{PROJECT_NAME}}

{{ONE_PARAGRAPH_DESCRIPTION}}

Key Concepts

• {{CONCEPT_1}} — {{ONE_LINE}}
• {{CONCEPT_2}} — {{ONE_LINE}}
• {{CONCEPT_3}} — {{ONE_LINE}}

Entry Points

• `{{PATH_1}}` — {{WHAT_IT_DOES}}
• `{{PATH_2}}` — {{WHAT_IT_DOES}}

High-Level Architecture

{{TWO_TO_THREE_SENTENCES}}

See architecture.md for the full picture.

Module Map

Getting Started

See getting-started.md.