# What Is the Purpose of SKILL.md in Archify? Understanding the Skill Manifest > Discover the purpose of SKILL.md in Archify. Learn how this skill definition file defines tool identity, metadata, and authoring workflows for the Archify framework. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: internals - Published: 2026-09-12 --- **SKILL.md serves as the central skill definition file and operational manifest for the Archify framework, defining the tool's identity, version metadata, and executable authoring workflows.** The [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) file in the `tt-a1i/archify` repository is located at [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) and functions as the authoritative source that powers the command-line interface. It bridges the skill manager and the implementation in `bin/archify.mjs`, telling the framework how to present Archify, what validation rules to enforce, and which documentation to reference during diagram generation. ## Core Function of SKILL.md in the Archify Framework Within the repository structure, [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) acts as the **skill manifest** that the framework parses to expose functionality to users. Without this file, the skill manager would lack the necessary metadata to invoke Archify or enforce its specific authoring constraints. ### Metadata and Skill Identity The header section of [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) declares the **skill name** (`archify`) and provides a concise **description** of its capabilities—generating polished, validated architecture-related diagrams as self-contained HTML. It also stores critical **metadata** including version information (currently version 2.17), author attribution (tt-a1i), and provenance data. This allows the CLI to report accurate version information when users query skill details. ### Operational Instructions and Authoring Rules The body of [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) contains the **operational guide** that dictates how the skill behaves at runtime. Key sections include: - **Fast authoring path**: A precise workflow prescribing how users generate diagrams (choose a type, read the matching schema, edit candidate JSON, validate, then deliver) - **Type routing**: Rules that map user requests to specific diagram implementations - **Update awareness**: Guidelines for handling schema and renderer updates - **Mermaid input handling**: Specifications for processing Mermaid syntax - **Authoring invariants**: Concrete constraints controlling validation, geometry, and rendering logic ## How SKILL.md Powers the CLI Implementation The `bin/archify.mjs` entry point implements the commands and workflows described in the skill file. When you execute CLI commands, the tool reads [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) to determine available operations and validate execution paths. ### Validation Commands The skill file defines a strict validation workflow that the CLI exposes via the `validate` command. Following the "Fast authoring path" prescribed in [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md), you validate a workflow diagram against showcase quality standards: ```bash node bin/archify.mjs validate workflow my-diagram.json --quality showcase --json ``` The flags `validate`, `workflow`, and `--quality showcase` directly correspond to the operational rules defined in the skill documentation. ### Delivery Workflow After validation, the delivery step generates the final HTML artifact. This mirrors the "Deliver" stage outlined in the skill file: ```bash node bin/archify.mjs deliver workflow my-diagram.json output.html --quality showcase --json ``` This command reads the rendering specifications from [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) to produce the self-contained HTML output. ### Runtime Metadata and Routing Queries You can query the skill's metadata—which the CLI reads from the `metadata` block of [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md)—using: ```bash node bin/archify.mjs skill-info --json ``` For authoring assistance, the `guide` command consults the "Type router" table in [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) to map natural language requests to appropriate diagram types: ```bash node bin/archify.mjs guide "create a data-flow diagram for an ETL pipeline" --json ``` ## Documentation References Linked by SKILL.md [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) does not operate in isolation; it references additional documentation that the skill runtime loads on demand. These include: - [`renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/renderers/workflow/README.md): Defines layout contracts for workflow diagrams - [`references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/references/authoring-contract.md): Contains detailed field enums, spacing mathematics, and geometry repair rules - `schemas/` and `examples/`: Directories containing JSON schema definitions and example files that authors must reference during the fast authoring path ## Summary - [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) serves as the **skill manifest** for the tt-a1i/archify repository, defining identity, version 2.17, and author metadata. - The file contains the **operational guide** for the CLI, including the fast authoring path and validation rules. - `bin/archify.mjs` implements commands (`validate`, `deliver`, `skill-info`, `guide`) by reading workflows defined in the skill file. - The skill manifest links to supporting documentation including renderer READMEs and authoring contracts to enforce geometry and validation constraints. ## Frequently Asked Questions ### What information does SKILL.md contain about the Archify version? The metadata block in [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) stores the current skill version (2.17), author attribution (tt-a1i), and provenance details. When you run `node bin/archify.mjs skill-info --json`, the CLI reads this metadata block to report version information and upstream attribution. ### How does Archify use SKILL.md during diagram validation? During validation, the CLI consults [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) to enforce the "Fast authoring path" workflow and authoring invariants. The file specifies which schemas to apply, quality levels like `showcase`, and validation constraints that control geometry and rendering rules before final delivery. ### Can I modify SKILL.md to change Archify's behavior? Modifying [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) would alter how the skill manager presents and executes Archify, as `bin/archify.mjs` relies on this file for command routing and metadata. Changes to operational sections like type routing or the fast authoring path would directly affect how the CLI processes validate and deliver commands. ### Where does SKILL.md reference additional documentation? The skill file points to [`renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/renderers/workflow/README.md) for layout contracts and [`references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/references/authoring-contract.md) for detailed field specifications and geometry repair rules. It also references the `schemas/` and `examples/` directories that contain the JSON definitions required during the authoring workflow.