SnapDoczilla

Skills by Julio Varas

[skills.sh] [smoke]

English · Español

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.

Skills

[SnapDoczilla component page: real usage example and real source code]
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 plugin marketplace add julvc/skillsclaude plugin install snapdoczilla@juliovc

/plugin marketplace add julvc/skills/plugin install snapdoczilla@juliovc

npx skills@latest add julvc/skills

npx skills@latest add julvc/skills --skill snapdoczilla -a codex -y

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.

claude mcp add snapdoczilla -- uvx snapdoczilla-mcp

Claude Desktop, Cursor and other mcpServers clients:

{  "mcpServers": {    "snapdoczilla": { "command": "uvx", "args": ["snapdoczilla-mcp"] }  }}

Codex CLI (~/.codex/config.toml):

[mcp_servers.snapdoczilla]command = "uvx"args = ["snapdoczilla-mcp"]

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.

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.

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.

1. Install the skill

See Installation.

2. Ask your agent, inside your repo

Document this project

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)

./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:

Or ask your agent "update the docs" inside a session. That works with every agent, Antigravity included.

6. Document a component

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 in dark mode with a Mermaid diagram]
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.

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:

name: docson:  push:    branches: [main]    paths: [documentation/html/**]permissions: { contents: read, pages: write, id-token: write }jobs:  deploy:    runs-on: ubuntu-latest    environment: github-pages    steps:      - uses: actions/checkout@v4      - uses: actions/upload-pages-artifact@v3        with: { path: documentation/html }      - uses: actions/deploy-pages@v4

What gets added to your repo

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

1. 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/.
2. 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.
3. Check: claude plugin validate ., npx skills@latest add . --list and bash tests/smoke.sh (CI runs it on every push and PR).
4. Add a row to the Skills table, in both languages.

Contributing

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.

License

LICENSE © Julio Varas

Español

English · Español

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.

Skills

[Ficha de componente generada por SnapDoczilla: uso real y código 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 plugin marketplace add julvc/skillsclaude plugin install snapdoczilla@juliovc

/plugin marketplace add julvc/skills/plugin install snapdoczilla@juliovc

npx skills@latest add julvc/skills

npx skills@latest add julvc/skills --skill snapdoczilla -a codex -y

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.

claude mcp add snapdoczilla -- uvx snapdoczilla-mcp

Claude Desktop, Cursor y otros clientes con mcpServers:

{  "mcpServers": {    "snapdoczilla": { "command": "uvx", "args": ["snapdoczilla-mcp"] }  }}

Codex CLI (~/.codex/config.toml):

[mcp_servers.snapdoczilla]command = "uvx"args = ["snapdoczilla-mcp"]

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.

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.

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.

1. Instala la skill

Ver Instalación.

2. Pídeselo a tu agente, dentro de tu repo

Documenta este proyecto

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)

./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:

O pídele a tu agente "actualiza la documentación" dentro de una sesión. Funciona con todos, incluido Antigravity.

6. Documenta un componente

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.

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

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

1. 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/.
2. 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.
3. Verifica: claude plugin validate ., npx skills@latest add . --list y bash tests/smoke.sh (el CI la corre en cada push y PR).
4. 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.

Licencia

LICENSE © Julio Varas