An agent skill that turns codebases into verifiable, interactive system maps
Archify is an agent skill that turns a system description or an entire repository into an interactive technical map. It supports five diagram types—architecture, workflow, sequence, data-flow, and lifecycle—and produces a single self-contained HTML file with built-in navigation, dark/light themes, finite motion, and exports to PNG, SVG, WebM, and 1200×630 share cards. Under the hood it uses a typed JSON IR as the source of truth, runs validation before delivery, and returns machine-readable repair receipts on failure. It also supports Before/Delta/After snapshots for architecture review. Designed for Raven, Cursor, Claude Code, Codex CLI, and OpenCode, it suits engineers and doc writers who want verifiable, shareable visualizations without hand-drawing.
Archify is an agent skill that turns a codebase or a system description into a polished, interactive system map directly in chat. It works with Raven, Cursor, Claude Code, Codex CLI, and OpenCode. Instead of pasting a diagram into a doc, you ask your agent to produce a shareable, self-contained HTML map that can be opened, presented, and inspected.
Archify 是一个 agent skill（代理技能），你可以在聊天中直接把一段系统描述或一个仓库变成一份精良的交互式系统地图。它支持 Raven、Cursor、Claude Code、Codex CLI 和 OpenCode。你不需要把图“粘贴”进文档，只要让 agent 生成一个可分享、单文件的 HTML 地图，随时打开、演示、检视。
Architecture diagrams in wikis and PRs go stale quickly, and hand-drawn boxes often drift from the code. Generic auto-layout tools can place nodes, but they rarely encode architectural judgment. Archify approaches this by making the agent responsible for hierarchy, spacing, routes, and emphasis, and by validating every artifact before it reaches the team. The output is not a “picture of the code”; it is a checked map with typed JSON IR underneath.
Wiki 和 PR 里的架构图总是很快过时，手绘的方框也常常和代码脱节。通用自动布局工具能摆放节点，却谈不上架构判断。Archify 的做法是：让 agent 负责层级、间距、路径和重点；并且在每份产物送到团队眼前之前先做验证。它产出的不是“代码的示意图”，而是一份带有类型化 JSON IR 底座、经过校验的地图。
Archify bakes trust into the delivery process. Before a showcase artifact replaces the last known good output, schema, layout, HTML/SVG, route, and label-to-route clearance checks must all pass. Failures come back as a machine-readable repair receipt: stable rule codes, the exact subject, measured evidence, and a list of supported fixes, instead of a Node stack trace or a random retry. Nodes that cite source evidence are marked SRC n and open Git-verified files at a pinned commit; ordinary artifacts stay source-free. An optional preview loop keeps the last verified diagram visible while a new version is being worked on.
Archify 把“可信”内建到交付流程里。一份展示级产物在替换上一份已知良好输出之前，必须先通过 schema、布局、HTML/SVG、路由以及标签到路由间距等检查。失败时返回的不是 Node 堆栈或盲目重试，而是一张机器可读的“修复收据”：稳定规则码、具体对象、测得证据、以及仅允许的修复手段。引用源码证据的节点会标记为 SRC n，并打开锁定在某个提交上的 Git 验证文件；普通产物则不带源码来源。可选的 preview 循环会在新版本生成期间，保持上一份已验证图继续可见。
Archify offers five diagram types. Architecture covers components, services, storage, and trust boundaries; Workflow focuses on CI/CD, approvals, and runbooks; Sequence walks through API calls and cache fallbacks; Data Flow maps pipelines, lineage, and PII; Lifecycle separates progress, waits, retries, and terminal outcomes. For design or PR review, Architecture Delta compares validated Before / Delta / After snapshots with a machine receipt. Four visual presets and dark/light themes are available, and the agent can accept refinement requests like “add Redis” or “highlight the rollback path” without losing the rest of the picture.
Archify 提供五种图类型：Architecture（架构）覆盖组件、服务、存储与信任边界；Workflow（工作流）聚焦 CI/CD、审批和 runbook；Sequence（时序）走查 API 调用与缓存回退；Data Flow（数据流）描述管道、血缘与 PII；Lifecycle（生命周期）区分进度、等待、重试与终态。做设计或 PR 评审时，Architecture Delta 会带一份机器收据比较校验过的 Before / Delta / After 快照。还有四种视觉预设和明暗主题。你可以继续下指令，比如“加 Redis”或“高亮回滚路径”，agent 会在不破坏其余结构的前提下迭代。
The pipeline has five steps. Generate: the agent writes typed JSON IR from your description. Validate: bundled validators and layout rules check the source; failures identify the exact local repair in JSON. Preview (optional): a loopback-only desktop session watches one source and reloads only verified revisions. Deliver: a same-directory candidate is rendered and checked; only a passing artifact atomically replaces the target. Iterate: the agent updates the source while unrelated structure stays stable. The CLI exposes these as doctor, demo, guide, validate, preview, and deliver commands; guide can even recommend a diagram type from a natural-language request.
流水线分五步。生成（Generate）：agent 根据你的描述写出类型化 JSON IR。校验（Validate）：内置校验器和布局规则检查来源，失败时用 JSON 指出可精确修复的位置。预览（Preview，可省略）：一个只监听 loopback 的桌面会话监视单个来源文件，只重载通过校验的版本。交付（Deliver）：在同一目录渲染并检查候选文件，只有通过的产物会原子地替换目标文件。迭代（Iterate）：agent 更新来源，同时无关结构保持稳定。CLI 对应命令是 doctor、demo、guide、validate、preview 和 deliver；其中 guide 可以根据自然语言问题推荐图类型。
Install globally with npx skills add tt-a1i/archify -g. For a non-interactive Cursor install, use npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes. To try without installing: npx skills use tt-a1i/archify@archify --agent codex. Then ask your agent, for example: “Use archify to map this repository's runtime architecture.” A bounded prompt such as “Analyze this repository, then use archify to create a high-level runtime architecture diagram” with 8–12 core components and a primary path keeps the result focused. You can also test the CLI directly with node archify/bin/archify.mjs guide "Show an API request with Redis cache miss".
全局安装一行搞定：npx skills add tt-a1i/archify -g。用 Cursor 且希望非交互安装：npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes。不想安装想先试：npx skills use tt-a1i/archify@archify --agent codex。然后让你的 agent 做，例如：“Use archify to map this repository's runtime architecture.” 如果希望结果聚焦，可以给一个限定范围的要求，比如“分析这个仓库，然后用 archify 画一张高层运行时架构图”，并指定 8–12 个核心组件、一条主路径。也可以直接跑 CLI 试：node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"。
The result is a single HTML file with a complete viewer inside. Press ? for the factual Diagram Guide, / to focus a semantic node, R or PATH to probe a directed route, L to compare semantic roles, M for an overview radar, P to play a guided story, F for presentation stage, and S/T/E for style, theme, and export. Exports include PNG, SVG, WebM, and a canonical 1200×630 share card; after tracing a route or reach, dedicated Route Share Card and Reach Share Card exports preserve that exact reading. Stable links can restore focused views with hash parameters.
产物是单个 HTML 文件，自带完整查看器。快捷键很齐全：? 打开图例指南，/ 聚焦语义节点，R 或 PATH 探测一条有向路由，L 比较语义角色，M 打开全局缩略图，P 播放引导故事，F 进入演示模式，S/T/E 分别切换风格、主题和导出。导出支持 PNG、SVG、WebM，以及标准 1200×630 分享卡片；在追踪了某条路由或可达范围后，还有专用的 Route Share Card 和 Reach Share Card 导出，把当时的解读完整带出去。稳定链接也能通过 hash 参数恢复聚焦视图。
Archify is not a general-purpose drawing editor or a Mermaid theme. Automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing are intentionally out of scope. It is best used when you want a communication artifact from a description or codebase, with validation and source traceability. For production deployment review, an engineering profile can fail closed when ownership, region, or boundary facts are missing—but it validates authored facts, not live infrastructure. If you need live, continuously updated topology from running systems, or free-form visual editing, this tool is not the right fit.
Archify 不是通用画图编辑器，也不是 Mermaid 主题。自动 Mermaid 解析、通用自动布局、托管分享、所见即所得编辑，都属于刻意不做的事。它最适合的场景是：从描述或代码库生成一份面向沟通的产物，并希望它经过校验、源头可溯。做生产部署评审时，可选的工程配置文件在缺少归属、区域或边界事实时会直接拒绝通过；但注意它校验的是作者声明的事实，而不是实时基础设施。如果你需要来自运行系统的实时、持续更新的拓扑，或者需要自由画布式编辑，那它并不合适。