Garden Skills Repository Structure: A Complete Guide to the Modular AI Skill Collection

The Garden Skills repository follows a modular, self-contained architecture where each AI skill resides in its own directory under skills/ with standardized internal files (SKILL.md, README.md, references/, scripts/, assets/), while separate website/, demo/, and scripts/ directories handle presentation, examples, and release automation.

The Garden Skills repository (ConardLi/garden-skills) is a curated collection of AI coding agent capabilities designed for Claude Code, Cursor, and similar environments. Understanding the Garden Skills repository structure is essential for developers looking to install individual skills, contribute new capabilities, or integrate the collection into existing agent workflows. The project uses a clear, modular pattern so each skill can be installed, versioned, or developed independently.

Top-Level Directory Organization

The repository root organizes functionality into distinct domains, separating core skills from marketing sites, examples, and tooling.

The skills/ Directory

The skills/ folder contains the core skill packages and represents the primary product of the repository. Each subfolder represents one self-contained skill, such as web-video-presentation, web-design-engineer, gpt-image-2, kb-retriever, and beautiful-article. These folders are designed to be copied directly into agent environments, with each containing the deterministic instructions and assets needed for that specific capability.

The website/ Directory

The website/ directory hosts Vite-powered static sites that serve as demo and marketing pages for individual skills. Examples include web-design-website and gpt-image2-website, each containing their own vite.config.ts, tsconfig.json, and source HTML/CSS/JS files. This separation keeps presentation layers distinct from the skill logic itself.

The demo/ Directory

The demo/ folder provides end-user examples showing skills in action through small HTML/CSS/JS files. For instance, web-design-demo/demo1.html can be opened locally to see the web-design-engineer skill output without requiring an AI agent environment.

The scripts/ Directory

The scripts/ folder houses release-automation utilities written in Node.js. These handle tasks such as updating README download links, packaging skills for distribution, and listing available skills in the collection.

Configuration and System Files

Additional top-level entries include .claude-plugin/ (containing the Claude Code marketplace manifest), .github/workflows/ (CI pipelines for validation), and dist/ (built artifacts including pre-generated markdown prompts). Root metadata files include package.json, README.md, CONTRIBUTING.md, LICENSE, and .gitignore.

Anatomy of a Skill Folder

Every skill in the collection follows an identical internal structure defined in the main README.md. This standardization allows agent environments to parse and execute any skill uniformly.

Required and Optional Components

Each skill folder contains:

• SKILL.md — The required contract file defining when to run the skill, input/output specifications, and execution logic.
• README.md — Human-friendly documentation explaining usage, examples, and galleries.
• references/ — Optional extended documentation used by the agent during execution.
• scripts/ — Deterministic helper scripts for tasks like PDF-to-image conversion.
• assets/ — Static resources including templates, fonts, icons, and other media.

Example Skill Paths

You can see this structure in practice by examining specific skills:

• skills/web-video-presentation/ — Contains presentation templates and slide generation logic.
• skills/web-design-engineer/ — Includes design system prompts and component libraries.
• skills/kb-retriever/ — Houses knowledge base querying capabilities and reference materials.

Supporting Infrastructure and Automation

The repository includes several mechanisms for maintaining quality and simplifying distribution.

Release Automation

The file scripts/release/update-readme.mjs contains Node.js logic that automatically rewrites download links in the main README.md on every release. This ensures versioned asset URLs remain current without manual editing.

Marketplace Integration

The .claude-plugin/marketplace.json file declares the plugin packs exposed to the Claude Code marketplace. It organizes skills into four categories: presentation-skills, web-design-skills, knowledge-base-skills, and image-generation-skills, mapping each to its corresponding folder in skills/.

Continuous Integration

The workflow defined in .github/workflows/validate-skills.yml runs validation logic on every pull request. This ensures all SKILL.md files are syntactically correct and that release consistency is maintained before code reaches the main branch.

How to Navigate the Garden Skills Repository

Understanding the file layout helps you extract and install skills efficiently. There are three canonical methods to bring a skill into your agent environment.

Installing via the Skills CLI

The recommended approach uses the skills CLI tool, which auto-detects your host agent (Claude Code, Cursor, Codex, etc.) and copies files to the proper location.

# Install every skill (latest)

npx skills add ConardLi/garden-skills

# Install a single skill

npx skills add ConardLi/garden-skills -s web-design-engineer

# Global install (stores under ~/.skills)

npx skills add ConardLi/garden-skills -s gpt-image-2 --global

Manual Copy for Local Development

For hacking or customization, clone the repository and copy specific skill folders directly:

git clone https://github.com/ConardLi/garden-skills.git

# For Claude Code

cp -r garden-skills/skills/kb-retriever ~/.claude/skills/

# For Cursor

cp -r garden-skills/skills/kb-retriever ~/.agents/skills/

Git Submodule Integration

For vendoring the collection within a larger project while pinning to specific versions:

git submodule add https://github.com/ConardLi/garden-skills.git vendor/garden-skills
ln -s ../../vendor/garden-skills/skills/web-design-engineer .claude/skills/web-design-engineer

# Pin to specific tag

cd vendor/garden-skills
git checkout web-design-engineer-v1.0.0

Key Files and Their Roles

Several files serve as navigation anchors when exploring the Garden Skills repository structure:

• README.md — The hub page listing all available skills, installation options, and high-level architecture decisions.
• skills/<skill>/SKILL.md — The formal contract each skill exposes to agents, defining triggers, inputs, and outputs.
• skills/<skill>/README.md — Human-readable documentation with usage tips, theme galleries, and example outputs.
• .claude-plugin/marketplace.json — Defines the Claude Code plugin packs that bundle related skills together.
• dist/prompt/claude-design-system-prompt.md — An example of pre-generated prompts stored in the distribution folder, used by the web-design-engineer skill.
• CONTRIBUTING.md — Guidelines for adding new skills or improving existing ones, ensuring consistency with the established folder anatomy.

Summary

• The Garden Skills repository organizes AI capabilities into modular, self-contained packages under the skills/ directory.
• Each skill follows a strict internal structure with SKILL.md (agent contract), README.md (human docs), and optional references/, scripts/, and assets/ folders.
• Supporting directories like website/, demo/, and scripts/ separate marketing, examples, and automation from core logic.
• Key automation files include scripts/release/update-readme.mjs for release management and .github/workflows/validate-skills.yml for CI validation.
• Skills can be installed via the npx skills CLI, manual copy, or Git submodule depending on your integration needs.

Frequently Asked Questions

What is the difference between SKILL.md and README.md in a skill folder?

The SKILL.md file serves as the formal contract that AI agents read to understand when to execute the skill, what inputs to expect, and how to format outputs. The README.md file is human-readable documentation containing usage examples, theme galleries, and implementation tips for developers. While agents parse SKILL.md deterministically, humans reference README.md to understand capabilities.

How does the Garden Skills repository handle versioning and releases?

Versioning is managed through Git tags and automated scripts. The scripts/release/update-readme.mjs utility automatically updates download link URLs in the main README.md to point to the latest release assets. Users can pin to specific versions using Git submodules and checking out tags like web-design-engineer-v1.0.0, ensuring reproducible skill behavior across projects.

Can I use these skills with agents other than Claude Code?

Yes. While the repository includes a .claude-plugin/marketplace.json manifest for Claude Code integration, the folder structure is agent-agnostic. Skills can be installed in Cursor (using ~/.agents/skills/), Codex, or other environments using the manual copy method or the npx skills CLI, which auto-detects the host agent and adjusts installation paths accordingly.

Where are the actual prompts and templates stored that the skills use?

Static assets like design system prompts are stored in the dist/ directory at the repository root (e.g., dist/prompt/claude-design-system-prompt.md), while skill-specific templates live within each skill's assets/ folder. The dist/ folder contains pre-generated markdown prompts used by multiple skills, whereas individual assets/ folders house templates, fonts, and icons specific to that skill's function.

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