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

A single skill in Garden Skills is a self‑contained package consisting of a SKILL.md specification, a 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 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, 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 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, 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 – 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.
• generate.js – Implements the text‑to‑image flow for Mode A by calling the OpenAI‑compatible /images/generations endpoint.
• edit.js – Implements the image‑editing flow for Mode A by calling /images/edits.
• 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 defines a template that 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 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:

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

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

For JSON output suitable for piping:

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

Generate an image in Mode A:

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:

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:

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, manifest.json, scripts/, and references/.
• 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 and edit.js implement the core API workflows for Mode A, while 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 file with YAML front‑matter describing the skill, a manifest.json declaring compatibility and metadata, a scripts/ directory containing at minimum 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) can accompany these for regional documentation.

How does the mode detection system work in Garden Skills?

The 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. 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 and are automatically managed by the scripts in scripts/.

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