Understanding the SKILL.md File Structure in Garden-Skills

The SKILL.md file is a declarative, machine-readable specification that defines a self-contained agent skill in the Garden-Skills framework, combining YAML front-matter for registration, markdown sections for behavior definition, and checkbox-based checklists for validation.

The SKILL.md file structure powers the Garden-Skills repository (ConardLi/garden-skills), acting as both documentation and executable instruction set for AI agents. Each skill resides in its own directory—such as skills/web-design-engineer/—and relies on a single markdown document to orchestrate complex design and coding workflows without containing any executable code itself. This architecture allows the skill to be versioned, edited, and reviewed like standard documentation while remaining fully interpretable by the framework's runtime.

What is SKILL.md?

A SKILL.md file serves as the master specification that defines a skill: a specialized agent capable of handling specific tasks like web design or code generation. Located at the root of each skill folder, this document follows a strict layout that the skill runner parses to drive agent behavior. The architecture is declarative and self-documenting, meaning the entire procedural logic lives inside markdown headings, tables, and lists rather than in external scripts.

Anatomy of the SKILL.md Specification

The document is divided into distinct functional blocks that guide the agent from request reception to final delivery.

YAML Front-Matter (Registration)

The file opens with machine-readable metadata consumed by the skill registry. In scripts/release/lib/skills.mjs, the loader extracts the name and description fields from lines 1-4 to register the skill under its canonical identifier.

---
name: web-design-engineer
description: "Build or redesign polished browser-rendered visual artifacts with HTML/CSS/JavaScript/React ..."
---

Scope Declaration

The Scope section establishes clear boundaries using a binary table format (✅ Applicable / ❌ Not applicable). This allows the orchestrator to route requests correctly, determining whether the current skill can handle the task or must delegate to another agent.

## Scope

✅ **Applicable**: Visual front-end deliverables and redesigns …
❌ **Not applicable**: Back-end APIs, CLI tools, …

Workflow and Checkpoints

The Workflow section contains numbered steps that the agent executes sequentially. Each step uses "### Step X:" headings and embeds checkpoints—mandatory pause points marked with 🛑 where the agent stops for user confirmation before proceeding.

### Step 3: Declare the Design System Before Writing Code

🛑 **Checkpoint 1**: After articulating Steps 3a + 3, stop. Tell the user …

Reference Routing

Rather than loading all rules at initialization, the skill uses dynamic resource loading. When a workflow step mentions an anchor like "Linear-style", the parser loads a single recipe file from references/style-recipes/<anchor>.md. This lightweight approach keeps the skill modular by loading only the specific rule sets required for the current task.

When the user names an anchor ("make it Linear-style") → read the single recipe file at
`references/style-recipes/<anchor>.md` (e.g., `references/style-recipes/linear.md`).

Pre-Delivery Validation

The Pre-delivery Checklist appears as a series of markdown checkboxes located at lines 442-457 that the agent audits before finalizing output. This ensures hard rules—such as prohibiting const styles = { … } in React files or restricting emoji usage unless brand-specified—are satisfied.

- [ ] **Step 0 ran** if any specific product/brand was named …
- [ ] **Design Read** exists …
- [ ] No `const styles = { … }` in React files …

How the Skill Runner Parses SKILL.md

The Garden-Skills runtime interprets the markdown structure through a five-phase process:

1. Registration Phase: The skill-loader (scripts/release/lib/skills.mjs) reads the YAML front-matter to expose the skill under its declared name.

2. Request Routing: The orchestrator consults the Scope table (lines 14-19) to verify the request falls within the skill's declared capabilities.

3. Sequential Execution: The runner processes the Workflow block (lines 22-73) step-by-step, respecting checkpoint markers that force user interaction.

4. Fallback Handling: If a request is vague, the agent consults the Fallback: Design Direction Advisor section (lines 90-124) to provide an alternate path rather than asking endless clarification questions.

5. Validation: The agent verifies every item in the Pre-delivery Checklist (lines 442-457) against hard rules in the Technical specifications (lines 334-447) and Design principles (lines 471-598) sections before completing the task.

Key Supporting Files

The SKILL.md operates within an ecosystem of auxiliary files located in the skill's references/ subdirectory:

• references/style-recipes/INDEX.md: Catalogs available style anchors like linear.md or aesop.md for dynamic loading during workflow execution.
• references/redesign-protocol.md: Defines classification rules for extensions versus overhauls, consulted by Step 2b of the workflow.
• references/critique-guide.md: Provides the scoring rubric used by Step 7 (Critique) to evaluate output quality according to the skill's aesthetic standards.

Summary

• The SKILL.md file structure combines YAML front-matter for machine registration with markdown sections for human-readable agent instructions.
• Scope tables enable intelligent request routing at lines 14-19, while Workflow sections with numbered steps and checkpoints govern execution flow starting at line 22.
• Dynamic reference loading from references/style-recipes/ keeps skills modular by loading only required rule sets on demand.
• Pre-delivery checklists enforce hard constraints through parseable markdown checkboxes at lines 442-457, ensuring quality gates are met before output delivery.
• The entire specification lives in skills/<skill-name>/SKILL.md and is parsed by scripts/release/lib/skills.mjs to create executable agents without embedded code.

Frequently Asked Questions

What makes SKILL.md different from a regular README?

Unlike static documentation, SKILL.md follows a strict structural contract parsed by the Garden-Skills runtime. While it uses standard markdown syntax—headings, checkboxes, and code blocks—the skill runner interprets specific sections like Scope, Workflow, and Checklists as executable instructions, making it a declarative program disguised as documentation rather than a passive reference file.

How does the skill loader recognize a new skill?

The skill loader (scripts/release/lib/skills.mjs) scans each skill directory for SKILL.md and extracts the YAML front-matter (specifically the name and description fields) from lines 1-4. This metadata registers the skill in the framework's registry, allowing the orchestrator to route requests to the correct agent based on the declared scope and name.

Can I add custom steps to the workflow?

Yes. The workflow section accepts any number of "### Step X:" headings. Each step is processed sequentially by the runtime. You can embed checkpoints using the 🛑 symbol followed by Checkpoint N to force the agent to pause for user confirmation, or reference auxiliary files in the references/ folder to expand the skill's capabilities without modifying core logic.

What happens if a skill violates its own pre-delivery checklist?

The pre-delivery checklist serves as a mandatory gate. If the agent cannot check every box—for example, if it detects const styles = { … } in a React file when the rules prohibit inline style objects—the skill must correct the violation before finalizing output. The checkboxes are not merely suggestions; they are parseable validation rules enforced by the skill runner before task completion.

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