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

> Understand SKILL.md's purpose in the diagram-design project. Discover how it defines skill discovery, invocation, and documentation for the Instagit platform.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-21

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) | Detailed syntax for Mermaid imports |
| [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) | Output format specifications |
| [`commands/doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/doctor.md) | Diagnostic troubleshooting guide |
| [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) | User profile customization options |

## Practical Usage Examples

When [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

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

```

Export to PNG format:

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

```

Run diagnostics:

```bash
instagit run doctor

```

Query skill metadata programmatically using the Instagit SDK:

```javascript
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) resides at [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.