Where to Find Documentation for Archify: A Complete Guide to README, SKILL.md, and Code Examples

Archify's documentation is distributed across the README.md for quick-start guides, archify/SKILL.md for CLI contracts, the docs/ directory for authoring patterns, and the examples/ folder for runnable artifacts.

Archify is an open-source diagramming tool hosted at tt-a1i/archify that converts text descriptions into architecture diagrams. Finding comprehensive documentation for Archify requires navigating several specialized files rather than a single monolithic doc site. This guide maps every documentation resource from high-level overviews in the repository root to JSON schema definitions and interactive web demos.

Primary Documentation Entry Points

Archify organizes its core documentation into two critical files at the repository root and skill directory.

README.md: Project Overview and Quick Start

The README.md file serves as the main entry point for new users. Located at the repository root, it contains high-level project descriptions, installation instructions via npx skills add tt-a1i/archify -g, and links to the project site. This file covers system requirements and provides the first steps for generating diagrams from text descriptions.

SKILL.md: Command Contracts and Runtime Behavior

The archify/SKILL.md file contains the formal skill description and command-line reference. Unlike the casual README, this document specifies usage contracts, runtime notes, and the exact interface between Archify and AI assistants or IDE integrations. Developers integrating Archify into Cursor, Claude, Codex, or OpenCode should reference this file for specification-compliant invocation patterns.

Detailed Authoring and Schema References

For advanced diagram customization and validation, Archify provides deep-dive documentation in the docs/ directory and schema definitions.

Authoring Cookbook for Diagram Patterns

The docs/authoring-cookbook.md file provides step-by-step authoring patterns, schema usage guidelines, and visual presets. This resource explains how to construct complex architecture diagrams, workflow visualizations, sequence diagrams, data-flow charts, and lifecycle diagrams using Archify's specific syntax and structure.

JSON Schema Definitions in schemas/README.md

The archify/schemas/README.md file defines the JSON schema contracts for each diagram type. This reference documents the exact data structures required for architecture, workflow, sequence, data-flow, and lifecycle diagrams. Use this file to understand validation rules and required fields when generating or modifying diagram JSON files programmatically.

Examples and Interactive Resources

Practical learning resources include runnable code samples and web-based interactive tools.

Runnable Examples Directory

The examples/ folder contains ready-made JSON and HTML artifacts demonstrating common Archify scenarios. These files illustrate typical invocation patterns and serve as templates for new projects. Users can execute these examples directly to understand how text descriptions transform into finalized diagram outputs.

Project Website and Interactive Demos

The project website at https://tt-a1i.github.io/archify/ hosts interactive demos, the Proof Lab, and the Scenario Guide. This external documentation complements the repository files by providing visual demonstrations of Archify's capabilities and allowing users to experiment with diagram generation in a browser environment.

Command-Line Quick Reference

According to the archify/SKILL.md specification, Archify exposes several CLI commands through archify/bin/archify.mjs. The following commands demonstrate the complete workflow from installation to delivery:

# Install Archify globally for Cursor, Claude, Codex, or OpenCode

npx skills add tt-a1i/archify -g

# Generate a quick "architecture" diagram from a description

echo "Browser -> API -> Redis -> PostgreSQL" > description.txt
node archify/bin/archify.mjs generate architecture description.txt --json > arch.json

# Validate the generated JSON (showcase quality)

node archify/bin/archify.mjs validate architecture arch.json --quality showcase --json

# Deliver the final HTML artifact

node archify/bin/archify.mjs deliver architecture arch.json output.html --quality showcase --open --json

# Run the interactive guide for a specific scenario

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"

Summary

• Start with README.md for installation and high-level concepts.
• Reference archify/SKILL.md for formal command contracts and runtime specifications.
• Consult docs/authoring-cookbook.md for diagram authoring best practices and visual presets.
• Check archify/schemas/README.md for JSON schema definitions and validation rules.
• Explore examples/ for runnable templates and output samples.
• Visit the project website for interactive demonstrations and the Scenario Guide.
• Use docs/skill-embedded-optional-update-notifier-design.md for advanced integration patterns involving update notifications.

Frequently Asked Questions

Where is the main installation guide for Archify?

The main installation instructions reside in README.md at the repository root. This file explains how to install Archify globally using npx skills add tt-a1i/archify -g for integration with AI coding assistants like Cursor, Claude, Codex, and OpenCode.

What is the difference between README.md and SKILL.md?

README.md provides high-level project overview and quick-start instructions for general users, while archify/SKILL.md contains the formal skill description, exact command-line contracts, and runtime behavior specifications required for programmatic integration and AI assistant configuration.

How do I find the correct JSON schema for my diagram type?

Diagram-specific JSON schemas are documented in archify/schemas/README.md. This file defines the data structures, required fields, and validation rules for architecture, workflow, sequence, data-flow, and lifecycle diagram types.

Are there runnable examples I can modify?

Yes. The examples/ directory contains sample JSON and HTML files that demonstrate typical Archify use cases. These artifacts serve as starting templates that you can copy, modify, and run through the CLI commands defined in archify/SKILL.md.

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