SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssoia-dev-archify-diagrams

soia-dev-archify-diagrams

Design & creation

View repository

Updated 10-16 08:46

About this skill

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

Customer-readable description

What this skill can do

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

Customer wants Skill will do Customer can see
Complete the work covered by this skill Read the user request, necessary context, and this skill's main-body process, and execute the minimal reliable steps The customer will see the execution plan, command output summary, code/document changes, verification results, and risk notes.
Missing dependencies, permissions, configuration, or key Stop actions that require external state, and clearly state what is missing Install commands, application addresses, configuration paths, or questions requiring customer confirmation
Execution complete Summarize successes, skips, failures, file changes, and verification results A completion receipt that can be copied into a ticket/log

How the customer uses it

  1. Describe the goal in natural language and provide the necessary inputs: files, URLs, repos, workspaces, proposals, vaults, or platform account status.
  2. For actions that can be dry-run or previewed, provide a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, seek customer confirmation first.

Dependencies and installation

Installation (recommended: install the entire domain plugin to install all skills in this repo at once):

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

claude plugin install soia-dev-design@soia

If you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is also installed, the same skill will appear in two indexes and drift separately, so it is recommended to choose one of the two:

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

Configuration conventions:

~/.config/soia-skills/soia-dev-archify-diagrams/config.yml
SOIA_DEV_ARCHIFY_DIAGRAMS_CONFIG_FILE=<custom-config-path>
  • If this skill does not need private configuration, you can skip creating config.yml。
  • If an API key, cookie, session, provider home, or local path is needed, it can only be placed in the private config.yml, the process environment, or the provider's own login state; it must not be written into the repo, vault body, or logs.
  • Third-party skills can only declare dependencies and installation methods; they do not directly modify third-party skill files.

WorkBuddy The loading unit of is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, and it needs to be installed separately, see docs/install/workbuddy.md。

Output directory contract

The output directory is resolved in the following priority order:

  1. Command line --output-dir <path>；
  2. Process environment variable or private configuration ARCHIFY_OUTPUT_DIR；
  3. Safe default ~/Downloads/soia-dev-archify-diagrams/。

--output-dir can be an absolute path or a path relative to the current working directory. The skill will not write user deliverables to the current directory by default, nor will it treat ~/.soia/workspaces/ as a general-purpose output directory.

Explicitly specify the directory according to the delivery scenario:

  • Repo README / documentation:--output-dir assets/diagrams；
  • Explicitly confirmed SOIA proposal:--output-dir <workspace>/proposals/<proposal-id>/design/diagrams；
  • Ordinary temporary preview or unspecified project directory: use the above ~/Downloads/soia-dev-archify-diagrams/ default value.

When using --png-only , HTML is only used as a temporary intermediate file within the output directory, and the HTML will be deleted after PNG export succeeds; when not using --png-only , the HTML is retained for browser preview and troubleshooting.

Logs and completion receipt

Every execution must let the customer see the process and results. Minimum receipt format:

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

日志摘要：
- 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

  1. Keep JSON IR as the source of truth.
  2. Generate HTML as a render/check intermediate; with --png-only, delete it after PNG export succeeds.
  3. Commit PNG previews for README-visible diagrams.
  4. Do not commit generated HTML unless the user explicitly asks for interactive diagrams.
  5. Make the main path left-to-right.
  6. Put side concerns in cards, not in long crossing arrows.
  7. Use few edge labels; label only non-obvious boundaries, policy/security paths, or async/batch paths.
  8. 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:

  1. Explicit binary: ARCHIFY_BIN=<path-to-archify.mjs>
  2. Command arg: --archify-root <path-to-archify-root>
  3. Explicit root: ARCHIFY_ROOT=<path-to-archify-root>
  4. 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 ARCHIFY_OUTPUT_DIR and then ~/Downloads/soia-dev-archify-diagrams/

README Preview Workflow

GitHub README should use committed PNG previews:

  1. Render Archify HTML.
  2. Export a PNG preview.
  3. Delete the temporary HTML.
  4. Commit JSON source and PNG preview.
  5. 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, ARCHIFY_OUTPUT_DIR, or the safe default.
  • Report which scripts were used and which checks passed.