What Is the Purpose of SKILL.md in Archify? Complete Technical Guide

SKILL.md serves as the central skill definition file and operational manifest for Archify, defining the tool's metadata, capabilities, and strict authoring rules that govern how architecture diagrams are validated and rendered.

In the tt-a1i/archify repository, archify/SKILL.md functions as the backbone of the command-line tool. This file tells the surrounding framework exactly what the Archify skill can do and how it should present itself to users. Without this manifest, the framework would lack the necessary instructions to expose Archify’s diagram generation capabilities or enforce its validation constraints.

Core Purpose of the Skill Definition File

At its core, SKILL.md acts as both a manifest and instruction set for the Archify skill. It declares the skill identity, defines operational workflows, and establishes the constraints that control validation, geometry, and rendering. According to the tt-a1i/archify source code, this file enables the skill manager to expose Archify’s functionality to users while maintaining strict authoring invariants.

The file serves three critical functions:

• Discovery: Provides the name (archify) and description that allow the framework to catalog the skill
• Configuration: Stores version 2.17, author attribution (tt-a1i), and provenance metadata required for reporting
• Governance: Defines the "Fast authoring path" and validation rules that bin/archify.mjs enforces during execution

Key Components of SKILL.md

Header Metadata and Identity

The header section of archify/SKILL.md establishes the skill's identity and descriptive capabilities. It specifies the name (archify) and a concise description covering the tool's purpose: generating polished, validated architecture-related diagrams as self-contained HTML. The metadata block tracks version information (currently 2.17), author details (tt-a1i), and provenance data, enabling the framework to report version information and upstream attribution.

The Fast Authoring Path

The operational guide within SKILL.md outlines the Fast authoring path, a precise six-step workflow users must follow when generating diagrams. This workflow requires:

1. Choosing a diagram type
2. Reading the matching schema from the schemas/ directory
3. Editing the candidate JSON
4. Validating against geometry rules
5. Repairing any spacing issues
6. Delivering the final HTML artifact

This sequence is hardcoded into the CLI's command structure, ensuring every user follows the same validation pipeline.

Validation and Routing Rules

The file contains sections on update awareness, type routing, Mermaid input handling, and authoring invariants. These provide the skill-runtime with concrete rules controlling validation logic, geometry constraints, and rendering parameters. The "Type router" table maps natural language requests to specific diagram implementations, while authoring invariants define strict constraints on field enums and spacing math.

How SKILL.md Powers the CLI

The bin/archify.mjs entry point reads archify/SKILL.md to implement its command structure. When you execute the CLI, you are running workflows defined in the skill definition file.

Validating diagrams follows the exact workflow prescribed in the Fast authoring path:

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

Delivering final HTML artifacts mirrors the Deliver step from the skill file:

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

Querying skill metadata reads the metadata block directly from SKILL.md:

node bin/archify.mjs skill-info --json

Requesting authoring guidance consults the Type router table to map natural language requests to diagram types:

node bin/archify.mjs guide "create a data-flow diagram for an ETL pipeline" --json

Referenced Documentation and Dependencies

SKILL.md does not operate in isolation. It references several critical documentation files that the skill consults on demand:

• renderers/workflow/README.md – Defines the layout contract referenced for workflow diagrams
• references/authoring-contract.md – Contains detailed field enums, spacing math, and geometry repair rules
• schemas/ – Contains JSON schema definitions authors must read during the fast authoring path
• examples/ – Provides example JSON files demonstrating valid diagram structures

These dependencies ensure that validation rules and rendering contracts remain decoupled from the core skill logic while remaining accessible to the runtime.

Summary

• archify/SKILL.md serves as the canonical skill definition file and operational manifest for the Archify tool according to the tt-a1i/archify source code
• The file stores metadata (version 2.17, author tt-a1i), descriptive capabilities, and strict authoring rules required for framework integration
• It defines the Fast authoring path, a six-step workflow for diagram creation, validation, and delivery
• bin/archify.mjs implements CLI commands (validate, deliver, guide, skill-info) according to the specifications in SKILL.md
• The file references supporting documentation including layout contracts and authoring constraints stored in renderers/ and references/

Frequently Asked Questions

Where is SKILL.md located in the Archify repository?

The skill definition file is located at archify/SKILL.md in the repository root. This specific path allows the skill manager to locate the manifest and instruction set necessary to initialize and run the Archify skill.

What metadata does SKILL.md contain?

The file contains a metadata block specifying version 2.17, author attribution to tt-a1i, and provenance information. This data enables the framework to report version details and maintain upstream attribution when displaying skill information to users.

How does SKILL.md affect the CLI commands I can run?

Every command in bin/archify.mjs—including validate, deliver, guide, and skill-info—implements workflows and rules defined in SKILL.md. The file's "Fast authoring path" section dictates the exact sequence of operations for diagram validation and delivery, while the "Type router" table powers the natural language mapping in the guide command.

Why is SKILL.md necessary for the framework to function?

Without SKILL.md, the framework would lack the manifest required to expose Archify's functionality to users. The file provides essential metadata for skill discovery, operational rules for validation and rendering, and references to dependent documentation like references/authoring-contract.md that enforce geometry and layout constraints.

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