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

soia-dev-archify-diagrams

Design & creation

View repository

Updated 10-16 08:09

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

The customer wants The skill will do The customer can see
Complete the work covered by this skill Read the user request, necessary context, and this skill's main workflow, 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 Installation commands, application URLs, configuration paths, or questions that require 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. The Agent first determines whether this skill applies, then checks dependencies, configuration, permissions, and risky actions.
  3. For actions that can be dry-run or previewed, provide a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, ask the customer for confirmation first.
  4. After execution, verify the real output; do not substitute "looks successful" for evidence.
  5. The final reply must give the customer a visible summary: what was done, log summary, file changes, issues, and next steps.

Dependencies and installation

Install this skill (single skill):

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

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-dev/soia-dev-archify-diagrams/config.yml
SOIA_DEV_ARCHIFY_DIAGRAMS_CONFIG_FILE=<custom-config-path>
  • If this skill does not require private configuration, you may skip creating config.yml。
  • If an API key, cookie, session, provider home, or local path is required, it may only be placed in a private config.yml, process environment, or the provider's own login state; it must not be written into the repository, vault body, or logs.
  • Strong dependencies, optional dependencies, and third-party skill relationships must be based on this SKILL.md and the subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly written, add the description first or ask the customer, and do not guess.
  • Third-party skills may only declare dependencies and installation methods; do not directly modify third-party skill files.

Output directory contract

The output directory is resolved in the following priority order:

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

--output-dir It 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 output directory.

Explicitly specify the directory by delivery scenario:

  • Repository 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 a temporary intermediate file in the output directory, and the HTML will be deleted after the PNG is successfully exported; 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. The minimum receipt format is:

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

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