How the Garden Skills Repository Is Structured for Each Agent Skill

Every agent skill in the Garden Skills framework resides in a self-contained directory under skills/ with a standardized layout that includes manifest.json for metadata, SKILL.md for workflow definitions, and dedicated subfolders for references, scripts, themes, and templates.

The Garden Skills repository organizes autonomous capabilities into modular, discoverable units. Each agent skill follows a strict directory convention under skills/<skill-name>/ that enables the framework to dynamically load, execute, and extend capabilities without coupling to specific LLM backends, making the repository structure essential for horizontal scalability.

Standard Directory Layout for Agent Skills

Each skill directory contains seven standard component types that make the skill discoverable, runnable, and extensible:

• Manifest (manifest.json): Located at skills/<skill-name>/manifest.json, this file stores machine-readable metadata including the skill name, semantic version, category, and a compat array that declares which LLM backends (Claude, Cursor, Gemini, etc.) can invoke the skill. For example, web-design-engineer/manifest.json declares version "1.3.0" and its compatibility matrix.

• Skill Definition (SKILL.md): Found at skills/<skill-name>/SKILL.md, this file combines YAML front-matter with Markdown to define the human-readable workflow and step-by-step instructions the agent follows at runtime.

• Readme (README.md): Quick-start documentation and usage tips located at skills/<skill-name>/README.md, often with localized variants such as README.zh-CN.md for internationalization support.

• References (references/): A directory containing design systems, style recipes, prompt templates, or domain-specific knowledge bases that the skill consults at runtime. For instance, web-video-presentation/references/CHAPTER-CRAFT.md provides content structure guidelines.

• Scripts (scripts/): Helper utilities that contain concrete execution logic, such as skills/gpt-image-2/scripts/check-mode.js for operating mode detection or skills/web-video-presentation/scripts/scaffold.sh for project bootstrapping.

• Theme Assets (themes/<theme-name>/): Optional token files like tokens.css or theme.json that define color palettes and typography for UI-heavy skills, enabling visual customization without touching core logic. Example: web-video-presentation/themes/warm-keynote/theme.json.

• Templates (templates/): Optional boilerplate files and scaffold code used when the skill initializes new projects, such as web-video-presentation/templates/vite.config.ts for Vite and React setups.

How Skills Are Discovered and Executed

The Garden Skills framework assembles agent capabilities at runtime through a four-phase process:

1. Discovery: The agent enumerates every directory under skills/ and parses each manifest.json to identify available capabilities and backend compatibility.

2. Execution: When a user request matches a skill's domain, the agent loads the corresponding SKILL.md to obtain the YAML-defined workflow, which may reference files in the references/ directory for specialized knowledge.

3. Runtime Helpers: The skill invokes scripts from its scripts/ folder to perform concrete operations, such as check-mode.js detecting generation versus editing modes, or scaffold.sh bootstrapping a Vite + React project skeleton.

4. Customization: The framework applies theme assets from themes/<theme-name>/ to inject design tokens into the workflow, allowing the same skill to render multiple visual styles without code changes.

Working with Skill Components

The following examples demonstrate how to interact with the Garden Skills repository structure programmatically.

Loading a Skill Manifest

Use Node.js to parse the JSON metadata that drives skill discovery:

import { readFileSync } from 'fs';
import path from 'path';

function loadManifest(skillName) {
  const manifestPath = path.join(
    __dirname, 'skills', skillName, 'manifest.json'
  );
  const raw = readFileSync(manifestPath, 'utf-8');
  return JSON.parse(raw);
}

// Example: read the Web-Design-Engineer manifest
const webDesign = loadManifest('web-design-engineer');
console.log(webDesign.name, webDesign.version);
// → "web-design-engineer" "1.3.0"

Detecting Skill Modes

Invoke helper scripts directly to determine runtime behavior:

# Detect which mode the skill should run in

node skills/gpt-image-2/scripts/check-mode.js --json

# Sample output:

# {"mode":"A","recommendation":"Run generate.js"}

Accessing Reference Templates

Load domain-specific knowledge from the references directory using Python:

import pathlib

def load_template(skill, category, name):
    tmpl = pathlib.Path(__file__).parent / f"skills/{skill}/references/{category}/{name}.md"
    return tmpl.read_text(encoding='utf-8')

prompt_template = load_template(
    'gpt-image-2', 'ui-mockups', 'live-commerce-ui.md'
)
print(prompt_template[:200])   # preview first 200 characters

Bootstrapping Projects with Skill Scaffolds

Execute scaffolding scripts to initialize new projects with skill-specific templates:

# Run the scaffold script with a chosen theme

bash skills/web-video-presentation/scripts/scaffold.sh \
  ./my-video-project \
  --theme=warm-keynote

# The script creates a Vite+React+TS skeleton under ./my-video-project

Summary

• Self-contained structure: Each agent skill lives in its own skills/<skill-name>/ directory with all required artifacts, enabling horizontal scaling of the repository.
• Standardized contract: Every skill must provide manifest.json for metadata and SKILL.md for workflow definitions, creating a uniform API surface for the framework.
• Modular assets: The references/, scripts/, themes/, and templates/ directories decouple domain knowledge, executable logic, visual design, and boilerplate code.
• Runtime assembly: The framework discovers skills by reading manifests, executes workflows from SKILL.md, and delegates specific operations to helper scripts and theme assets.

Frequently Asked Questions

What files define an agent skill in the Garden Skills repository?

Every agent skill requires manifest.json for machine-readable metadata and SKILL.md for the workflow definition written in YAML front-matter plus Markdown. These two files form the minimal contract that the Garden Skills framework requires to discover and execute a skill.

How does the Garden Skills framework discover available agent skills?

The framework enumerates all directories under skills/ and parses each manifest.json file to extract the skill name, version, category, and the compat array that specifies which LLM backends can safely invoke the skill.

What is the purpose of the references directory in a Garden Skills agent skill?

The references/ directory stores domain-specific knowledge bases such as design-system recipes, style guides, and prompt templates that the skill consults during execution. For example, web-video-presentation/references/CHAPTER-CRAFT.md contains content structure guidelines used when generating interactive videos.

Can agent skills include localized documentation and visual themes?

Yes, skills support localization through README variants like README.zh-CN.md and visual customization through the themes/<theme-name>/ directory containing theme.json and tokens.css files, allowing the same skill logic to serve different languages and design systems.

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