What Is the Purpose of SKILL.md in Archify? Understanding the Skill Manifest

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 file in the tt-a1i/archify repository is located at 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 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 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 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 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, you validate a workflow diagram against showcase quality standards:

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:

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

This command reads the rendering specifications from 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—using:

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

For authoring assistance, the guide command consults the "Type router" table in SKILL.md to map natural language requests to appropriate diagram types:

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

Documentation References Linked by SKILL.md

SKILL.md does not operate in isolation; it references additional documentation that the skill runtime loads on demand. These include:

• renderers/workflow/README.md: Defines layout contracts for workflow diagrams
• 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 in 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 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 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 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 for layout contracts and 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.

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