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

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 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 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 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, 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 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 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 serving as the authoritative reference that links to ancillary assets. The file references 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 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 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 to build a comprehensive summary table of available capabilities. It extracts the YAML frontmatter to generate machine-readable indexes:

// 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 referenced from SKILL.md to create distributable ZIP archives. The script reads the machine-readable manifest to determine packaging boundaries:

// 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 and 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 functions as a self-contained reference hub within its skill directory, linking to 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, 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 serves as the comprehensive human-readable specification containing workflows and instructions, manifest.json provides the machine-readable manifest used for packaging and publishing. The SKILL.md file links to or references the 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 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 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. This co-location with ancillary assets like 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.

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