SnapDoczilla

Julio Varas 的技能

English · Español

我在真实项目中使用的 Agent 技能。小巧、易读、易于调整。它们遵循开放的 Agent Skills 格式（SKILL.md），因此首先适用于 Claude Code，也适用于 Codex、OpenCode、Antigravity、Gemini CLI 和其他 Agent。

技能

SnapDoczilla 生成的组件页面：每次构建时都会从仓库中提取真实用法和真实源代码。

安装（30 秒即可完成）

有两种方式。Claude Code 插件是一个托管套件，会在我发布更新时自动更新。skills.sh 会将可编辑文件复制到你的项目中，适用于任何 Agent。任选一种：两种都安装会让每项技能重复两份。

claude plugin marketplace add julvc/skills
claude 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 而非技能，或者你的客户端不支持技能？SnapDoczilla 还提供本地 MCP 服务（stdio，Python）。Agent 仍会根据你的代码编写文档；服务负责确定性操作：安装、“自上次记录的提交以来有哪些变更”、安全地写入页面以及严格构建。

claude mcp add snapdoczilla -- uvx snapdoczilla-mcp

Claude Desktop、Cursor 和其他 mcpServers 客户端：

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

Codex CLI（~/.codex/config.toml）：

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

需要 uv、git 和 bash（Windows 上需要 Git for Windows）。服务不会读取你的代码：客户端会使用自己的文件工具读取（在 Claude Desktop 中，请添加一个文件系统服务）。在同一个 Agent 中使用 MCP 服务或技能，不要同时使用两者。

它还提供提示词 document_project。然后只需提出请求：“为这个项目编写文档”。

SnapDoczilla：分步指南

你将获得： 仓库中的 documentation/ 文件夹。任何人双击打开 documentation/html/index.html 即可查看：包含搜索和图表，无需安装，也无需联网。文档不会与代码脱节：每次构建时，页面都会嵌入真实源文件。完整示例见 examples/shop（一个 Express API 和 React 应用；下载仓库并打开 examples/shop/documentation/html/index.html）。

范围。 它可以为任何技术栈记录仓库中的内容：Spring、Node（Express/Nest）、Python（FastAPI/Django/Flask）、.NET、Go、PHP、Ruby；Vue、React、Angular、Svelte。

它不会截图、运行实时演示、托管任何内容，也不会替代你的 OpenAPI/Swagger。文档会使用你选择的语言编写（默认为英语）。

要求。 阅读文档：需要浏览器。生成/更新文档：需要 Git（含 bash；Windows 上需要 Git for Windows）、Python 3 和一个 Agent。

1. 安装技能

参见安装。

2. 在仓库中向你的 Agent 提出请求

Document this project

Agent 会检测你的区域（例如 back=backend/、front=frontend/），安装脚手架，根据你的真实代码编写首批页面，构建网站并检查图表。它绝不会提交更改。

3. 阅读文档

打开 documentation/html/index.html。

4. 审查并提交

检查 git diff，修正所有标记为待确认的内容，并提交 documentation/（包括 html/，这样读者就无需安装任何东西）。

5. 保持文档更新（任何开发者，只需一条命令）

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

在 Windows 上，双击 documentation\update.cmd。只有自上次同步以来发生变化的内容才会发送给 Agent。代码变更但文档未更新时，pre-push 钩子会提醒你（但不会阻止操作）。

Claude Code 是默认选项。使用其他 Agent？设置 DOCS_LLM：

或者在会话中让你的 Agent “更新文档”。所有 Agent 都支持，包括 Antigravity。

6. 编写组件文档

Add a SnapDoczilla page for the Button component

你将了解组件的用途、工作方式、props/events/slots、来自应用的真实用法示例以及真实源代码。

7. 在 CMMI 环境下工作？使用 cmmi 配置

Document this project with SnapDoczilla using the CMMI profile

工作流相同，另外还会生成一个过程证据页面，将 CMMI 实践领域（TS、DAR、PI、RDM、VV、PR、CM、PQA、OT、PAD）映射到仓库中的证据；生成一个 需求 → 代码 → 测试 → 页面 可追溯性矩阵，以及每个发布标签对应的基线表。ADR 遵循 DAR（标准 + 替代方案）。需求 ID 仅取自真实提交、分支或 issue。文档可支持评估，但绝不会声称符合标准。脚本：install.sh <repo> "<Name>" <lang> cmmi。MCP：snapdoczilla_install，参数为 profile: "cmmi"。

8. 需要用户手册？在任何配置下都可以添加

Write the user manual for this app with SnapDoczilla

为应用使用者添加用户手册部分，包括需求、入门步骤、界面地图，以及每个功能对应的页面。页面包含编号步骤、准确的按钮和字段标签、预期结果，以及根据 UI 代码中的真实消息生成的 消息 → 原因 → 处理方法 表格。截图位置会保留占位符（img/<function>-NN.png），供人工拍摄后填入。使用 cmmi 配置时，手册也会作为 OT/VV 证据引用。脚本：add-manual.sh <repo>。MCP：snapdoczilla_add_manual。

架构页面，深色模式，图表离线渲染。

SnapDoczilla 还是 Docusaurus？

它们解决的是不同的问题。Docusaurus 是一个用于构建手写网站的引擎。SnapDoczilla 是一种工作流：由你的 Agent 根据代码编写文档，并保持文档与代码同步。

如果你需要一个支持多版本和多语言的公共产品网站，请选择 Docusaurus。如果你想让团队今天就能看懂任意代码库，并让文档始终保持清晰，请选择 SnapDoczilla。

发布到 Web（可选）

documentation/html/ 是一个静态网站。若要通过 GitHub Pages 提供服务，请在仓库中添加 .github/workflows/docs.yml，并将 设置 → Pages → 来源 设置为 GitHub Actions：

name: docs
on:
  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

仓库中会添加哪些内容

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

向此仓库添加新技能

1. 创建 skills/<skill-name>/SKILL.md，并添加 name 和 description 前置元数据（description 决定 Agent 何时触发该技能）。辅助文件放在同级目录：scripts/、assets/、references/。
2. Claude Code：在 .claude-plugin/marketplace.json 中为其添加插件（每个技能一个插件，全部归属 juliovc marketplace）。当有两个或更多插件时，为每个插件创建单独的文件夹，其中包含 .claude-plugin/plugin.json，并将 source 指向该文件夹。
3. 检查：运行 claude plugin validate .、npx skills@latest add . --list 和 bash tests/smoke.sh（CI 会在每次推送和 PR 时运行该检查）。
4. 在 Skills 表格中添加一行，并同步更新两种语言的表格。

贡献

欢迎提交 Issues 和 PR。提交 PR 前，请运行 bash tests/smoke.sh。SnapDoczilla 的改进想法：提供不依赖 Python 的选项、按框架提供组件模板、检测行范围代码片段是否已过时。

许可证

LICENSE © Julio Varas

西班牙语

English · 西班牙语

面向我在真实项目中使用的 Agent 的 Skills。小巧、易读且易于调整。它们遵循开放格式 Agent Skills（SKILL.md）：优先支持 Claude Code，也支持 Codex、OpenCode、Antigravity、Gemini CLI 等其他 Agent。

Skills

SnapDoczilla 生成的组件说明卡片：每次构建都会从仓库中提取真实用法和真实代码。

有两种选择。Claude Code 插件是一个托管包，我发布更新时它会自动更新。skills.sh 会将可编辑文件复制到你的项目中，适用于任何 Agent。任选其一：如果两种都安装，每个 skill 都会重复一份。

claude plugin marketplace add julvc/skills
claude 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 服务（Claude Desktop、Cursor 和任何 MCP 客户端）

更喜欢使用 MCP 而不是 skills，或者你的客户端不支持 skills？SnapDoczilla 也以本地 MCP 服务（stdio、Python）的形式发布。Agent 仍会根据你的代码编写文档；服务负责执行确定性操作：安装、查询“自上次记录的提交以来有哪些变化”、安全地编写页面，以及严格构建。

claude mcp add snapdoczilla -- uvx snapdoczilla-mcp

Claude Desktop、Cursor 和其他使用 mcpServers 的客户端：

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

Codex CLI（~/.codex/config.toml）：

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

需要 uv、git 和 bash（Windows 上需要 Git for Windows）。服务不会读取你的代码：读取代码的是客户端，它会使用自身的文件工具（在 Claude Desktop 中，添加一个 filesystem 服务）。每个 Agent 使用 MCP 服务或 skill，不要两者同时使用。

它还会提供 document_project 提示词。之后只需请求：“为这个项目编写文档”。

SnapDoczilla：分步指南

**你将获得：**你的仓库中会有一个 documentation/ 文件夹。任何人只需双击打开 documentation/html/index.html：其中包含搜索和图表，无需安装任何东西，也无需联网。文档不会与代码脱节，因为每次构建时，页面都会包含真实的源文件。完整示例见 examples/shop（一个 Express API + 一个 React 应用）：下载仓库，然后打开 examples/shop/documentation/html/index.html。

**范围。**可为仓库中的内容生成文档，支持任何技术栈：Spring、Node（Express/Nest）、Python（FastAPI/Django/Flask）、.NET、Go、PHP、Ruby；Vue、React、Angular、Svelte。

不会生成截图、制作实时演示、发布到任何服务，也不会取代你的 OpenAPI/Swagger。文档会使用你选择的语言编写（默认英语；如果你用西班牙语与 Agent 交流，文档就会用西班牙语编写）。

**要求。**阅读：浏览器。生成或更新：Git（需带 bash；Windows 上使用 Git for Windows）、Python 3 和 Agent。

1. 安装 skill

参见安装。

2. 在仓库中向 Agent 提出请求

Documenta este proyecto

Agent 会识别你的区域（例如 back=backend/、front=frontend/），安装目录结构，根据真实代码编写首批页面，构建站点并检查图表。它绝不会提交 commit。

3. 阅读文档

打开 documentation/html/index.html。

4. 检查并提交 commit

检查 git diff，修正标记为待确认的内容，然后提交 documentation/。请包含 html/，这样读者就无需安装任何东西。

5. 保持文档最新（任何开发者都可执行，一个命令）

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

在 Windows 上，双击 documentation\update.cmd。Agent 只会收到自上次同步以来发生变化的内容。pre-push hook 会提醒你存在尚未记录的代码变更（但绝不会阻止操作）。

默认使用 Claude Code。使用其他 Agent？请设置 DOCS_LLM：

也可以在会话中向 Agent 发送*"更新文档"*。所有 Agent 都适用，包括 Antigravity。

6. 为组件编写文档

Agrega una ficha de SnapDoczilla para el componente Boton

你将获得组件的说明、工作原理、props/events/slots、应用中的实际用法示例以及真实源代码。

7. 使用 CMMI？请使用 cmmi 配置文件

Documenta este proyecto con SnapDoczilla usando el perfil CMMI

沿用相同的工作流，另加一个过程证据页面，将 CMMI 的实践领域（TS、DAR、PI、RDM、VV、PR、CM、PQA、OT、PAD）映射到仓库中的证据；还包括一张需求 → 代码 → 测试 → 页面的追溯矩阵，以及一张按发布 tag 列出的基线表。ADR 遵循 DAR（标准 + 备选方案）。需求 ID 仅来自真实的 commit、分支或 issue。文档可为评估提供支持，但绝不声明合规。脚本：install.sh <repo> "<Nombre>" <lang> cmmi。MCP：snapdoczilla_install，参数为 profile: "cmmi"。

8. 需要用户手册吗？将它添加到任意配置中

Escribe el manual de usuario de esta aplicación con SnapDoczilla

添加 用户手册 一节，供应用使用者查阅：列出要求、入门步骤、屏幕导航图，以及每项功能对应的页面，其中包含编号步骤、按钮和字段的准确名称、预期结果，以及根据界面代码中的实际消息构建的 消息 → 原因 → 处理方法 表格。截图会以占位符（img/<funcion>-NN.png）的形式保留，供他人拍摄。使用 cmmi 配置时，手册也会作为 OT/VV 证据引用。脚本：add-manual.sh <repo>。MCP：snapdoczilla_add_manual。

SnapDoczilla 还是 Docusaurus？

它们解决的是不同的问题。Docusaurus 是一个用来构建手写网站的引擎。SnapDoczilla 则是一套工作流：由 Agent 根据代码编写文档，并让文档与代码保持同步。

如果要构建支持多个版本和多种语言的公开产品网站，请选择 Docusaurus。如果希望团队今天就能理解任何代码，并且今后也能持续理解，请选择 SnapDoczilla。

发布到 Web（可选）

documentation/html/ 是一个静态网站。要通过 GitHub Pages 发布，请使用 在 Web 上发布 一节中的工作流，并将 Settings → Pages → Source 设置为 GitHub Actions。

添加到仓库的内容

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

向此仓库添加新技能

1. 创建 skills/<nombre-skill>/SKILL.md，并添加 name 和 description frontmatter（描述决定 Agent 在何时启用该技能）。支持文件放在同一目录下：scripts/、assets/、references/。
2. Claude Code：在 .claude-plugin/marketplace.json 中为该技能添加一个插件（每个技能一个插件，全部置于 juliovc marketplace 下）。有两个或更多技能时，为每个技能创建单独的文件夹，其中包含 .claude-plugin/plugin.json，并将 source 指向该文件夹。
3. 验证：运行 claude plugin validate .、npx skills@latest add . --list 和 bash tests/smoke.sh（CI 会在每次 push 和 PR 时运行该脚本）。
4. 在 技能 表格中添加一行，并同时填写两种语言的内容。

贡献

欢迎提交 Issues 和 PR。提交 PR 前，请运行 bash tests/smoke.sh。SnapDoczilla 的改进建议：提供无需 Python 的选项、针对各框架的文档模板，以及检测行号范围已过时的代码片段。

许可证

LICENSE © Julio Varas