# Anatomy of a Skill in Garden Skills: File Structure and Runtime Components

> Explore the anatomy of a skill in Garden Skills. Discover its file structure including SKILL.md, manifest.json, scripts, and references. Understand its runtime components for efficient AI development.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: internals
- Published: 2026-09-01

---

**A single skill in Garden Skills is a self‑contained package consisting of a [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) specification, a [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) descriptor, a `scripts/` directory with mode detection and execution logic, and a `references/` tree of prompt templates—all following a strict, reproducible anatomy across every skill.**

The `ConardLi/garden-skills` repository implements a modular architecture where every skill (such as `gpt-image-2`, `web-video-presentation`, or `beautiful-article`) follows an identical directory layout and runtime contract. This standardized anatomy allows Garden to automatically discover, invoke, and present capabilities to any compatible AI agent.

## Core Components of a Skill

Every skill directory under `skills/<skill-name>/` contains the same set of files and subdirectories, forming a clear separation between human documentation, machine metadata, runtime scripts, and prompt libraries.

### SKILL.md – The Human‑Readable Contract

The [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file serves as the authoritative specification for the skill. It includes YAML front‑matter defining the `name` and `description`, followed by sections that explain **run‑mode detection**, **core workflow**, **environment variables**, **output conventions**, and the **prompt‑template index**.

In [`skills/gpt-image-2/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/gpt-image-2/SKILL.md), the document specifies how the skill detects whether it can run locally (Mode A), delegate to host‑native tools (Mode B), or operate as an advisor (Mode C). It also documents the expected directory conventions, such as the creation of `garden-gpt-image-2/prompt/` and `garden-gpt-image-2/image/` at runtime.

### manifest.json – Machine‑Readable Metadata

The [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) file provides the machine‑readable contract that Garden uses to index and invoke the skill. It contains the `name`, `version`, `category`, and `description`, along with a `compat` field that enumerates which agents can execute the skill.

According to the source code in [`skills/gpt-image-2/manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/gpt-image-2/manifest.json), the compatibility list tells Garden whether Claude, Cursor, Codex, Gemini, or Opencode can invoke this skill, enabling cross‑agent portability.

### scripts/ – Runtime Logic and Mode Detection

The `scripts/` directory contains the executable JavaScript files that implement the skill’s behavior and environment inspection.

- **[`check-mode.js`](https://github.com/ConardLi/garden-skills/blob/main/check-mode.js)** – Inspects environment variables (`ENABLE_GARDEN_IMAGEGEN`, `OPENAI_API_KEY`) and host‑native tooling to report the current runtime mode (A, B, or C). Located at [`skills/gpt-image-2/scripts/check-mode.js`](https://github.com/ConardLi/garden-skills/blob/main/skills/gpt-image-2/scripts/check-mode.js).
- **[`generate.js`](https://github.com/ConardLi/garden-skills/blob/main/generate.js)** – Implements the text‑to‑image flow for Mode A by calling the OpenAI‑compatible `/images/generations` endpoint.
- **[`edit.js`](https://github.com/ConardLi/garden-skills/blob/main/edit.js)** – Implements the image‑editing flow for Mode A by calling `/images/edits`.
- **[`shared.js`](https://github.com/ConardLi/garden-skills/blob/main/shared.js)** – Provides helper utilities for request building, response handling, environment‑variable parsing, and prompt rendering.

### references/ – Prompt Template Library

The `references/` directory houses a hierarchical collection of Markdown prompt templates organized by category (e.g., `ui-mockups/`, `product-visuals/`, `technical-diagrams/`). Each file contains replaceable `{argument ...}` placeholders that the scripts populate at runtime.

For example, [`skills/gpt-image-2/references/ui-mockups/live-commerce-ui.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/gpt-image-2/references/ui-mockups/live-commerce-ui.md) defines a template that [`shared.js`](https://github.com/ConardLi/garden-skills/blob/main/shared.js) can render with specific product names and prices.

### Runtime Output Directories

When a skill executes, it creates standardized output folders:

- **`garden-<skill-name>/prompt/`** – Stores the rendered prompt text (all modes).
- **`garden-<skill-name>/image/`** – Stores generated binary assets (Mode A only).

These paths are documented in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) and are created dynamically by the scripts during execution.

## The Three Runtime Modes

The anatomy supports three distinct execution strategies determined by [`check-mode.js`](https://github.com/ConardLi/garden-skills/blob/main/check-mode.js):

1. **Mode A (Garden Local)** – The skill has full API access (e.g., `OPENAI_API_KEY` is present) and executes the generation logic directly via [`generate.js`](https://github.com/ConardLi/garden-skills/blob/main/generate.js) or [`edit.js`](https://github.com/ConardLi/garden-skills/blob/main/edit.js).
2. **Mode B (Host‑Native Delegation)** – The skill renders the prompt but delegates actual execution to host‑native tools (local Stable Diffusion, Photoshop scripts, etc.).
3. **Mode C (Advisor‑Only)** – The skill acts as a prompt engineer, saving the rendered text for the user to paste into an external tool.

## Practical Usage Examples

Detect the current runtime mode:

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

```

For JSON output suitable for piping:

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

```

Generate an image in Mode A:

```bash
node skills/gpt-image-2/scripts/generate.js \
  --prompt "A cute baby sea otter playing on a sunny beach" \
  --size 1024x1024 \
  --quality high

```

Edit an existing image in Mode A:

```bash
node skills/gpt-image-2/scripts/edit.js \
  --image assets/source.png \
  --prompt "Replace the background with a clean studio scene"

```

Handle Mode B or C programmatically:

```bash
MODE=$(node skills/gpt-image-2/scripts/check-mode.js --json | jq -r .mode)
PROMPT=$(node -e "require('./skills/gpt-image-2/scripts/shared.js').renderPrompt('live-commerce-ui', {product:'Smartwatch', price:'$199'})")

if [ "$MODE" = "B" ]; then
  host-image-tool --prompt "$PROMPT"
elif [ "$MODE" = "C" ]; then
  echo "Prompt ready for manual execution:"
  echo "$PROMPT"
fi

```

## Summary

- Every skill follows an identical **anatomy** defined by [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md), [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json), `scripts/`, and `references/`.
- **[`check-mode.js`](https://github.com/ConardLi/garden-skills/blob/main/check-mode.js)** determines whether the skill runs locally (Mode A), delegates to host tools (Mode B), or operates as an advisor (Mode C).
- **[`generate.js`](https://github.com/ConardLi/garden-skills/blob/main/generate.js)** and **[`edit.js`](https://github.com/ConardLi/garden-skills/blob/main/edit.js)** implement the core API workflows for Mode A, while **[`shared.js`](https://github.com/ConardLi/garden-skills/blob/main/shared.js)** provides common utilities.
- **`references/`** contains categorized prompt templates with placeholder substitution handled by the runtime.
- Outputs are written to **`garden-<skill-name>/`** subdirectories, with paths standardized across all skills.

## Frequently Asked Questions

### What files are required to create a new skill in Garden Skills?

A minimal skill requires four components: a [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file with YAML front‑matter describing the skill, a [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) declaring compatibility and metadata, a `scripts/` directory containing at minimum [`check-mode.js`](https://github.com/ConardLi/garden-skills/blob/main/check-mode.js) for environment detection, and a `references/` directory with at least one prompt template. Optional localized README files (e.g., [`README.zh-CN.md`](https://github.com/ConardLi/garden-skills/blob/main/README.zh-CN.md)) can accompany these for regional documentation.

### How does the mode detection system work in Garden Skills?

The [`scripts/check-mode.js`](https://github.com/ConardLi/garden-skills/blob/main/scripts/check-mode.js) file inspects environment variables such as `ENABLE_GARDEN_IMAGEGEN` and `OPENAI_API_KEY`, along with the availability of host‑native image tools. It returns a mode identifier (A, B, or C) that determines whether the skill executes the API call itself, delegates to external software, or simply prepares a prompt for manual execution.

### Can Garden Skills be used with any AI agent or IDE?

Yes, provided the agent is listed in the `compat` field of [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json). The repository explicitly supports Claude, Cursor, Codex, Gemini, and Opencode agents. Because the skill anatomy is standardized and language‑agnostic at the interface level, any tool capable of executing Node.js scripts or reading the generated prompts can consume the skill.

### Where are generated outputs stored when running a skill?

At runtime, skills create directories prefixed with `garden-<skill-name>/`. Specifically, the `prompt/` subdirectory stores rendered text prompts for all modes, while the `image/` subdirectory stores binary assets generated during Mode A execution. These paths are defined in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) and are automatically managed by the scripts in `scripts/`.