# What is a SKILL.md File: Content, Structure, and Usage in the HumanLayer Skills Repository > Discover what a SKILL.md file is in the HumanLayer skills repository. Learn about its YAML metadata, markdown content, and usage for LLM agent workflows. - Repository: [HumanLayer/skills](https://github.com/humanlayer/skills) - Tags: getting-started - Published: 2026-09-12 --- **A [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/SKILL.md) file acts as both the metadata descriptor and runtime execution guide for reusable AI skills in **humanlayer/skills**. Located at `plugins//skills//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: ```text plugins//skills//SKILL.md ``` For example, the **show-me** skill definition lives at [`plugins/show-me/skills/show-me/SKILL.md`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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. ```yaml --- 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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/SKILL.md) file: 1. **Load**: The system retrieves the file from `plugins//skills//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`](https://github.com/humanlayer/skills/blob/main/SKILL.md) file during skill invocation: ```typescript 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: ```markdown --- 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`](https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md) | | **narrow-react-prop-types** | [`plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/skills/improve-claude-md/SKILL.md) | | **design-control-loop** | [`plugins/design-control-loop/skills/design-control-loop/SKILL.md`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md) | ## Summary - A [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/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//skills//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//skills//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//skills//SKILL.md`. This nested structure ensures the Instagit runtime can programmatically resolve skill names to their canonical definition files using predictable string interpolation.