Offline docs-as-code for any backend and frontend: a MkDocs site in your repo, by your AI agent.
io.github.julvc/snapdoczilla (MCP Server)
snapdoczilla is an offline docs-as-code MCP server. It supports creating and maintaining a MkDocs site directly within a repository, including for both backend and frontend documentation workflows.
Agent skills I use on real projects. Small, readable, easy to adapt. They follow the open Agent Skills format (SKILL.md), so they work in Claude Code first and also in Codex, OpenCode, Antigravity, Gemini CLI and other agents.
Documentation for any backend and any frontend as an offline HTML site inside your repo. Anyone reads it with a double click; any dev updates it with one command. Mermaid diagrams, API map, ADRs and react.dev-style component pages with real code and real usage.
A component page generated by SnapDoczilla: real usage and real source, pulled from the repo on every build.
Installation (30-second setup)
Two options. The Claude Code plugin is a managed bundle that updates when I ship. skills.sh copies editable files into your project, for any agent. Pick one: installing both gives you every skill twice.
Claude Code (plugin)
bash
claude plugin marketplace add julvc/skills
claude plugin install snapdoczilla@juliovc
Invoke it with /snapdoczilla:snapdoczilla, or just ask "document this project": Claude picks it up on its own.
Codex, OpenCode, Antigravity, Gemini CLI and other agents
bash
npx skills@latest add julvc/skills
Pick the skills and the agents to install them on. Or install one skill on one agent with no prompts:
bash
npx skills@latest add julvc/skills --skill snapdoczilla -a codex -y
Agent ids: claude-code, codex, opencode, antigravity, gemini-cli. Add -g to install globally instead of in the current project.
Manual (no tooling)
Copy skills/snapdoczilla/ into your agent's skills folder:
Agent
Project
Global
Claude Code
.claude/skills/
~/.claude/skills/
Codex
.agents/skills/
~/.codex/skills/
OpenCode
.agents/skills/
~/.config/opencode/skills/
Antigravity
.agents/skills/
~/.gemini/antigravity/skills/
MCP server (Claude Desktop, Cursor and any MCP client)
Prefer MCP over skills, or your client has no skills support? SnapDoczilla also ships as a local MCP server (stdio, Python). The agent still writes the docs from your code; the server does the deterministic parts: install, "what changed since the last documented commit", safe page writes and the strict build.
bash
claude mcp add snapdoczilla -- uvx snapdoczilla-mcp
Claude Desktop, Cursor and other mcpServers clients:
Needs uv, git and bash (on Windows: Git for Windows). The server does not read your code: your client does with its own file tools (in Claude Desktop, add a filesystem server). Use the MCP server or the skill in a given agent, not both.
Tool
What it does
snapdoczilla_status
Installed? Areas, commits not yet documented, pages, next ADR number, suggested next step
snapdoczilla_install
Scaffolds documentation/, writes areas.conf, downloads Mermaid once
snapdoczilla_get_rules
The rules the pages must follow (language, never invent, embed real code)
snapdoczilla_changes_since_sync
Files and commits of an area since its last documented commit
snapdoczilla_write_page
Writes one page, confined to documentation/source/, and adds it to nav
snapdoczilla_build_html
Strict MkDocs build; a failed build keeps the previous site
snapdoczilla_mark_synced
Records HEAD as the last documented commit of an area
It also exposes the prompt document_project. Then just ask: "Document this project".
SnapDoczilla: step by step
What you get: a documentation/ folder in your repo. Anyone opens documentation/html/index.html with a double click: search and diagrams included, no install, no internet. Docs can't drift from code: pages embed the real source files on every build. See a full result in examples/shop (an Express API + React app; download the repo and open examples/shop/documentation/html/index.html).
Scope. It documents what lives in the repo, for any stack: Spring, Node (Express/Nest), Python (FastAPI/Django/Flask), .NET, Go, PHP, Ruby; Vue, React, Angular, Svelte.
Backend
Frontend
Any project
Architecture with Mermaid flows, API map by resource, integrations, data model
Screens/routes, src/ structure, state, component pages (API + real usage + real code)
Overview, getting started, ADRs
It does not take screenshots, run live demos, host anything or replace your OpenAPI/Swagger. Docs are written in the language you choose (English by default).
Requirements. To read: a browser. To generate/update: Git (with bash; on Windows, Git for Windows), Python 3 and an agent.
The agent detects your areas (e.g. back=backend/, front=frontend/), installs the scaffolding, writes the first pages from your real code, builds the site and checks the diagrams. It never commits.
3. Read it
Open documentation/html/index.html.
4. Review and commit
Check git diff, fix anything flagged as to be confirmed and commit documentation/ (including html/, so readers need nothing installed).
5. Keep it updated (any dev, one command)
bash
./documentation/update.sh # all areas
./documentation/update.sh --front # one area
./documentation/update.sh --html-only # rebuild the HTML only, after editing .md by hand
On Windows, double-click documentation\update.cmd. Only what changed since the last sync goes to the agent. A pre-push hook reminds you (never blocks) when code changed without docs.
Claude Code is the default. Using another agent? Set DOCS_LLM:
Agent
DOCS_LLM
Codex CLI
codex exec --full-auto
OpenCode
opencode run
Gemini CLI
gemini --yolo -p
Or ask your agent "update the docs" inside a session. That works with every agent, Antigravity included.
6. Document a component
code
Add a SnapDoczilla page for the Button component
You get what it is, how it works, props/events/slots, a real usage example from your app and the real source code.
Architecture page, dark mode, diagram rendered offline.
SnapDoczilla or Docusaurus?
They solve different problems. Docusaurus is an engine to build a site you write by hand. SnapDoczilla is a workflow: your agent writes the docs from the code and keeps them in sync.
Docusaurus
SnapDoczilla
Who writes
You
Your agent, from the real code
Staying current
Manual
Incremental, per git diff; code embedded from the real files
Read without a server
No
Yes, double-click
Stack
Node, React, MDX
Python only to build; nothing to read
Versions, multi-locale, blog, plugins
Yes
No
Pick Docusaurus for a public product site with versions and many languages. Pick SnapDoczilla to make any codebase understandable to your team, today, and keep it that way.
Publish on the web (optional)
documentation/html/ is a static site. To serve it with GitHub Pages, add .github/workflows/docs.yml to your repo and set Settings → Pages → Source to GitHub Actions:
documentation/
├── source/ # editable Markdown (the agent writes here)
│ └── assets/ # local mermaid.min.js + diagrams.js
├── html/ # generated site (committed: zero-setup reading)
├── mkdocs.yml
├── areas.conf # code areas: name=path
├── AGENT-RULES.md # rules for the agent (language, never invent, format)
├── AGENT-RULES-<area>.md # per-area rules (e.g. component pages)
├── update.sh / .cmd # the only command you need
├── requirements.txt # mkdocs<2, mkdocs-material<10
└── .last-sync-<area> # last documented commit per area
.githooks/pre-push # reminder only, never blocks
Adding a new skill to this repo
Create skills/<skill-name>/SKILL.md with name and description frontmatter (the description decides when agents trigger it). Helpers go next to it: scripts/, assets/, references/.
Claude Code: add a plugin for it in .claude-plugin/marketplace.json (one plugin per skill, all under the juliovc marketplace). When there are two or more, give each one its own folder with a .claude-plugin/plugin.json and point source at it.
Check: claude plugin validate ., npx skills@latest add . --list and bash tests/smoke.sh (CI runs it on every push and PR).
Issues and PRs welcome. Run bash tests/smoke.sh before opening a PR. Ideas for SnapDoczilla: a no-Python option, per-framework component templates, detecting drifted line-range snippets.
Skills para agentes que uso en proyectos reales. Pequeñas, legibles y fáciles de adaptar. Siguen el formato abierto Agent Skills (SKILL.md): funcionan primero en Claude Code y también en Codex, OpenCode, Antigravity, Gemini CLI y otros agentes.
Documentación para cualquier backend y cualquier frontend como un sitio HTML offline dentro de tu repo. Cualquier persona la lee con doble clic y cualquier dev la actualiza con un comando. Diagramas Mermaid, mapa de la API, ADRs y fichas de componentes al estilo react.dev con código real y uso real.
Ficha de componente generada por SnapDoczilla: uso y código reales, tomados del repo en cada build.
Instalación (30 segundos)
Dos opciones. El plugin de Claude Code es un paquete administrado que se actualiza cuando publico. skills.sh copia archivos editables en tu proyecto, para cualquier agente. Elige una: si instalas las dos, tendrás cada skill duplicada.
Claude Code (plugin)
bash
claude plugin marketplace add julvc/skills
claude plugin install snapdoczilla@juliovc
Se invoca con /snapdoczilla:snapdoczilla, o simplemente pidiendo "documenta este proyecto": Claude la activa solo.
Codex, OpenCode, Antigravity, Gemini CLI y otros agentes
bash
npx skills@latest add julvc/skills
Elige las skills y los agentes donde instalarlas. O instala una skill en un agente sin preguntas:
bash
npx skills@latest add julvc/skills --skill snapdoczilla -a codex -y
Ids de agentes: claude-code, codex, opencode, antigravity, gemini-cli. Agrega -g para instalarla de forma global en vez de solo en el proyecto actual.
Manual (sin herramientas)
Copia skills/snapdoczilla/ en la carpeta de skills de tu agente:
Agente
Proyecto
Global
Claude Code
.claude/skills/
~/.claude/skills/
Codex
.agents/skills/
~/.codex/skills/
OpenCode
.agents/skills/
~/.config/opencode/skills/
Antigravity
.agents/skills/
~/.gemini/antigravity/skills/
Servidor MCP (Claude Desktop, Cursor y cualquier cliente MCP)
¿Prefieres MCP a las skills, o tu cliente no las soporta? SnapDoczilla también se publica como servidor MCP local (stdio, Python). El agente sigue escribiendo la documentación desde tu código; el servidor hace lo determinista: instalar, "qué cambió desde el último commit documentado", escribir páginas de forma segura y el build estricto.
bash
claude mcp add snapdoczilla -- uvx snapdoczilla-mcp
Claude Desktop, Cursor y otros clientes con mcpServers:
Requiere uv, git y bash (en Windows: Git for Windows). El servidor no lee tu código: lo hace tu cliente con sus propias herramientas de archivos (en Claude Desktop, agrega un servidor de filesystem). En cada agente usa el servidor MCP o la skill, no ambos.
Herramienta
Qué hace
snapdoczilla_status
¿Instalada? Áreas, commits sin documentar, páginas, próximo número de ADR y siguiente paso sugerido
snapdoczilla_install
Crea documentation/, escribe areas.conf y descarga Mermaid una vez
snapdoczilla_get_rules
Las reglas que deben seguir las páginas (idioma, no inventar, código real)
snapdoczilla_changes_since_sync
Archivos y commits de un área desde su último commit documentado
snapdoczilla_write_page
Escribe una página, limitada a documentation/source/, y la agrega al nav
snapdoczilla_build_html
Build estricto de MkDocs; si falla, se conserva el sitio anterior
snapdoczilla_mark_synced
Registra HEAD como último commit documentado de un área
También expone el prompt document_project. Después solo pide: "Documenta este proyecto".
SnapDoczilla: paso a paso
Qué obtienes: una carpeta documentation/ en tu repo. Cualquier persona abre documentation/html/index.html con doble clic: trae búsqueda y diagramas, sin instalar nada y sin internet. La documentación no se desfasa del código, porque las páginas incluyen los archivos fuente reales en cada build. Hay un resultado completo en examples/shop (una API Express + una app React): descarga el repo y abre examples/shop/documentation/html/index.html.
Alcance. Documenta lo que está en el repo, en cualquier stack: Spring, Node (Express/Nest), Python (FastAPI/Django/Flask), .NET, Go, PHP, Ruby; Vue, React, Angular, Svelte.
Backend
Frontend
Cualquier proyecto
Arquitectura con flujos Mermaid, mapa de la API por recurso, integraciones, modelo de datos
Pantallas y rutas, estructura de src/, estado, fichas de componentes (API + uso real + código real)
Resumen, primeros pasos, ADRs
No saca capturas, no hace demos vivas, no publica en ningún servidor y no reemplaza tu OpenAPI/Swagger. La documentación se escribe en el idioma que elijas (inglés por defecto; si le hablas al agente en español, la escribe en español).
Requisitos. Para leer: un navegador. Para generar o actualizar: Git (con bash; en Windows, Git for Windows), Python 3 y un agente.
El agente detecta tus áreas (por ejemplo back=backend/, front=frontend/), instala la estructura, escribe las primeras páginas a partir de tu código real, construye el sitio y revisa los diagramas. Nunca hace commit.
3. Léela
Abre documentation/html/index.html.
4. Revisa y haz commit
Revisa el git diff, corrige lo marcado como por confirmar y haz commit de documentation/. Incluye html/, para que quien la lea no tenga que instalar nada.
5. Mantenla al día (cualquier dev, un comando)
bash
./documentation/update.sh # todas las áreas
./documentation/update.sh --front # una sola área
./documentation/update.sh --html-only # solo regenera el HTML, tras editar los .md a mano
En Windows, doble clic en documentation\update.cmd. Al agente solo le llega lo que cambió desde la última sincronización. Un hook pre-push te avisa (nunca bloquea) cuando hay cambios de código sin documentar.
Por defecto usa Claude Code. ¿Usas otro agente? Define DOCS_LLM:
Agente
DOCS_LLM
Codex CLI
codex exec --full-auto
OpenCode
opencode run
Gemini CLI
gemini --yolo -p
O pídele a tu agente "actualiza la documentación" dentro de una sesión. Funciona con todos, incluido Antigravity.
6. Documenta un componente
code
Agrega una ficha de SnapDoczilla para el componente Boton
Obtienes qué es, cómo funciona, props/eventos/slots, un ejemplo de uso real de tu aplicación y el código fuente real.
¿SnapDoczilla o Docusaurus?
Resuelven problemas distintos. Docusaurus es un motor para construir un sitio que escribes a mano. SnapDoczilla es un flujo de trabajo: tu agente escribe la documentación desde el código y la mantiene sincronizada.
Docusaurus
SnapDoczilla
Quién escribe
Tú
Tu agente, desde el código real
Mantenerla al día
A mano
Incremental, por git diff; el código se incluye desde los archivos reales
Leer sin servidor
No
Sí, con doble clic
Stack
Node, React, MDX
Python solo para construir; nada para leer
Versiones, varios idiomas, blog, plugins
Sí
No
Elige Docusaurus para un sitio público de producto con versiones y varios idiomas. Elige SnapDoczilla para que cualquier código sea entendible para tu equipo, hoy, y siga siéndolo.
Publicar en la web (opcional)
documentation/html/ es un sitio estático. Para servirlo con GitHub Pages, usa el workflow de la sección Publish on the web y configura Settings → Pages → Source en GitHub Actions.
Qué se agrega a tu repo
code
documentation/
├── source/ # Markdown editable (aquí escribe el agente)
│ └── assets/ # mermaid.min.js local + diagrams.js
├── html/ # sitio generado (se commitea: se lee sin instalar nada)
├── mkdocs.yml
├── areas.conf # áreas de código: nombre=ruta
├── AGENT-RULES.md # reglas para el agente (idioma, no inventar, formato)
├── AGENT-RULES-<area>.md # reglas por área (p. ej. fichas de componentes)
├── update.sh / .cmd # el único comando que necesitas
├── requirements.txt # mkdocs<2, mkdocs-material<10
└── .last-sync-<area> # último commit documentado por área
.githooks/pre-push # solo avisa, nunca bloquea
Agregar una skill nueva a este repo
Crea skills/<nombre-skill>/SKILL.md con el frontmatter name y description (la descripción define cuándo la activan los agentes). Los archivos de apoyo van al lado: scripts/, assets/, references/.
Claude Code: agrega un plugin para ella en .claude-plugin/marketplace.json (un plugin por skill, todos bajo el marketplace juliovc). Cuando haya dos o más, dale a cada una su propia carpeta con un .claude-plugin/plugin.json y apunta source a esa carpeta.
Verifica: claude plugin validate ., npx skills@latest add . --list y bash tests/smoke.sh (el CI la corre en cada push y PR).
Agrega una fila a la tabla de Skills, en los dos idiomas.
Contribuir
Issues y PR son bienvenidos. Corre bash tests/smoke.sh antes de abrir un PR. Ideas para SnapDoczilla: una opción sin Python, plantillas de fichas por framework y detectar snippets con rangos de líneas desfasados.
