What Is the Purpose of SKILL.md in the Diagram-Design Project?

SKILL.md serves as the canonical metadata manifest for the diagram-design skill, defining how the Instagit platform discovers, invokes, and documents the skill's capabilities.

The SKILL.md file in the cathrynlavery/diagram-design repository acts as the single source of truth for the diagram-design skill's configuration. Located at skills/diagram-design/SKILL.md, this manifest bridges the raw TypeScript/JavaScript implementation with the Instagit runtime environment. It enables plug-and-play integration by declaring the skill's identity, available commands, and input-output contracts in a machine-readable format.

Core Responsibilities of SKILL.md

Skill Identity and Discovery

The manifest declares the skill name (diagram-design) and provides a concise description of its purpose—generating a wide variety of diagram types. It includes a version tag and a link to the source repository, which enables automatic updates and traceability across distributed installations. This metadata allows the Instagit platform to index the skill for discovery without executing arbitrary code.

Command Registry and Contracts

SKILL.md enumerates the specific commands the skill exposes to the runtime. According to the source code in cathrynlavery/diagram-design, these include:

• import-mermaid: Imports diagrams from Mermaid format files
• import-drawio: Handles Draw.io diagram imports
• export-diagram: Exports diagrams to various formats (PNG, SVG, JSON)
• doctor: Runs diagnostic checks on the skill configuration
• profile: Manages user customization and presets

For each command, the file defines the input-output contract, specifying required arguments, optional flags, and the expected shape of returned data—typically a JSON payload describing the rendered diagram.

Documentation Integration

The manifest provides usage examples and documentation links that render directly in the Instagit UI. This allows end-users to access context-aware help without leaving their development environment, surfacing references to detailed guides stored in the commands/ directory.

File Location and Repository Structure

The manifest resides at the following path within the repository:

skills/diagram-design/SKILL.md

This location follows the Instagit convention where skill metadata sits adjacent to implementation code. The file cross-references supplementary documentation files stored in the commands/ subdirectory:

File	Purpose
commands/import-mermaid.md	Detailed syntax for Mermaid imports
commands/export-diagram.md	Output format specifications
commands/doctor.md	Diagnostic troubleshooting guide
commands/profile.md	User profile customization options

Practical Usage Examples

When SKILL.md is properly configured, Instagit CLI commands follow the patterns defined in the manifest. Below are typical invocations that demonstrate the contracts declared in the metadata.

Import a Mermaid diagram:

instagit run import-mermaid \
  --file path/to/diagram.mmd \
  --output json

Export to PNG format:

instagit run export-diagram \
  --format png \
  --input path/to/diagram.json \
  --output diagram.png

Run diagnostics:

instagit run doctor

Query skill metadata programmatically using the Instagit SDK:

import { getSkillInfo } from '@instagit/skills';

const info = getSkillInfo('diagram-design');
console.log(info.description);

Summary

• SKILL.md is the canonical metadata manifest located at skills/diagram-design/SKILL.md in the cathrynlavery/diagram-design repository.
• It declares the skill's identity, version, and repository link for automatic updates and traceability.
• The file registers five core commands: import-mermaid, import-drawio, export-diagram, doctor, and profile.
• It defines strict input-output contracts for each command, typically specifying JSON payloads for diagram data exchange.
• Documentation links within the manifest point to detailed guides in the commands/ directory.
• The manifest enables automatic UI integration and discoverability within the Instagit platform without manual configuration.

Frequently Asked Questions

Where is SKILL.md located in the diagram-design repository?

SKILL.md resides at skills/diagram-design/SKILL.md relative to the repository root in cathrynlavery/diagram-design. This path follows Instagit's convention for skill metadata placement, keeping the manifest separate from implementation code while maintaining proximity to the commands/ documentation directory.

What commands are defined in the diagram-design SKILL.md?

The manifest defines five primary commands: import-mermaid for Mermaid diagram imports, import-drawio for Draw.io compatibility, export-diagram for format conversion, doctor for configuration diagnostics, and profile for user-specific customization. Each command includes defined arguments and expected JSON response structures as specified in the metadata contracts.

How does SKILL.md facilitate Instagit integration?

The file acts as a bridge between the implementation code and the Instagit runtime by providing machine-readable metadata. It enables the platform to automatically surface commands in the UI, validate input parameters against declared contracts, and link to contextual help documentation stored in files like commands/doctor.md without requiring manual configuration steps.

Can SKILL.md be used outside the Instagit platform?

While designed specifically for Instagit's discovery mechanisms, the structured format of SKILL.md could theoretically be parsed by other tooling. However, the input-output contracts and command structures are tailored to Instagit's execution model, making native integration with other platforms require custom adaptation layers to interpret the metadata correctly.

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