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

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

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

Global Installation

Install Archify once for all Cursor workspaces:

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 and the 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
User/Global	~/.agents/skills/ or ~/.cursor/skills/	archify/SKILL.md

After installation, verify discoverability:

npx skills list --agent cursor --json

Using Archify in Cursor

Prompt Cursor naturally in the editor or terminal:

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

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. Archify's archify/SKILL.md satisfies this contract, so the skill appears in Claude Code's Skills panel.

From a Claude Code chat session:

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 at lines 56-64.

Universal Global Install

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

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, 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	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	Installation matrix and quick-start guide
docs/research-cursor-onboarding-2026-07.md	Detailed Cursor-specific commands and verification
scripts/start-template.html	Browser UI with agent selection tabs

Complete Integration Examples

Cursor: Full Workflow

# 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

# Install

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

Then in Claude Code:

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

Multi-Agent Global Setup

# 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.
• 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 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.

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