soia-dev-archify-diagrams

Use this skill to turn architecture and process explanations into polished Archify diagrams with maintainable JSON source files and README-friendly PNG previews.

The skill owns the reusable workflow and helper scripts. Archify itself remains an external renderer.

soia-dev-archify-diagrams/
├── SKILL.md
├── scripts/
│   ├── render-archify-diagrams.mjs
│   └── export-archify-previews.mjs
└── assets/examples/
    ├── minimal-architecture.architecture.json
    ├── minimal-dataflow.dataflow.json
    └── minimal-workflow.workflow.json

客户可读说明

这个技能可以做什么

Draw, improve, validate, or publish Archify architecture / data-flow / sequence / lifecycle diagrams with JSON IR and PNG previews

客户想要	技能会做	客户能看到
完成本技能覆盖的工作	读取用户请求、必要上下文和本技能正文流程，执行最小可靠步骤	客户会看到执行计划、命令输出摘要、代码/文档变更、验证结果和风险说明。
缺少依赖、权限、配置或 key	停止需要外部状态的动作，明确指出缺什么	安装命令、申请地址、配置路径或需要客户确认的问题
执行完成	汇总成功、跳过、失败、文件变更和验证结果	一段可复制进工单/日志的完成回执

客户如何使用

用自然语言说明目标，并提供必要输入：文件、URL、repo、workspace、proposal、vault 或平台账号状态。
能 dry-run 或预览的动作先给预览；涉及删除、覆盖、发送、发布、写远端状态时先征求客户确认。

依赖与安装

安装（推荐：装整个领域插件，一次装好本仓全部技能）：

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-dev-design@soia

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

npx skills add soia-team/soia-open-dev-design-skills -g -a '*' -s soia-dev-archify-diagrams -y

配置约定：

~/.config/soia-skills/soia-dev-archify-diagrams/config.yml
SOIA_DEV_ARCHIFY_DIAGRAMS_CONFIG_FILE=<custom-config-path>

如果本技能不需要私有配置，可以不创建 config.yml。
如果需要 API key、cookie、session、provider home 或本机路径，只能放进私有 config.yml、进程环境或 provider 自己的登录态里，不能写进仓库、vault 正文或日志。
第三方 skill 只能声明依赖和安装方式，不直接修改第三方 skill 文件。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

输出目录契约

输出目录按以下优先级解析：

命令行 --output-dir <path>；
进程环境变量或私有配置中的 ARCHIFYOUTPUTDIR；
安全默认值 ~/Downloads/soia-dev-archify-diagrams/。

--output-dir 可以是绝对路径或相对当前工作目录的路径。技能不会把用户交付物默认写入当前目录，也不会把 ~/.soia/workspaces/ 当作通用输出目录。

按交付场景显式指定目录：

仓库 README / 文档：--output-dir assets/diagrams；
已明确确认的 SOIA proposal：--output-dir <workspace>/proposals/<proposal-id>/design/diagrams；
普通临时预览或未指定项目目录：使用上述 ~/Downloads/soia-dev-archify-diagrams/ 默认值。

使用 --png-only 时，HTML 只作为输出目录内的临时中间文件，PNG 导出成功后会删除 HTML；不使用 --png-only 时保留 HTML，便于浏览器预览和排错。

日志与完成回执

每次执行都要让客户看见过程和结果。最低回执格式：

完成：<一句话说明本次完成了什么>。

日志摘要：
- started: <检查到的输入/配置/依赖，不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化：
- <绝对路径或“未改动文件”>

验证：
- <运行过的检查、命令或人工核对点>

问题与下一步：
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>

Choose Diagram Type

User intent	Archify type	JSON suffix
System components, repos, services, local directories, runtime boundaries	`architecture`	`.architecture.json`
Installation paths, data movement, lineage, where files flow	`dataflow`	`.dataflow.json`
Maintenance process, approval flow, tool-call flow, CI/release steps	`workflow`	`.workflow.json`
Who calls whom over time, request/response, fallback behavior	`sequence`	`.sequence.json`
State/status transitions, terminal outcomes, retry/cancel paths	`lifecycle`	`.lifecycle.json`

If a rough Mermaid flowchart mixes components and process, choose one story and split the rest into a second diagram.

Diagram Rules

Keep JSON IR as the source of truth.
Generate HTML as a render/check intermediate; with --png-only, delete it after PNG export succeeds.
Commit PNG previews for README-visible diagrams.
Do not commit generated HTML unless the user explicitly asks for interactive diagrams.
Make the main path left-to-right.
Put side concerns in cards, not in long crossing arrows.
Use few edge labels; label only non-obvious boundaries, policy/security paths, or async/batch paths.
Run Archify validate, render, and check before claiming the diagram is done.

Standard Layout

For repository README/docs diagrams, prefer:

assets/diagrams/
├── <slug>.architecture.json
└── <slug>.png

For an explicitly confirmed SOIA proposal, write diagrams under:

<workspace>/proposals/<proposal-id>/design/diagrams/

Do not infer a proposal workspace from the current directory, and do not hardcode a maintainer-specific workspace path in SKILL.md, JSON examples, README files, or scripts. If the caller has not supplied a project destination, use the output-directory contract above.

Setup

Do not copy the Archify upstream source into a skill repository. Use one of these locations at runtime:

Explicit binary: ARCHIFY_BIN=<path-to-archify.mjs>
Command arg: --archify-root <path-to-archify-root>
Explicit root: ARCHIFY_ROOT=<path-to-archify-root>
Installed skill locations:

- .agents/skills/archify (current workspace) - ~/.gemini/antigravity-cli/skills/archify - ~/.agents/skills/archify - ~/.codex/skills/archify - ~/.claude/skills/archify

If Archify is not available, clone it outside the skill repo and point ARCHIFY_ROOT to that checkout:

git clone https://github.com/tt-a1i/archify.git <workspace>/archify
cd <workspace>/archify/archify
npm install

Render Workflow

Render all diagrams in a directory and keep only JSON + PNG:

node skills/soia-dev-archify-diagrams/scripts/render-archify-diagrams.mjs \
  --dir assets/diagrams \
  --output-dir assets/diagrams \
  --png-only \
  --theme light \
  --width 1400 \
  --height 1000 \
  --scale 2

Render one diagram:

node skills/soia-dev-archify-diagrams/scripts/render-archify-diagrams.mjs \
  --file assets/diagrams/system.architecture.json \
  --output-dir assets/diagrams \
  --png-only

The helper:

Finds .architecture.json, .workflow.json, .sequence.json, .dataflow.json, and *.lifecycle.json
Runs archify validate
Runs archify render
Runs archify check
Writes HTML previews to the resolved output directory
With --png-only, exports PNG previews to the same directory and deletes temporary HTML files
Without --output-dir, uses ARCHIFYOUTPUTDIR and then ~/Downloads/soia-dev-archify-diagrams/

README Preview Workflow

GitHub README should use committed PNG previews:

Render Archify HTML.
Export a PNG preview.
Delete the temporary HTML.
Commit JSON source and PNG preview.
Embed the PNG directly.

Use the bundled exporter when HTML already exists:

node skills/soia-dev-archify-diagrams/scripts/export-archify-previews.mjs \
  --dir assets/diagrams \
  --output-dir assets/diagrams \
  --theme light \
  --width 1400 \
  --height 1000 \
  --scale 2

Markdown:

![Diagram](assets/diagrams/example.png)

Centered HTML:

<p align="center">
  <img src="assets/diagrams/example.png" alt="Example architecture diagram" width="100%">
</p>

Minimal JSON Patterns

Start from assets/examples/ when creating new diagrams. Use the suffix to select the renderer:

*.architecture.json
*.dataflow.json
*.workflow.json

Keep examples generic. Do not include personal directories, private repo paths, tokens, cookies, or private workspace names.

Layout Debugging

Archify validation errors are usually actionable. Apply its suggestions directly:

label collision: set labelDy, labelDx, labelAt, or labelSegment
node collision: move row / col, change pos, or reduce size / width
short workflow edge: skip adjacent columns or route through drop / bottom-channel
viewBox overflow: increase meta.viewBox or reduce node count

Do not ignore overlap errors. Fix JSON and re-render.

Output Checklist

Before final response:

JSON IR exists and is ready to commit.
Temporary HTML rendered and passed archify check.
README PNG exists if the diagram should be visible on GitHub.
README-visible diagram HTML was deleted unless explicitly requested.
Markdown links/images resolve locally.
Report the resolved output directory and whether it came from --output-dir, ARCHIFYOUTPUTDIR, or the safe default.
Report which scripts were used and which checks passed.

soia-dev-archify-diagrams

Installation

Stronger alternatives

Similar popular skills

Also in this package

Agent compatibility

Repository health

Skill metadata

Package contents

History

SKILL.md

soia-dev-archify-diagrams

客户可读说明

这个技能可以做什么

客户如何使用

依赖与安装

输出目录契约

日志与完成回执

Choose Diagram Type

Diagram Rules

Standard Layout

Setup

Render Workflow

README Preview Workflow

Minimal JSON Patterns

Layout Debugging

Output Checklist