# How to Integrate Archify with Cursor, Claude Code, and Other AI Agents

> Learn how to integrate Archify with AI agents like Cursor and Claude. Use a single agent-neutral skill and natural language prompts for seamless integration.

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

---

**Archify integrates with AI agents through a single agent-neutral skill that any supported agent can discover and invoke using natural-language prompts.**

Archify is distributed as an **agent-skill** that generates typed JSON architecture diagrams and renders them as self-contained HTML artifacts. The integration pattern is identical across all agents: install the skill to the agent's scan path, then prompt the agent naturally. This guide covers exact installation commands and usage patterns for Cursor, Claude Code, and other supported agents.

## Installing Archify for Cursor

Cursor discovers skills from [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) files in specific directory roots. The `skills` CLI automates installation with the `--agent cursor` flag.

### Project-Scoped Installation

Install Archify for the current project only:

```bash
npx -y skills add tt-a1i/archify --skill archify --agent cursor --copy --yes

```

### Global Installation

Install Archify once for all Cursor workspaces:

```bash
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

```

These commands are documented in the Cursor onboarding research file at [`docs/research-cursor-onboarding-2026-07.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-cursor-onboarding-2026-07.md) and the main [`README_EN.md`](https://github.com/tt-a1i/archify/blob/main/README_EN.md).

### Where Cursor Finds the Skill

| Scope | Path Scanned by Cursor | Archify Entry Point |
|-------|------------------------|---------------------|
| **Project** | `.agents/skills/` or `.cursor/skills/` | [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) |
| **User/Global** | `~/.agents/skills/` or `~/.cursor/skills/` | [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) |

After installation, verify discoverability:

```bash
npx skills list --agent cursor --json

```

### Using Archify in Cursor

Prompt Cursor naturally in the editor or terminal:

```text
Use archify to map this repository's runtime architecture.

```

Cursor invokes `archify/bin/archify.mjs doctor`, validates the generated JSON IR, runs the `deliver` command, and opens the resulting HTML artifact.

## Installing Archify for Claude Code

Claude Code follows the same pattern with a different default path.

### Installation Command

```bash
npx skills add tt-a1i/archify --skill archify --agent claude-code --copy --yes

```

This installs to `~/.claude/skills/` (or legacy `.claude/skills/` for project-scoped installs).

### Discovery and Usage

Claude Code loads any folder containing a valid [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md). Archify's [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) satisfies this contract, so the skill appears in Claude Code's **Skills** panel.

From a Claude Code chat session:

```text
Use archify to create a high-level architecture diagram for this project.

```

The pipeline executes identically: generate → validate → render → deliver.

## Installing Archify for Other Agents

Archify supports additional agents through the same CLI with agent-specific paths:

| Agent | Default Install Path | Example Command |
|-------|----------------------|-----------------|
| **Codex CLI** | `~/.agents/skills/` or `.agents/skills/` | `npx skills add tt-a1i/archify --agent codex --copy --yes` |
| **OpenCode** | `~/.config/opencode/skills/` or `.opencode/skills/` | `npx skills add tt-a1i/archify --agent opencode --copy --yes` |
| **Raven** | `~/.raven/workspace/skills/` (manual) | `unzip archify.zip -d ~/.raven/workspace/skills/` |

These paths are enumerated in the **Installation options** table of [`README_EN.md`](https://github.com/tt-a1i/archify/blob/main/README_EN.md) at lines 56-64.

### Universal Global Install

For agents sharing the `~/.agents/skills/` root (Cursor, Codex, OpenCode):

```bash
npx -y skills add tt-a1i/archify --skill archify --global --copy --yes

```

## How the Agent Integration Works Under the Hood

Archify's skill implementation is **completely agent-neutral**. The agent-specific logic consists solely of where the skill is installed and how the user invokes it.

### The Five-Step Pipeline

| Step | Implementation | Location in Source |
|------|---------------|-------------------|
| **Generate** | CLI parses natural-language prompt into typed JSON IR | `archify/bin/archify.mjs` |
| **Validate** | Schema validators enforce structure, layout, and reachability rules | `archify/schemas/` |
| **Preview** *(optional)* | Local watch loop reloads verified revisions, preserving last-good artifact on error | `preview` command |
| **Deliver** | Renderer produces deterministic self-contained HTML (plus PNG/SVG/WebM) | `deliver` command |
| **Iterate** | Subsequent prompts edit JSON source; unchanged parts remain stable | Incremental refinement |

### Entry Point: `archify.mjs`

The CLI in `archify/bin/archify.mjs` exposes five commands: `doctor`, `validate`, `preview`, `deliver`, and `guide`. Agents invoke `archify.mjs` directly; no agent-specific wrappers exist.

### UI Agent Selection

The web interface for choosing agents lives in [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html), where the tab list derives from the `KNOWN_AGENTS` set at lines 291-293. This UI is for manual browser use, not agent integration.

## Key Integration Files

| File | Purpose |
|------|---------|
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Canonical skill manifest every agent reads to discover capabilities |
| `archify/bin/archify.mjs` | CLI entry point with `doctor`, `validate`, `preview`, `deliver`, `guide` commands |
| `archify/schemas/` | JSON Schema definitions for typed IR validation |
| [`README_EN.md`](https://github.com/tt-a1i/archify/blob/main/README_EN.md) | Installation matrix and quick-start guide |
| [`docs/research-cursor-onboarding-2026-07.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-cursor-onboarding-2026-07.md) | Detailed Cursor-specific commands and verification |
| [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) | Browser UI with agent selection tabs |

## Complete Integration Examples

### Cursor: Full Workflow

```bash

# Install

npx -y skills add tt-a1i/archify --skill archify --agent cursor --copy --yes

# Verify

npx skills list --agent cursor --json

# Use in Cursor chat

Use archify to map this repository's runtime architecture.

```

### Claude Code: Full Workflow

```bash

# Install

npx skills add tt-a1i/archify --skill archify --agent claude-code --copy --yes

```

Then in Claude Code:

```text
Use archify to create a data-flow diagram of the authentication pipeline.

```

### Multi-Agent Global Setup

```bash

# One command covers Cursor, Codex, and OpenCode

npx -y skills add tt-a1i/archify --skill archify --global --copy --yes

```

## Summary

- **Archify integrates with AI agents through a single agent-neutral skill** installed via the `skills` CLI with `--agent` flags.
- **Cursor** uses `--agent cursor` and scans `.cursor/skills/` or `~/.cursor/skills/`.
- **Claude Code** uses `--agent claude-code` and scans `~/.claude/skills/`.
- **Other agents** (Codex, OpenCode, Raven) follow the same pattern with agent-specific paths documented in [`README_EN.md`](https://github.com/tt-a1i/archify/blob/main/README_EN.md).
- **The core pipeline** (generate → validate → deliver) is identical across all agents and lives entirely in `archify/bin/archify.mjs`.
- **No agent-specific code exists** in the rendering or validation logic; only installation location differs.

## Frequently Asked Questions

### How do I verify Archify is properly installed for my agent?

Run `npx skills list --agent <agent> --json` and confirm `archify` appears in the output. For Cursor specifically, check that [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) exists in `.cursor/skills/archify/` (project) or `~/.cursor/skills/archify/` (global).

### Can I use the same Archify installation for multiple agents?

Yes. A global install to `~/.agents/skills/` is shared by Cursor, Codex CLI, and OpenCode. Claude Code requires its own path (`~/.claude/skills/`), and Raven requires manual unzipping to its dedicated directory.

### What happens when an agent runs Archify?

The agent executes `archify/bin/archify.mjs` with the `doctor` subcommand by default. This generates typed JSON IR from your natural-language prompt, validates it against schemas in `archify/schemas/`, renders a self-contained HTML artifact, and returns either the file path or a shareable card URL.

### Does Archify work offline after installation?

Yes. The CLI and all rendering logic run locally. The only network-dependent features are optional: fetching updates via `npx skills` and sharing artifacts via hosted URLs. Generated HTML files are fully self-contained and work without connectivity.