What is a SKILL.md File: Content, Structure, and Usage in the HumanLayer Skills Repository

A SKILL.md file is the canonical definition file for each skill in the HumanLayer skills repository, containing YAML front-matter for metadata and markdown sections that specify purpose, output formats, and execution workflows for LLM agents.

The SKILL.md file acts as both the metadata descriptor and runtime execution guide for reusable AI skills in humanlayer/skills. Located at plugins/<skill-name>/skills/<skill-name>/SKILL.md, this markdown specification defines how the Instagit platform should interpret user requests and enforce deterministic output formats. Understanding the SKILL.md content structure allows developers to extend the skill catalog or customize AI agent behavior with precision.

File Location and Naming Convention

Every skill in the repository follows a strict directory convention. The canonical definition file resides at:

plugins/<skill-name>/skills/<skill-name>/SKILL.md

For example, the show-me skill definition lives at plugins/show-me/skills/show-me/SKILL.md, while the narrow-react-prop-types skill is located at plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md. This predictable structure enables the Instagit runtime to programmatically discover and load skill definitions by name.

Content Structure and Sections

A SKILL.md file combines YAML front-matter with instructional markdown sections. The file serves dual purposes: it provides human-readable documentation and machine-parseable instructions that constrain LLM outputs.

YAML Front-Matter Metadata

The file begins with YAML front-matter containing required metadata fields that the skill loader reads during initialization.

---
name: show-me
description: Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
---

The name field must match the directory name, while description provides a concise summary for the skill registry. According to the source code in plugins/show-me/skills/show-me/SKILL.md, this metadata enables the platform to index and display available capabilities without parsing the full document.

Purpose Statement

Following the front-matter, a purpose statement articulates the skill's objective in natural language. This section typically includes directives on tone, conciseness, and target audience. For instance, the show-me skill instructs agents to "Help the user understand the current topic of conversation visually" and explicitly mandates "Skip the preamble and keep prose brief."

Guidelines and Output Formats

This section enumerates the specific visual artifacts and code formats the skill may generate. The show-me skill (lines 8-99) lists supported outputs including:

• Pseudocode blocks for illustrating logic flow
• Mermaid sequence diagrams for showing interactions
• Diff snippets for highlighting state changes
• HTML slides for presentations
• Component trees for UI architecture

Each format includes concrete syntax examples ensuring consistent rendering across different LLM responses.

Stylistic Directives

Stylistic rules constrain how the agent presents information. These directives specify what to omit (preambles, excessive prose), how to structure visualizations ("Place each visual next to the short text it supports"), and judgment guidelines ("Use your judgement and don't overwhelm the user"). These constraints prevent the LLM from generating verbose or unfocused content.

Optional Workflow Steps

Complex skills define step-by-step execution workflows in the markdown body. The narrow-react-prop-types skill (lines 22-150) implements a 10-step process that guides the AI through identifying live code paths, tightening TypeScript prop types, and validating changes. These workflows function as deterministic algorithms embedded within the skill definition.

How the Instagit Platform Uses SKILL.md

When the Instagit platform receives a request to invoke a skill (e.g., !show-me), the runtime executes a four-phase pipeline using the corresponding SKILL.md file:

1. Load: The system retrieves the file from plugins/<skill-name>/skills/<skill-name>/SKILL.md to extract the name and description metadata.

2. Parse: The parser converts the instructional sections into an enriched prompt that constrains the LLM's output format (e.g., "use Mermaid for flow diagrams", "show diff when highlighting changes").

3. Execute: The platform calls the LLM with the constructed prompt, ensuring the model adheres to the formats and workflows defined in the skill specification.

4. Render: Any generated artifacts (HTML, Mermaid diagrams, diff blocks) are extracted from the LLM response and rendered back to the user interface.

This process transforms a static markdown file into a deterministic, reusable specification that standardizes AI agent behavior across different sessions.

Practical Implementation Examples

Invoking a Skill Programmatically

The following TypeScript pseudo-code illustrates how the Instagit runtime references the SKILL.md file during skill invocation:

await runSkill({
  skillName: "show-me",               // looks up plugins/show-me/skills/show-me/SKILL.md
  userPrompt: "Explain event-driven architecture",
});

Minimal SKILL.md Skeleton

Developers creating new skills can use this template structure:

---
name: my-skill
description: Brief description of what the skill does.
---

# What the skill does

Provide a concise explanation...

## Formats you may use

- Pseudocode blocks
- Mermaid diagrams
- Diff snippets

Key Reference Files

The repository contains several canonical examples demonstrating different complexity levels:

Skill	SKILL.md Location
show-me	plugins/show-me/skills/show-me/SKILL.md
narrow-react-prop-types	plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md
improve-claude-md	plugins/improve-claude-md/skills/improve-claude-md/SKILL.md
design-control-loop	plugins/design-control-loop/skills/design-control-loop/SKILL.md
build-iterated-agentic-loop	plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md

Summary

• A SKILL.md file combines YAML front-matter (for metadata) with markdown instructions (for execution constraints) to define reusable AI skills.
• Files must reside at plugins/<skill-name>/skills/<skill-name>/SKILL.md to enable automatic discovery by the Instagit runtime.
• The content structure includes purpose statements, output format specifications (Mermaid, diff, HTML), stylistic rules, and optional step-by-step workflows.
• The Instagit platform parses these files to construct constrained LLM prompts, ensuring deterministic output formats across different skills.
• Reference implementations in the humanlayer/skills repository demonstrate patterns for both simple visualization tasks and complex multi-step refactoring workflows.

Frequently Asked Questions

What metadata fields are required in the YAML front-matter of a SKILL.md file?

The YAML front-matter must include a name field (matching the skill directory name) and a description field (containing a brief summary of capabilities). These fields enable the Instagit loader to index the skill without parsing the full markdown content.

How does the Instagit platform parse a SKILL.md file during execution?

The runtime loads the file from plugins/<skill-name>/skills/<skill-name>/SKILL.md, extracts the YAML metadata for registration, then converts the instructional markdown sections into system prompt constraints. These constraints restrict the LLM to specific output formats like Mermaid diagrams, diff blocks, or HTML artifacts defined within the file.

What output formats can be specified in a SKILL.md file?

Skills can define various visual and code formats including pseudocode blocks, Mermaid sequence diagrams, diff snippets for change visualization, HTML slides for presentations, and component trees for UI architecture. The show-me skill demonstrates concrete syntax examples for each format in lines 8-99 of its definition.

Where should a new SKILL.md file be placed in the repository?

New skill definitions must follow the path convention plugins/<skill-name>/skills/<skill-name>/SKILL.md. This nested structure ensures the Instagit runtime can programmatically resolve skill names to their canonical definition files using predictable string interpolation.

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