# How the Garden Skills Repository Is Structured for Each Agent Skill

> Discover the structured layout of the Garden Skills repository. Learn how each agent skill directory includes manifest.json, SKILL.md, and dedicated subfolders for efficient organization.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: architecture
- Published: 2026-08-30

---

**Every agent skill in the Garden Skills framework resides in a self-contained directory under `skills/` with a standardized layout that includes [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) for metadata, [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/web-design-engineer/manifest.json) declares version "1.3.0" and its compatibility matrix.

- **Skill Definition ([`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/skills/gpt-image-2/scripts/check-mode.js) for operating mode detection or [`skills/web-video-presentation/scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/scripts/scaffold.sh) for project bootstrapping.

- **Theme Assets (`themes/<theme-name>/`)**: Optional token files like [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css) or [`theme.json`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/check-mode.js) detecting generation versus editing modes, or [`scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/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:

```javascript
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:

```bash

# 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:

```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:

```bash

# 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`](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 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`](https://github.com/ConardLi/garden-skills/blob/main/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`](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 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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/README.zh-CN.md) and visual customization through the `themes/<theme-name>/` directory containing [`theme.json`](https://github.com/ConardLi/garden-skills/blob/main/theme.json) and [`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css) files, allowing the same skill logic to serve different languages and design systems.