Understanding the Anatomy of a Garden Skill: File Structure and Components

A Garden Skill is a self-contained folder consisting of a manifest.json for metadata and a 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 declares the skill's identity, version, category, and compatibility. According to the source code in 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.

{
  "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 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, including step-by-step instructions the agent must follow.

---
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 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, 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 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, 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 file. The YAML front-matter inside this file, combined with the 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 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 for workflow logic, 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.
• GPT-Image-2: Combines workflow definitions with deterministic scripting via 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 for metadata and 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 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 and SKILL.md are mandatory. The manifest.json provides discovery metadata, while 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 and the YAML header of 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 file.

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