# Garden Skill Structure and SKILL.md Components: A Complete Guide > Explore the structure of a Garden Skill and its SKILL.md components. Understand how these self-contained packages deliver reusable AI capabilities within the Garden framework. - Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills) - Tags: deep-dive - Published: 2026-08-28 --- **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`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json)**: Located at the skill root (e.g., [`skills/web-design-engineer/manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md)**: The canonical specification document (e.g., [`skills/web-design-engineer/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/SKILL.md)) that describes the skill's intent, inputs, outputs, and execution workflow in structured Markdown. - **[`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md)**: Quick-start documentation providing installation hints and high-level overviews. Localized versions like [`README.zh-CN.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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: ```bash # 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`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) to validate input schemas and its [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) to resolve dependencies. ## Summary - A Garden Skill is a self-contained directory under `skills/` containing [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json), [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md), and optional asset folders. - **[`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) for machine-readable metadata and [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/agents/openai.yaml)), skills can declare dependencies on external AI providers. The [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) workflow section references these scripts by relative path, allowing the framework to invoke JavaScript, Python, or Shell utilities during skill execution.