figure-spec
Generate deterministic publication-quality architecture, workflow, and pipeline diagrams from structured JSON (FigureSpec) into editable SVG. Use when user says \"架构图\", \"workflow 图\", \"pipeline 图\", \"确定性矢量图\", \"figure spec\", \"draw architecture\", or needs precise, editable, publication-ready vector diagrams. Preferred over AI illustration for formal architecture/workflow figures.
wanshuiyin · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add wanshuiyin/Auto-claude-code-research-in-sleep --skill figure-spec技能说明
name: figure-spec description: "Generate deterministic publication-quality architecture, workflow, and pipeline diagrams from structured JSON (FigureSpec) into editable SVG. Use when user says "架构图", "workflow 图", "pipeline 图", "确定性矢量图", "figure spec", "draw architecture", or needs precise, editable, publication-ready vector diagrams. Preferred over AI illustration for formal architecture/workflow figures." argument-hint: "[description-of-diagram]" allowed-tools: Bash(*), Read, Write, Edit, mcp__codex__codex
FigureSpec: Deterministic JSON → SVG Figure Generation
Generate publication-quality architecture diagrams, workflow pipelines, audit cascades, and system topology figures as editable SVG vector graphics using a deterministic JSON → SVG renderer.
When to Use This Skill
Use figure-spec for:
- System architecture diagrams (layered, hub-and-spoke, multi-plane)
- Workflow / pipeline figures
- Audit cascade / flow-control diagrams
- Any structured diagram where node positions, connections, and groupings are semantically important
- Figures that need to be edited/tweaked later (SVG is plain text)
- Figures where determinism matters (same spec → same SVG)
Do NOT use for:
- Data plots (bar/line/scatter) — use
/paper-figure - Natural/qualitative illustrations — use
/paper-illustration - Quick state-machine / flowchart — use
/mermaid-diagram(lighter syntax)
Core Properties
- Deterministic: identical FigureSpec JSON always produces identical SVG output (for a fixed renderer version + fonts)
- Editable: SVG output is plain-text, can be post-edited by hand or programmatically
- Validated: renderer enforces schema, rejects malformed specs with clear error messages
- Shape-aware: edge clipping works correctly for rect/rounded/circle/ellipse/diamond
- CJK support: multi-line labels with proper Chinese character width estimation
- No external API: runs fully local, no network, no API keys
Tool Location
Phase 3.1 (Arch C) move: the canonical implementation now lives at
skills/figure-spec/scripts/figure_renderer.py (this SKILL's own
scripts/ subdirectory). A backwards-compatible shim at
tools/figure_renderer.py forwards to the canonical file via
os.execv, so existing users with .aris/tools/figure_renderer.py
or a manually copied tools/figure_renderer.py keep working
unchanged.
Resolve $FIGURE_RENDERER with the hybrid chain (layer 0 prefers the
self-contained location for the owning SKILL; layers 1-4 are the
shared-runtime chain documented in
shared-references/integration-contract.md §2,
Policy A — skill-local gate):
# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).
FIGURE_RENDERER=""
if [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/figure_renderer.py" ]; then
FIGURE_RENDERER="$CLAUDE_SKILL_DIR/scripts/figure_renderer.py"
fi
# Layers 1-4: shared-runtime chain (legacy compatibility + non-CC hosts).
if [ -z "$FIGURE_RENDERER" ]; then
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
FIGURE_RENDERER=".aris/tools/figure_renderer.py"
[ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER="tools/figure_renderer.py"
[ -f "$FIGURE_RENDERER" ] || { [ -n "${ARIS_REPO:-}" ] && FIGURE_RENDERER="$ARIS_REPO/tools/figure_renderer.py"; }
[ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER=""
fi
[ -z "$FIGURE_RENDERER" ] && {
echo "ERROR: figure_renderer.py not resolved (layer 0: \$CLAUDE_SKILL_DIR/scripts/; layers 1-4: .aris/tools/, tools/, \$ARIS_REPO/tools/, \$ARIS_REPO/tools/ via ~/.aris/repo)." >&2
echo " /figure-spec cannot produce SVG output. Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), or copy the helper from \$ARIS_REPO/skills/figure-spec/scripts/." >&2
exit 1
}
Invoke:
python3 "$FIGURE_RENDERER" render <spec.json> --output <out.svg>
python3 "$FIGURE_RENDERER" validate <spec.json>
python3 "$FIGURE_RENDERER" schema
Workflow
Step 1: Understand the Diagram Goal
From $ARGUMENTS (description or path to PAPER_PLAN.md / NARRATIVE_REPORT.md), identify:
- Purpose: architecture, workflow, pipeline, audit cascade, topology?
- Main entities: what are the boxes?
- Relationships: how do they connect? (uses, produces, calls, verifies, chains)
- Grouping: do entities cluster into named regions?
- Hierarchy vs network: stacked layers, left-to-right flow, or central hub?
Step 2: Draft the FigureSpec JSON
Canvas sizing guide:
- Single-column figure: ~500×350 px
- Two-column (full-width): ~900×500 px
- Tall topology: ~700×700 px
Start from a template based on the diagram type:
Architecture (stacked rows):
{
"canvas": {"width": 900, "height": 520},
"nodes": [
{"id": "layer1_label", "label": "Layer 1", "x": 450, "y": 60, ...},
{"id": "node_a", "label": "A", "x": 180, "y": 120, ...},
{"id": "node_b", "label": "B", "x": 350, "y": 120, ...}
],
"edges": [...],
"groups": [
{"label": "Layer 1", "node_ids": ["node_a", "node_b"], "fill": "#F0F9FF", "stroke": "#BAE6FD"}
]
}
Workflow (left-to-right chain):
{
"canvas": {"width": 900, "height": 300},
"nodes": [
{"id": "step1", "label": "Step 1", "x": 100, "y": 150, "shape": "rounded"},
{"id": "step2", "label": "Step 2", "x": 280, "y": 150, "shape": "rounded"}
],
"edges": [
{"from": "step1", "to": "step2", "label": "produces"}
]
}
Decision diamond:
{"id": "check", "label": "Passes?", "shape": "diamond", "x": 450, "y": 200}
Step 3: Render and Validate
阅读完整来源 ↗