# Understanding the Anatomy of a Garden Skill: File Structure and Components > Explore the anatomy of a Garden Skill. Learn how manifest.json and SKILL.md files enable AI agents to discover and execute tasks safely and deterministically. - Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills) - Tags: deep-dive - Published: 2026-08-31 --- **A Garden Skill is a self-contained folder consisting of a [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) for metadata and a [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file containing the workflow definition, enabling AI agents to discover and execute deterministic tasks without running arbitrary code.** The ConardLi/garden-skills repository defines a standardized format for packaging AI capabilities into portable, version-controlled units. Understanding the anatomy of a Garden Skill allows developers to create modular workflows that coding agents can load on-demand using a predictable file structure. Each skill follows a deliberately simple layout so agents can parse intent, workflow, and assets without any runtime execution. ## Required Core Components Every Garden Skill must include two specific files that form the foundation of the anatomy of a Garden Skill. ### manifest.json (Skill Metadata) Located at the root of the skill folder, [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) declares the skill's identity, version, category, and compatibility. According to the source code in [`skills/web-design-engineer/manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/manifest.json), this file contains fields like `name`, `version`, `category`, and `description` that help agents determine when to activate the skill. ```json { "name": "web-design-engineer", "version": "1.0.0", "category": "Design", "description": "Professional web design and UI/UX engineering", "compat": ["claude-code", "cursor"] } ``` ### SKILL.md (Workflow Definition) The [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file serves as the executable specification. It contains a YAML front-matter block (delimited by `---`) repeating the name and description, followed by a Markdown body defining the workflow steps, hard rules, and checkpoints. The web-design-engineer skill implements its full workflow in [`skills/web-design-engineer/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/SKILL.md), including step-by-step instructions the agent must follow. ```markdown --- name: web-design-engineer description: "Professional web design and UI/UX engineering" --- # Web Design Engineer ## Overview Explain the high-level purpose and when to invoke this skill. ## Workflow 1. **Step 0** – Verify facts (optional). 2. **Step 1** – Gather input. 3. **Step 2** – Process / generate output. 4. **Step 3** – Validate and return results. ## Hard Rules - Never fabricate data. - Always ask for clarification before proceeding. ``` ## Optional Resources and Supporting Assets Beyond the required files, the anatomy of a Garden Skill supports several optional directories that extend functionality. ### Human Documentation (README.md) A [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md) provides developer-friendly usage instructions and installation guidelines. The repository's top-level README links to individual skill READMEs, such as [`skills/web-design-engineer/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/README.md), offering human-readable context beyond the agent-oriented SKILL.md. ### Reference Material (references/) The `references/` directory stores extensive documentation like design recipes, anti-pattern guides, and technical specifications. For example, [`skills/web-design-engineer/references/style-recipes/INDEX.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/references/style-recipes/INDEX.md) contains design-direction recipes that the skill loads on-demand during execution. ### Deterministic Scripts (scripts/) Skills may include helper utilities in a `scripts/` folder, though these are deterministic tools rather than arbitrary executables. The gpt-image-2 skill ships with [`skills/gpt-image-2/scripts/generate.js`](https://github.com/ConardLi/garden-skills/blob/main/skills/gpt-image-2/scripts/generate.js), a JavaScript helper suite that performs specific, safe operations like image generation tasks. ### Static Assets (assets/) Templates, fonts, icons, and theme contracts reside in an `assets/` directory. The beautiful-article skill defines theme contracts in `skills/beautiful-article/theme-profiles/`, allowing the skill to reference consistent styling resources when producing output. ### Environment Configuration (.env.example) If a skill requires secrets or configuration variables, it includes a `.env.example` file at the root as a placeholder template. This file documents expected environment variables without shipping actual values, ensuring secure deployment practices. ## How Agents Discover and Load Skills When scanning a workspace, agents look for folders containing a [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file. The YAML front-matter inside this file, combined with the [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json), tells the agent three critical things: - **When** to activate: The `description` field matches against user requests. - **What** to use: The `category` and `compat` fields define supported agents (e.g., `"claude-code"`, `"cursor"`). - **How** to execute: The body of [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) outlines the step-wise workflow and hard rules. Skills installed via the CLI are placed under agent-specific directories like `.claude/skills/` or `.agents/skills/`, while the same layout supports raw Git clones or submodule vendoring. ## Real-World Examples in the Repository The ConardLi/garden-skills repository demonstrates the anatomy of a Garden Skill through several production implementations: - **Web Design Engineer**: Uses [`skills/web-design-engineer/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/SKILL.md) for workflow logic, [`skills/web-design-engineer/manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/manifest.json) for metadata, and `skills/web-design-engineer/references/style-recipes/` for design documentation. - **KB Retriever**: Implements retrieval workflows with PDF/Excel safety checks in [`skills/kb-retriever/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/kb-retriever/SKILL.md). - **GPT-Image-2**: Combines workflow definitions with deterministic scripting via [`skills/gpt-image-2/scripts/generate.js`](https://github.com/ConardLi/garden-skills/blob/main/skills/gpt-image-2/scripts/generate.js). - **Beautiful Article**: Leverages `skills/beautiful-article/theme-profiles/` for asset management and consistent theming. ## Summary - A Garden Skill requires exactly two files: [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) for metadata and [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) for the workflow definition. - Optional directories include `references/` for documentation, `scripts/` for deterministic helpers, `assets/` for static files, and `.env.example` for configuration templates. - Agents discover skills by detecting [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) files and parsing their YAML front-matter to determine activation criteria. - The structure ensures AI agents can interpret and execute skills without running arbitrary code or accessing uncontrolled external secrets. ## Frequently Asked Questions ### What files are strictly required for a Garden Skill? Only [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) and [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) are mandatory. The [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) provides discovery metadata, while [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) contains the YAML front-matter and step-by-step workflow instructions. All other components are optional enhancements. ### How does an AI agent know when to activate a specific skill? The agent matches the user's request against the `description` field in both [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) and the YAML header of [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md). The `category` and `compat` fields further filter which agents can execute the skill based on their capabilities. ### Can Garden Skills execute arbitrary code on my system? No. While skills may include deterministic helper scripts in the `scripts/` directory, these are designed as safe, specific utilities rather than arbitrary execution environments. The skill system prevents uncontrolled code execution by design. ### Where should I install Garden Skills so my agent can find them? Place skill folders under agent-specific directories such as `.claude/skills/`, `.agents/skills/`, or `.codex/skills/` when using the skills CLI. Alternatively, you can use raw Git clones or Git submodules in these locations, provided the folder contains the required [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file.