# What Is the Purpose of the SKILL.md File in dotnet/skills?

> Discover the purpose of the SKILL.md file in dotnet/skills. It acts as a metadata descriptor and contract for automated skill discovery, validation, and documentation.

- Repository: [.NET Platform/skills](https://github.com/dotnet/skills)
- Tags: how-to-guide
- Published: 2026-07-06

---

**The SKILL.md file serves as the canonical metadata descriptor and self-describing contract for every skill in the dotnet/skills repository, enabling automated discovery, validation, and documentation generation.**

Each skill in the repository is defined by a structured markdown file that declares its capabilities, constraints, and execution workflow. The SKILL.md file follows a strict schema that allows tooling to parse skill definitions without requiring additional code. This design makes every skill discoverable, machine-readable, and self-documenting across the entire ecosystem.

## Core Purpose and Structure

The SKILL.md file acts as the single source of truth for skill metadata. According to the source code analysis, it contains several critical sections that define how a skill behaves and when it should be invoked.

### Metadata Declaration

Every SKILL.md begins with YAML frontmatter that declares the **name**, **description**, and **license** under which the skill is distributed. This header provides the essential identity information that the validator and documentation generators consume first.

### Usage Guidelines and Constraints

The file explicitly documents **when the skill should be used** and **when it should not be used**, helping automated systems and developers understand the appropriate context for invocation. It also specifies critical rules that guard against common mistakes for the target platform, ensuring safe execution across different environments.

### Workflow Definition

The SKILL.md outlines a **step-by-step workflow** that includes detection logic, platform-specific commands, and validation checkpoints. This structured approach allows the skill-validator to understand the execution flow without parsing imperative code. The workflow section typically defines inputs through structured tables and describes the sequence of operations required to complete the skill's objective.

## Machine-Readable Contract

The SKILL.md file is consumed by the **skill-validator** located in [`eng/skill-validator/src/Models.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Models.cs) to automatically generate documentation, perform static validation, and expose the skill to tooling such as Instagit.

Because every skill follows the same structured markdown schema, the validator can reliably parse the file and surface the skill’s capabilities to end-users. The validator deserializes the markdown sections into the `SkillManifest` model, which includes properties for `Name`, `Description`, `License`, `Inputs`, and `WorkflowSteps`.

## SKILL.md Structure and Schema

The file follows a predictable pattern that balances human readability with machine parsing requirements.

Here is a minimal template that demonstrates the expected structure:

```markdown
---
name: my-skill
description: > 
  One-sentence summary of what the skill does.
license: MIT
---

# My Skill

## When to Use

- Specific scenario A
- Specific scenario B

## When Not to Use

- When condition X is not met

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| Example | Yes | Explanation |

## Workflow

1. Step 1 description
2. Step 2 description

```

Real skill files, such as the **run-tests** skill found in `plugins/**/skills/**/SKILL.md`, demonstrate this pattern in production use.

## Validation and Tooling Integration

The validator reads each SKILL.md and performs three critical functions:

1. **Validates** that required fields are present and correctly formatted.
2. **Generates** web documentation for the skill automatically.
3. **Exposes** the skill to Instagit so users can invoke it via natural-language prompts.

The integration relies on the consistent schema defined in [`eng/skill-validator/src/Models.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Models.cs). The `SkillManifest` class maps directly to the sections found in SKILL.md files, creating a type-safe representation that drives the validation engine. Additional documentation in [`eng/skill-validator/src/docs/InvestigatingResults.md`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/docs/InvestigatingResults.md) keeps the validation syntax synchronized with the SKILL.md specification.

## Summary

- **SKILL.md** is the canonical descriptor for every skill in the dotnet/skills repository.
- It declares metadata (name, description, license), usage constraints, and step-by-step workflows.
- The file follows a strict schema that enables the skill-validator in [`eng/skill-validator/src/Models.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Models.cs) to parse and validate skills automatically.
- Skills become discoverable and invocable through tooling like Instagit without requiring additional integration code.
- Files are located throughout the repository under `plugins/**/skills/**/SKILL.md`.

## Frequently Asked Questions

### What happens if a SKILL.md file is missing required sections?

The skill-validator will fail validation and prevent the skill from being exposed to tooling. The validator checks for mandatory fields such as name, description, and license in the frontmatter, as well as required workflow sections. Missing critical rules or input definitions will generate errors during the build process.

### How does the skill-validator parse the markdown structure?

The validator uses the `SkillManifest` class defined in [`eng/skill-validator/src/Models.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Models.cs) to deserialize the YAML frontmatter and markdown sections into typed properties. This model includes dictionaries for inputs and lists for workflow steps, allowing the validator to perform static analysis on the skill's structure without executing any code.

### Can I add custom fields to a SKILL.md file?

While the schema supports standard fields like name, description, license, inputs, and workflow steps, adding custom fields may cause validation failures unless the `SkillManifest` model in [`eng/skill-validator/src/Models.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Models.cs) is updated to recognize them. The strict schema ensures consistency across all skills in the repository.

### Where are SKILL.md files located in the repository?

SKILL.md files are distributed throughout the repository under the path pattern `plugins/**/skills/**/SKILL.md`. Each skill resides in its own directory containing the SKILL.md descriptor alongside any implementation files or platform-specific resources required for execution.