# What Is the Purpose of SKILL.md in Archify? Complete Technical Guide > Discover the purpose of SKILL.md in Archify. Learn how this central skill definition file defines metadata, capabilities, and authoring rules for architecture diagram validation and rendering. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: deep-dive - Published: 2026-09-10 --- **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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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: ```bash node bin/archify.mjs validate workflow my-diagram.json --quality showcase --json ``` **Delivering final HTML artifacts** mirrors the Deliver step from the skill file: ```bash 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`](https://github.com/tt-a1i/archify/blob/main/SKILL.md): ```bash node bin/archify.mjs skill-info --json ``` **Requesting authoring guidance** consults the Type router table to map natural language requests to diagram types: ```bash node bin/archify.mjs guide "create a data-flow diagram for an ETL pipeline" --json ``` ## Referenced Documentation and Dependencies [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) does not operate in isolation. It references several critical documentation files that the skill consults on demand: - **[`renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/renderers/workflow/README.md)** – Defines the layout contract referenced for workflow diagrams - **[`references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/references/authoring-contract.md) that enforce geometry and layout constraints.