Garden Skill Structure and SKILL.md Components: A Complete Guide

A Garden Skill is a self-contained package under the skills/ directory that bundles declarative metadata, human-readable specifications, and executable assets to deliver reusable AI-driven capabilities within the Garden framework.

The ConardLi/garden-skills repository establishes a standardized format for packaging automation workflows and AI agents. Understanding the Garden Skill structure enables contributors to extend the ecosystem and allows users to discover, install, and execute capabilities through the Garden CLI.

Core Directory Layout of a Garden Skill

Each skill resides in a dedicated subdirectory under skills/ and follows a predictable schema that separates configuration from implementation logic.

Required Core Files

• manifest.json: Located at the skill root (e.g., skills/web-design-engineer/manifest.json), this file contains machine-readable metadata including the skill name, version, author, entry points, required agents, and searchable tags.
• SKILL.md: The canonical specification document (e.g., skills/web-design-engineer/SKILL.md) that describes the skill's intent, inputs, outputs, and execution workflow in structured Markdown.
• README.md: Quick-start documentation providing installation hints and high-level overviews. Localized versions like README.zh-CN.md support international users.

Optional Asset Directories

• references/: Domain-specific knowledge bases containing style guides or design references the skill may invoke during execution.
• agents/: YAML declarations of external AI providers (e.g., skills/web-design-engineer/agents/openai.yaml) required for the skill's operation.
• scripts/: Executable helpers written in JavaScript, Python, or Shell for custom preprocessing or postprocessing steps.
• templates/: Scaffoldable boilerplate files (HTML, CSS, Vite configs) that the skill can inject into target projects.

Anatomy of SKILL.md

SKILL.md serves as the heart of every Garden Skill, designed to be both human-editable and machine-parsable. The Garden framework reads this file's headings to construct execution graphs while developers use it as the primary reference documentation.

Standard Sections Within SKILL.md

1. Title & Brief Description: A concise one-sentence summary of the capability.
2. Motivation / Use-Case: Context explaining why the skill exists and typical scenarios for deployment.
3. Inputs: Detailed schema of required parameters, including data types and validation rules.
4. Outputs: Expected result formats and consumption patterns for downstream processes.
5. Workflow: Step-by-step procedural mapping that connects inputs to agents, scripts, and final outputs.
6. Dependencies: External services or libraries required, cross-referenced with manifest.json.
7. Example Interaction: Sample prompts and responses demonstrating a complete execution cycle.
8. Notes & Limitations: Edge cases, constraints, and roadmap items.

Configuration and Metadata

manifest.json Specification

The manifest.json file enables discoverability through the Garden CLI. It declares entry points and dependencies, allowing the framework to filter and list skills via commands like garden skill list without parsing the entire directory structure.

External Agent Definitions

Optional YAML files in the agents/ directory (such as skills/web-design-engineer/agents/openai.yaml) declare Large Language Model configurations. These files separate AI provider credentials from skill logic, enabling the same skill to run against different model providers based on environment configuration.

Executing Garden Skills

The Garden CLI consumes the structured files to orchestrate execution. Here are practical commands demonstrating how the framework interacts with the Garden Skill structure:

# Discover available skills by parsing manifest.json files

garden skill list

# Scaffold a project using templates from a specific skill

garden skill scaffold web-design-engineer --output ./my-design

# Execute a skill with validated inputs per SKILL.md specifications

garden skill run web-design-engineer \
  --input '{"theme":"retro-futurism","target":"website"}'

These commands reference the web-design-engineer skill located at skills/web-design-engineer/, reading its SKILL.md to validate input schemas and its manifest.json to resolve dependencies.

Summary

• A Garden Skill is a self-contained directory under skills/ containing manifest.json, SKILL.md, and optional asset folders.
• SKILL.md defines the contract between users and the framework, specifying inputs, outputs, and workflows in machine-readable Markdown.
• Optional directories (agents/, scripts/, templates/, references/) extend capabilities without bloating the core definition.
• The manifest.json file drives CLI discoverability and dependency resolution.
• This modular structure enables versioning, sharing, and plug-and-play integration into Garden-enabled workflows.

Frequently Asked Questions

What is the minimum required structure for a Garden Skill?

Every Garden Skill must include at least two files at its root: manifest.json for machine-readable metadata and SKILL.md for the human-readable specification. While optional directories like scripts/ or templates/ enhance functionality, the skill cannot be discovered or executed by the Garden CLI without these core files.

How does the Garden framework parse SKILL.md?

The framework reads the Markdown headings within SKILL.md to identify sections like Inputs, Outputs, and Workflow. This structured format allows the CLI to build an execution graph automatically while presenting the documentation to developers in a readable format.

Can a Garden Skill reference external AI models?

Yes. By placing YAML agent definitions in the optional agents/ directory (e.g., skills/web-design-engineer/agents/openai.yaml), skills can declare dependencies on external AI providers. The manifest.json references these agents, and the CLI configures them at runtime based on environment variables or local settings.

Where should I place helper scripts in a Garden Skill?

Custom processing logic belongs in the optional scripts/ directory at the skill root. The SKILL.md workflow section references these scripts by relative path, allowing the framework to invoke JavaScript, Python, or Shell utilities during skill execution.

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