repo-wiki

name repo-wiki description Generate and maintain citation-backed repository wikis as MkDocs-compatible Markdown. Creates baseline docs, detects changes, and incrementally updates only affected pages with file path and line number citations. license MIT compatibility Requires git, filesystem access, and uv (Python package manager). Works with any git repository. metadata {"version":"1.0.0","author":"Agent Skills","category":"documentation"} allowed-tools cat ls git uv Repo Wiki Agent Skill Generate and maintain a living, citation-backed wiki for any codebase as structured Markdown files compatible with MkDocs. What This Skill Does This skill enables agents to: Generate baseline wiki - Create complete documentation from scratch Track changes - Detect code modifications via git diff Update incrementally - Refresh only impacted pages, not entire wiki Add citations - Link every technical claim to specific file paths and line ranges Maintain traceability - Generate clickable permalinks to source code Preserve human edits - Only update managed blocks, leave manual edits intact When to Use This Skill Use this skill when you need to: Document a new codebase with comprehensive, citation-backed pages Keep documentation synchronized with code changes Provide trustworthy docs that reviewers can verify against source code Create onboarding materials for new engineers Generate architectural overviews with source traceability Maintain a "living wiki" that updates incrementally after each change How It Works This skill is composed of specialized sub-skills that work together: repo-wiki-initialize - Set up wiki structure and baseline repo-wiki-index - Build a searchable code map repo-wiki-generate - Create citation-backed markdown pages repo-wiki-detect - Find changes since last run repo-wiki-update - Incrementally refresh affected pages repo-wiki-validate - Verify citations and quality gates Quick Start Generate a New Wiki # Activate the initialize sub-skill cat /path/to/skills/repo-wiki-initialize/SKILL.md # Follow instructions to create baseline wiki Update Existing Wiki After Code Changes # Activate the detect changes sub-skill cat /path/to/skills/repo-wiki-detect/SKILL.md # Then activate the update sub-skill cat /path/to/skills/repo-wiki-update/SKILL.md Validate Wiki Quality # Activate the validate sub-skill cat /path/to/skills/repo-wiki-validate/SKILL.md Workflow Overview First-Time Wiki Creation Read repo-wiki-initialize/SKILL.md for initialization instructions Read repo-wiki-index/SKILL.md to build code map Read repo-wiki-generate/SKILL.md to generate pages with citations Read repo-wiki-validate/SKILL.md to verify output quality Incremental Updates (After Code Changes) Read repo-wiki-detect/SKILL.md to identify changes Read repo-wiki-update/SKILL.md to refresh impacted pages Read repo-wiki-validate/SKILL.md to verify changes Output Structure The skill generates a MkDocs-compatible documentation tree: <repo>/ mkdocs.yml # MkDocs configuration docs/ index.md # Overview getting-started/ local-dev.md configuration.md architecture/ overview.md data-flow.md dependency-map.md components/ <component-name>.md # One per major component api/ endpoints.md operations/ build-and-test.md deploy.md glossary.md .repo_wiki/ state.json # Tracks baseline commit & page mappings manifest.json # Citations and source fingerprints logs/ Citation Format Every technical claim includes citations with file paths and line ranges: Inline Format: The service starts an HTTP server on the configured port. Source: `src/server.ts` L12–L48 Footnote Format (Preferred): The service starts an HTTP server[^1]. [ ^1 ]: `src/server.ts` L12–L48 (commit abc1234) Remote Permalink (When Git Remote Available): [ ^1 ]: [ src/server.ts#L12-L48 ]( https://github.com/org/repo/blob/abc1234/src/server.ts#L12-L48 ) Key Principles Citation-backed : Every non-trivial technical statement must have a citation Incremental : Only update what changed, minimize diff size Deterministic : Same commit = same output (modulo timestamps) Safe : Exclude secrets, avoid overwriting manual edits Verifiable : Citations must point to valid file:line ranges Reviewable : Small PRs, stable formatting, link-checkable Reference Materials For detailed information, see the references/ directory: references/CITATION-SPEC.md - Citation format and coverage rules references/ARCHITECTURE.md - Skill design and module relationships references/STATE-FORMAT.md - State file schema and usage references/TEMPLATES.md - Page template specifications Scripts Helper scripts are available in scripts/ directory: scripts/validate_citations.py - Verify all citations resolve correctly scripts/generate_permalinks.py - Convert local citations to remote URLs scripts/detect_managed_blocks.py - Find and parse managed block markers scripts/compute_page_impact.py - Determine which pages need updates Assets Templates and resources in assets/ directory: assets/templates/mkdocs.yml.template - MkDocs config template assets/templates/component-page.md.template - Component page structure assets/templates/overview-page.md.template - Overview page structure assets/templates/architecture-page.md.template - Architecture page structure