How Archify Interacts with AI Coding Agents: The Agent Skill Integration Guide

Archify functions as a self-contained Agent Skill that AI coding agents discover via SKILL.md, install through skill registries, and invoke through deterministic JSON-to-diagram workflows to generate architecture visualizations.

Archify is engineered specifically for AI-powered coding agents such as Cursor, Claude Code, Codex CLI, and OpenCode. Instead of operating as a standalone utility, it exposes a formal skill interface that agents can discover, validate, and execute within chat sessions. This guide details the complete interaction protocol between Archify and AI coding agents, from initial discovery through final artifact delivery.

What Is the Archify Agent Skill?

An Agent Skill is a self-contained package that exposes capabilities through a standardized manifest. In archify/SKILL.md, Archify defines its skill name, version, and operational contracts. Agents scan repositories for this file to register Archify as an available capability.

The skill abstraction ensures agents never invoke hidden scripts. All functionality surfaces through documented commands in bin/archify.mjs, with contracts specified in the skill manifest and archify/references/delivery-contract.md.

The 7-Step Agent Interaction Workflow

AI coding agents interact with Archify through a deterministic seven-stage pipeline. Each stage produces machine-readable outputs that agents can parse, validate, and repair programmatically.

Step 1: Skill Discovery via SKILL.md

Agents initiate interaction by scanning the repository root for archify/SKILL.md. This markdown file contains front-matter metadata declaring the skill name, description, version, and entry points.

When present, the agent registers Archify as an available skill. The file serves as the canonical manifest—agents treat it as the single source of truth for invocation rules and never execute undocumented binaries.

Step 2: Installation to Agent-Specific Directories

The user or agent executes a one-liner installation command that copies Archify into agent-specific skill directories (.agents/skills/archify, .cursor/skills/archify, etc.).

npx skills add tt-a1i/archify -g

This command, documented in the README "Quick start" section, installs the skill globally for the current agent environment.

Step 3: Typed JSON IR Generation

The agent generates a typed JSON Intermediate Representation (IR) describing the desired diagram. This JSON follows strict schemas defined in archify/schemas/, with common.schema.json providing the base contract for all diagram types (architecture, workflow, sequence, data-flow, lifecycle).

Example workflow specification:

{
  "type": "workflow",
  "meta": { "quality_profile": "showcase" },
  "nodes": [
    { "id": "user", "type": "frontend", "label": "User" },
    { "id": "router", "type": "backend", "label": "Router" },
    { "id": "tool", "type": "external", "label": "Tool Provider" }
  ],
  "edges": [
    { "source": "user", "target": "router", "label": "request" },
    { "source": "router", "target": "tool", "label": "tool‑call" },
    { "source": "tool", "target": "router", "label": "response" },
    { "source": "router", "target": "user", "label": "reply" }
  ]
}

Step 4: Validation with Machine-Readable Receipts

Archify validates the JSON IR against schema, layout, and semantic rules using the bundled validator:

node bin/archify.mjs validate workflow candidate.json --quality showcase --json

The validator returns a JSON receipt containing a diagnostics[] array. Each diagnostic specifies the subject, supportedFixes, and exact evidence field. Agents parse this receipt to programmatically apply suggested fixes and retry validation without human intervention.

Step 5: Deterministic Delivery

Upon validation success, the agent triggers delivery:

node bin/archify.mjs deliver workflow candidate.json diagram.html --quality showcase --json

The deliver command compiles the JSON into a deterministic HTML/SVG artifact. It performs an atomic write operation—emitting the file only after all checks succeed—preventing partial or corrupted outputs. The command returns the artifact path, validation summary, and a SHA-256 receipt defined in archify/references/delivery-contract.md.

Step 6: Viewer Interaction and Visual Verification

The generated HTML contains built-in viewer capabilities including theme switching, search, focus mode, route tracing, and share-card export. Agents can return the artifact URL to users or invoke visual verification:

node bin/archify.mjs visual-check diagram.html --json

This optional step confirms the diagram renders correctly across various viewport sizes, as documented in the SKILL.md section "Optional viewer capabilities".

Step 7: Benchmarking Tool-Call Workflows

Real-world integration patterns appear in benchmarks/ordinary-model-floor/prompts/agent-tool-call.workflow.md. This benchmark demonstrates how agents call Archify as part of a tool-call workflow—generating JSON, running validation, and delivering the final diagram without human repair loops.

Architectural Highlights for AI Integration

Several design decisions make Archify particularly suitable for AI coding agents:

Skill-First Design – The SKILL.md manifest eliminates ambiguity. Agents parse a single file to understand all capabilities, parameters, and contracts.

Typed JSON IR – All diagram types extend common.schema.json, providing deterministic contracts that LLMs can reliably populate. Type-specific schemas in archify/schemas/ enforce strict validation rules.

Agent-Friendly Diagnostics – Validation failures return structured JSON with supportedFixes arrays. Agents can implement automatic repair loops by applying these fixes and revalidating.

Zero-Install Runtime – Archify runs entirely in Node.js without external service dependencies (except an optional, opt-out update check). This sandbox-safe architecture suits restricted agent environments that cannot make arbitrary network calls.

Deterministic Compilation – The deliver step guarantees identical outputs for identical inputs, enabling reproducible builds across different agent sessions.

Key Implementation Files

Understanding these source files clarifies the agent integration surface:

• archify/SKILL.md – Canonical skill manifest describing discovery, validation, delivery, and viewer contracts.
• archify/schemas/README.md – JSON IR schema definitions that agents use to author diagram specifications.
• bin/archify.mjs – Entry point for validation (validate) and delivery (deliver) commands.
• benchmarks/ordinary-model-floor/prompts/agent-tool-call.workflow.md – Reference implementation showing tool-call integration patterns.
• archify/references/delivery-contract.md – Formal specification for artifact generation, hashing, and atomic writes.
• archify/references/viewer-runtime.md – Documentation of viewer capabilities available in generated artifacts.

Summary

Archify interacts with AI coding agents through a formal skill protocol:

• Agents discover capabilities via the SKILL.md manifest in the repository root.
• Installation uses standard skill registries with npx skills add.
• Interaction proceeds through typed JSON IR generation, schema validation, and deterministic HTML delivery.
• The validation system returns machine-readable diagnostics enabling automatic error repair.
• All operations execute locally in Node.js without external dependencies, ensuring sandbox compatibility.
• Real-world benchmarks demonstrate end-to-end tool-call workflows requiring zero human intervention.

This architecture positions Archify as a deterministic, schema-driven diagram generator that AI agents can invoke reliably within automated coding workflows.

Frequently Asked Questions

How does an AI agent discover that Archify is available in a repository?

Agents scan for archify/SKILL.md at the repository root. This file contains standardized front-matter metadata that registers Archify as an available skill. The agent parses this manifest to understand entry points, commands, and operational contracts without executing arbitrary code.

What happens if the AI generates invalid JSON for a diagram?

Archify's validator (node bin/archify.mjs validate) returns a structured JSON receipt containing a diagnostics[] array. Each diagnostic includes supportedFixes and exact evidence fields. The agent can parse this output, apply the suggested fixes programmatically, and revalidate until the JSON passes all schema and semantic checks.

Can AI agents use Archify without internet access?

Yes. Archify operates as a zero-install Node.js runtime that functions entirely offline. The only exception is an optional, opt-out update check. All diagram compilation, validation, and delivery occur locally, making it safe for sandboxed agents with restricted network permissions.

What diagram types can AI agents generate with Archify?

Agents can generate architecture diagrams, workflow diagrams, sequence diagrams, data-flow diagrams, and lifecycle diagrams. All types share a common schema foundation (common.schema.json) with type-specific extensions in archify/schemas/, ensuring consistent JSON structures across different visualization needs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}