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

> Discover how Archify integrates with AI coding agents. Learn to generate architecture visualizations using deterministic JSON-to-diagram workflows and agent skill integration.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-30

---

**Archify functions as a self-contained Agent Skill that AI coding agents discover via [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.).

```bash
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`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) providing the base contract for all diagram types (architecture, workflow, sequence, data-flow, lifecycle).

Example workflow specification:

```json
{
  "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:

```bash
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:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** – Canonical skill manifest describing discovery, validation, delivery, and viewer contracts.
- **[`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/benchmarks/ordinary-model-floor/prompts/agent-tool-call.workflow.md)** – Reference implementation showing tool-call integration patterns.
- **[`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md)** – Formal specification for artifact generation, hashing, and atomic writes.
- **[`archify/references/viewer-runtime.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)) with type-specific extensions in `archify/schemas/`, ensuring consistent JSON structures across different visualization needs.