# What Is the Purpose of the SKILL.md File in Garden Skills?

> Discover the purpose of the SKILL.md file in Garden Skills. This file acts as a human-readable blueprint and machine-parseable contract for reusable AI prompts.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: how-to-guide
- Published: 2026-08-30

---

**SKILL.md serves as the declarative specification that defines each reusable design-oriented AI prompt in Garden Skills, functioning as both a human-readable workflow blueprint and a machine-parseable contract for automated tooling.**

Garden Skills organizes reusable AI capabilities into discrete, versioned units called "skills." At the heart of each skill lies the [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file, which acts as the single source of truth that bridges human design intent with automated execution pipelines. According to the repository's architecture, this file establishes the contract between the infrastructure and the AI agent performing the work.

## Core Architectural Roles of SKILL.md

The [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file fulfills three distinct architectural purposes within the Garden Skills framework. These roles enable both manual interaction and automated processing of skill definitions.

### Metadata and Skill Discovery

The top-level YAML frontmatter in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) provides the essential identifiers that the repository's tooling parses to index and catalogue available skills. This metadata block includes fields such as `name` and `description`, which allow scripts to generate skill registries without parsing the entire document body.

In [`skills/web-design-engineer/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/SKILL.md), this YAML block enables the automated discovery system to present the skill to end-users or other agents. The `scripts/release/list-skills.mjs` utility specifically scans for these frontmatter blocks to build the skill inventory.

### Behavioral Workflow Blueprint

Beyond metadata, the markdown body of [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) contains the complete operational workflow that guides AI agents through task execution. This includes step-by-step instructions for **verification of facts**, **requirement gathering**, **design-system declaration**, and **staged checkpoints** through v0 draft, full build, and verification phases.

By encoding the process in plain text, the skill becomes both human-readable and machine-executable without additional code compilation. The **Pre-delivery Checklist** section within [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) ensures quality control standards are maintained across all skill executions.

### Self-Contained Reference Hub

Each skill resides in its own isolated folder, with [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) serving as the authoritative reference that links to ancillary assets. The file references [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) and other theme files or reference recipes, instructing the runner which files to copy or generate during a release.

This design keeps skills modular, simplifies versioning, and enables the automated scripts in `scripts/release/` to package a skill without external configuration. The [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) effectively declares *who* the skill is, *what* it does, *how* it should behave, and *what* artifacts belong to it.

## Automating Skill Management with SKILL.md

The Garden Skills repository leverages [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) files to power its release and distribution automation. Two critical scripts in `scripts/release/` demonstrate how the specification drives infrastructure operations.

### Indexing Skills via list-skills.mjs

The `list-skills.mjs` script reads each [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) to build a comprehensive summary table of available capabilities. It extracts the YAML frontmatter to generate machine-readable indexes:

```javascript
// scripts/release/list-skills.mjs (excerpt)
import { readFile } from 'fs/promises';
import { glob } from 'fast-glob';

async function getSkillSummaries() {
  const skillPaths = await glob('skills/**/SKILL.md');
  const summaries = [];

  for (const path of skillPaths) {
    const content = await readFile(path, 'utf8');
    const meta = content.match(/^---\n([\s\S]*?)\n---/);
    if (meta) {
      const yaml = yamlParse(meta[1]);          // parses name/description
      summaries.push({
        name: yaml.name,
        description: yaml.description,
        file: path,
      });
    }
  }
  return summaries;
}

```

This extraction pattern allows the repository to maintain a dynamic catalogue without manual bookkeeping, parsing the `name` and `description` fields from each skill's specification.

### Packaging Distributions via pack-skill.mjs

When preparing skills for distribution, `pack-skill.mjs` uses the [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) referenced from [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) to create distributable ZIP archives. The script reads the machine-readable manifest to determine packaging boundaries:

```javascript
// scripts/release/pack-skill.mjs (excerpt)
import { readFile, writeFile } from 'fs/promises';
import archiver from 'archiver';

async function packSkill(skillDir) {
  const manifest = JSON.parse(
    await readFile(`${skillDir}/manifest.json`, 'utf8')
  );
  const output = fs.createWriteStream(`${manifest.name}.zip`);
  const archive = archiver('zip');

  archive.pipe(output);
  archive.directory(skillDir, false);
  await archive.finalize();
}

```

The relationship between [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) and [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) ensures that human-readable documentation remains synchronized with machine-readable packaging instructions.

## Summary

- **SKILL.md** acts as the declarative specification for each reusable AI prompt in the Garden Skills repository, combining metadata, workflow instructions, and asset references in a single document.

- The YAML frontmatter provides **discovery metadata** that `scripts/release/list-skills.mjs` parses to generate skill catalogues automatically.

- The markdown body serves as a **behavioral blueprint** containing step-by-step instructions, quality checklists, and workflow stages that AI agents follow during execution.

- Each [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) functions as a **self-contained reference hub** within its skill directory, linking to [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) and enabling automated packaging via `scripts/release/pack-skill.mjs`.

- This design pattern keeps skills isolated, versionable, and simultaneously readable by humans and executable by machines without additional compilation steps.

## Frequently Asked Questions

### What information is contained in the YAML frontmatter of SKILL.md?

The YAML frontmatter contains discovery metadata including the skill's `name` and `description`. In [`skills/web-design-engineer/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/SKILL.md), this block appears at the top of the file delimited by triple dashes (`---`). The `scripts/release/list-skills.mjs` utility specifically targets this section using regex patterns to extract structured data for indexing purposes, enabling automated catalogue generation without parsing the full workflow content.

### How does SKILL.md differ from manifest.json in Garden Skills?

While [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) serves as the comprehensive human-readable specification containing workflows and instructions, [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) provides the machine-readable manifest used for packaging and publishing. The [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file links to or references the [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) to tell automated systems which files comprise the skill distribution. According to the source code in `pack-skill.mjs`, the manifest determines the exact boundaries and naming conventions for ZIP archives during the release process.

### Can SKILL.md be executed directly by AI agents, or is it purely documentation?

[`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) functions as executable documentation that AI agents process directly to perform skills. The markdown body contains the complete behavioral blueprint including verification steps, requirement gathering protocols, and pre-delivery checklists. Because the workflow is encoded in plain text rather than compiled code, AI agents can parse and execute these instructions without intermediate translation layers, making the skill both human-readable and machine-executable.

### Where are SKILL.md files located within the Garden Skills repository structure?

Each [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) resides in its own skill-specific subdirectory under the `skills/` directory. For example, the Web Design Engineer skill is located at [`skills/web-design-engineer/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/SKILL.md). This co-location with ancillary assets like [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) and theme files enables the self-contained reference pattern, allowing `list-skills.mjs` to discover all skills using the glob pattern `skills/**/SKILL.md` while maintaining isolation between different skill implementations.