# What Is the Purpose of the SKILL.md File in Each Skill Module?

> Discover the purpose of SKILL.md files in the emilkowalski/skills repository. Learn how this manifest file combines YAML and markdown for machine and human understanding.

- Repository: [Emil Kowalski/skills](https://github.com/emilkowalski/skills)
- Tags: deep-dive
- Published: 2026-08-07

---

**SKILL.md serves as the manifest, metadata source, and comprehensive documentation for every skill module in the emilkowalski/skills repository, combining YAML front-matter for machine discovery with detailed markdown instructions for human or AI execution.**

Each skill module in this open-source framework contains exactly one [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) file that functions as its **canonical source of truth**. The file's dual structure—machine-parseable headers followed by human-readable guidance—enables both automated tooling and developers to understand and execute a skill correctly without external configuration.

## The Three Core Functions of SKILL.md

### 1. Metadata Declaration via YAML Front-Matter

The top of every [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) contains YAML front-matter that declares machine-readable identifiers. The Skills CLI parses this at runtime to discover and catalog available capabilities.

```yaml
---
name: review-animations
description: Reviews animation and motion code against a high craft bar …
disable-model-invocation: true
---

```

Key fields include:

- **`name`** – The unique identifier used to invoke the skill via CLI
- **`description`** – Shown in help listings and skill discovery
- **`disable-model-invocation`** – Boolean flag that restricts whether the skill may internally call a language model

This pattern appears consistently across skills like [`skills/review-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/SKILL.md) and [`skills/prototype/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/prototype/SKILL.md).

### 2. Human-Readable Specification

Everything below the front-matter constitutes the **executable documentation** that explains:

- The skill's **single purpose** (e.g., "review animation and motion code" or "build multiple UI variants")
- **Operating posture** and hard rules that constrain behavior
- **Workflow phases** and expected output formats
- **Auxiliary resources** (links to [`STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/STANDARDS.md), [`PICKER.md`](https://github.com/emilkowalski/skills/blob/main/PICKER.md), or other skill-specific references)

AI assistants and developers read this section to understand *how* to execute the skill correctly according to the author's intent.

### 3. Self-Contained Reference for the CLI

The Skills CLI (`npx skills@latest`) performs runtime scanning of `skills/*/SKILL.md` files to:

1. Parse front-matter and auto-register skills under their declared `name`
2. Extract `description` for help listings
3. Respect `disable-model-invocation` flags when determining execution permissions

Because behavior and documentation coexist in one file, the CLI presents accurate usage summaries without additional code or external registries.

## Practical Examples: Consuming SKILL.md Programmatically

### Loading Skill Metadata with Node.js

```javascript
import fs from 'fs';
import matter from 'gray-matter';               // npm i gray-matter

function loadSkillMeta(skillDir) {
  const path = `${skillDir}/SKILL.md`;
  const raw = fs.readFileSync(path, 'utf8');
  const { data, content } = matter(raw);        // data = front-matter, content = markdown body
  return { meta: data, doc: content };
}

// Example: load the "prototype" skill
const { meta, doc } = loadSkillMeta('skills/prototype');
console.log(meta.name);        // → prototype
console.log(meta.description); // → Build multiple genuinely different versions …

```

### Listing Available Skills via CLI

```bash

# After installing the package

npx skills@latest list

# Sample output (derived from each SKILL.md front-matter):

#   emil-design-eng   – The main skill that consists of mostly animation …

#   animate            – Builds an animation from scratch …

#   review-animations  – Review your animations in a strict way …

```

### Executing a Specific Skill

```bash

# Run "review-animations" on current project

npx skills@latest run review-animations "Please review the animation in src/button.tsx"

```

The CLI resolves `review-animations` by reading [`skills/review-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/SKILL.md), extracts configuration, then executes the framework logic.

## Key Files in the Repository Structure

| File | Role |
|------|------|
| `skills/*/SKILL.md` | Manifest + human-readable specification for each skill |
| [`README.md`](https://github.com/emilkowalski/skills/blob/main/README.md) | Central catalog linking to every [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) |
| [`skills/animate/RECIPES.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/RECIPES.md) | Example of intra-skill documentation linking back to [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) |
| `skills/*/STANDARDS.md` | Supporting standards documentation referenced by [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) |

## Summary

- **SKILL.md unifies identity, configuration, and procedural documentation** in a single discoverable artifact
- **YAML front-matter** enables machine discovery and CLI integration without external registries
- **Markdown body** provides exhaustive guidance for correct skill execution by humans or AI systems
- **Consistent structure** across [`skills/review-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/SKILL.md), [`skills/prototype/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/prototype/SKILL.md), and all other modules ensures predictable tooling behavior
- The repository's [`README.md`](https://github.com/emilkowalski/skills/blob/main/README.md) treats these files as the **canonical source of truth**, linking directly to each [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) for authoritative skill documentation

## Frequently Asked Questions

### What happens if a SKILL.md file is missing the name field?

The CLI will fail to register the skill at runtime. The `name` field in the YAML front-matter is mandatory because it serves as the unique invocation key for commands like `npx skills@latest run <name>`.

### Can a skill module contain multiple SKILL.md files?

No. The framework expects exactly one [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) per skill directory. The CLI scans `skills/*/SKILL.md` using glob patterns, so additional files would be ignored or cause unpredictable behavior.

### How does disable-model-invocation affect skill execution?

When set to `true`, this flag prevents the skill runtime from internally invoking a language model. This is useful for deterministic, rules-based skills that operate entirely through coded logic rather than generative AI.

### Where can I find examples of well-structured SKILL.md files?

Reference [`skills/review-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/SKILL.md) and [`skills/prototype/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/prototype/SKILL.md) in the emilkowalski/skills repository. Both demonstrate proper front-matter syntax, comprehensive workflow documentation, and appropriate linking to supporting standards files.