semantic-git

semantic-git generates human-readable documentation that explains what a codebase does, so someone can understand the system without reading code.

It creates *.semantic.md files colocated next to the source code they describe — visible right in your IDE file tree. These files use plain English, mermaid diagrams, and structured explanations to make any codebase approachable.

What It Does

• Analyzes a repository and generates documentation at the right level of granularity
• Places docs next to the code: notes.semantic.md appears right beside notes.ts
• Creates repo-level overviews (OVERVIEW.semantic.md, ARCHITECTURE.semantic.md) with system diagrams
• Updates incrementally on commits — only regenerates docs for changed code
• Works on any language or framework

Skills

Skill	Description
semantic-git	Generate and maintain colocated codebase documentation

Quick Start

Claude Code

Register this repository as a plugin marketplace:

/plugin marketplace add <repo-url>

Then install the skill:

/plugin install semantic-git-skills@semantic-git-skills

Or install directly by adding the skill folder to your Claude Code configuration.

Usage

Once installed, use any of these to trigger the skill:

• /semantic-git — full generation for the current repo
• "document this repo" — Claude will use the skill automatically
• "explain this codebase" — triggers on documentation-related requests
• Commit or open a PR — the skill updates docs incrementally

Example Output

After running on a repo, you'll see files like:

your-repo/
├── OVERVIEW.semantic.md                    # What the project does, reading guide
├── ARCHITECTURE.semantic.md                # System diagrams, design decisions
├── .semantic-manifest.json                 # Tracks doc coverage and freshness
├── src/
│   ├── auth/
│   │   └── .semantic.md                    # Explains the auth module
│   ├── lib/
│   │   ├── processor.ts
│   │   ├── processor.semantic.md           # Explains processor.ts
│   │   └── utils/
│   │       └── .semantic.md                # Explains the utils directory

Each file contains:

• A plain-English summary of what the code does and why
• Mermaid diagrams showing how components connect
• Key concepts defined in accessible language
• "Important files" pointers for when you do need to read code
• Edge cases and gotchas

How It Works

1. Scans the repo structure, reads .gitignore, identifies logical modules
2. Decides granularity — directories get .semantic.md, complex individual files get <name>.semantic.md
3. Generates documentation using simple explanations and diagrams
4. Tracks what's documented in .semantic-manifest.json with commit SHAs
5. Updates incrementally — on subsequent runs, only regenerates docs for changed code

Creating Your Own Skills

See the template for a minimal skill starting point, or read the Agent Skills specification.

License

Apache 2.0 — see LICENSE.