# Garden Skills Repository Structure: A Complete Guide to the Modular AI Skill Collection > Explore the modular structure of the Garden Skills repository. Learn how AI skills are organized with standardized internal files and dedicated directories for presentation and automation. - Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills) - Tags: architecture - Published: 2026-09-01 --- **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`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md), [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/vite.config.ts), [`tsconfig.json`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/package.json), [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md), [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/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`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md)** — The required contract file defining when to run the skill, input/output specifications, and execution logic. - **[`README.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/README.md) on every release. This ensures versioned asset URLs remain current without manual editing. ### Marketplace Integration The [`.claude-plugin/marketplace.json`](https://github.com/ConardLi/garden-skills/blob/main/.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`](https://github.com/ConardLi/garden-skills/blob/main/.github/workflows/validate-skills.yml) runs validation logic on every pull request. This ensures all [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/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. ```bash # 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: ```bash 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: ```bash 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`](https://github.com/ConardLi/garden-skills/blob/main/README.md)** — The hub page listing all available skills, installation options, and high-level architecture decisions. - **`skills//SKILL.md`** — The formal contract each skill exposes to agents, defining triggers, inputs, and outputs. - **`skills//README.md`** — Human-readable documentation with usage tips, theme galleries, and example outputs. - **[`.claude-plugin/marketplace.json`](https://github.com/ConardLi/garden-skills/blob/main/.claude-plugin/marketplace.json)** — Defines the Claude Code plugin packs that bundle related skills together. - **[`dist/prompt/claude-design-system-prompt.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) (agent contract), [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/.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`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) and [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md) in a skill folder? The [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/README.md) file is **human-readable documentation** containing usage examples, theme galleries, and implementation tips for developers. While agents parse [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) deterministically, humans reference [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/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`](https://github.com/ConardLi/garden-skills/blob/main/.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`](https://github.com/ConardLi/garden-skills/blob/main/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.