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

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 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 contains YAML front-matter that declares machine-readable identifiers. The Skills CLI parses this at runtime to discover and catalog available capabilities.

---
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 and 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, 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

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

# 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

# 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, 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	Central catalog linking to every SKILL.md
skills/animate/RECIPES.md	Example of intra-skill documentation linking back to SKILL.md
skills/*/STANDARDS.md	Supporting standards documentation referenced by 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, skills/prototype/SKILL.md, and all other modules ensures predictable tooling behavior
• The repository's README.md treats these files as the canonical source of truth, linking directly to each 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 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 and 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.

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