# Understanding the Repository Structure of Garden Skills: A Complete Monorepo Guide

> Explore the Garden Skills repository structure, a comprehensive monorepo guide. Understand how skills, websites, and tooling are organized in this design-focused project. Learn more now.

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

---

**Garden Skills is organized as a monorepo that groups stand-alone design-oriented assets called "skills" with supporting websites, demos, and release automation tooling.**

The Garden Skills repository by ConardLi serves as a centralized hub for design-oriented assets consumable by the Claude Code Plugin. Understanding the repository structure of Garden Skills enables developers to contribute new skills, customize existing ones, or integrate the assets into their own workflows.

## Top-Level Directory Organization

The root of the repository contains standard project files alongside specialized directories that separate concerns between skill definitions, presentation layers, and automation:

- [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md) — Project overview with installation instructions and a gallery of available skills (includes localized variants)
- [`package.json`](https://github.com/ConardLi/garden-skills/blob/main/package.json) — Core npm metadata defining the monorepo workspace configuration, scripts, and repository metadata
- `skills/` — Self-contained skill directories with manifests and assets
- `website/` — Vite-powered demonstrator sites for the Web-Design Engine and GPT-Image 2
- `demo/` — Plain-HTML demonstrations requiring no build step
- `scripts/` — Release utilities including `list-skills.mjs`, `pack-skill.mjs`, and `cut-release.mjs`
- `.github/workflows/` — CI workflows that validate skill definitions and perform releases
- `.claude-plugin/` — Marketplace metadata enabling direct installation from the Claude Code Plugin UI
- `LICENSE` and `CONTRIBUTING*` — Legal and contribution guidelines

## Skills Folder Structure

Each skill in the `skills/` directory follows a consistent convention that makes it machine-readable and self-documenting.

### Standard Skill Layout

Every skill folder contains:

```

skills/
└─ <skill-name>/
   ├─ README.md           # Human-readable documentation and usage instructions

   ├─ SKILL.md            # Machine-readable description

   ├─ manifest.json       # Metadata consumed by the plugin system and websites

   ├─ <optional-assets>/  # Theme files, templates, images, and other resources

   └─ scripts/            # Helper scripts for some skills (e.g., generate.js)

```

### Notable Skill Examples

**Web-Video Presentation** contains multiple theme sub-folders including `warm-keynote` and `electric-studio`. Its metadata lives at [`skills/web-video-presentation/manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/manifest.json).

**GPT-Image 2** provides image generation prompts with a [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) and reference markdown files located in its skill root.

**Beautiful Article** focuses on typography with theme profiles stored under `skills/beautiful-article/theme-profiles/`.

## Website Projects Structure

The `website/` directory hosts two independent Vite projects that expose skills as interactive web applications:

- **Web-Design Engine website** (`website/web-design-website/`) — Contains [`vite.config.ts`](https://github.com/ConardLi/garden-skills/blob/main/vite.config.ts), TypeScript configuration, and [`index.html`](https://github.com/ConardLi/garden-skills/blob/main/index.html) as the entry point
- **GPT-Image 2 website** (`website/gpt-image2-website/`) — Similar Vite structure with an additional [`netlify.toml`](https://github.com/ConardLi/garden-skills/blob/main/netlify.toml) for deployment configuration

Both sites import skill manifests at runtime to render dynamic skill galleries, allowing users to preview capabilities without installing the Claude plugin.

## Demo Folder Contents

The `demo/` directory provides lightweight, build-free previews of skills. These are pure HTML/CSS/JavaScript files that demonstrate specific skill implementations.

For example, [`demo/web-design-demo/demo1.html`](https://github.com/ConardLi/garden-skills/blob/main/demo/web-design-demo/demo1.html) and [`demo/web-design-demo/demo2.html`](https://github.com/ConardLi/garden-skills/blob/main/demo/web-design-demo/demo2.html) illustrate different configurations of the Web-Design Engine skill. Users can open these files directly in a browser without running a build step or development server.

## Release Automation Scripts

Located in `scripts/release/`, these Node.js utilities handle packaging and publication:

- **`list-skills.mjs`** — Enumerates all skills and prints their current version information
- **`pack-skill.mjs`** — Bundles an individual skill into a zip archive ready for distribution
- **`cut-release.mjs`** — Orchestrates version bumping and changelog generation across the monorepo

These scripts automate the validation and packaging workflow triggered by CI pipelines in `.github/workflows/`.

## Key Configuration Files

Several files are critical to repository operations:

| File | Purpose |
|------|---------|
| [`package.json`](https://github.com/ConardLi/garden-skills/blob/main/package.json) | Defines npm workspace boundaries and top-level dependencies |
| `skills/*/manifest.json` | Core descriptors read by the Claude Code Plugin and demo sites |
| `website/*/vite.config.ts` | Configures the Vite build system for interactive showcases |
| [`.github/workflows/validate-skills.yml`](https://github.com/ConardLi/garden-skills/blob/main/.github/workflows/validate-skills.yml) | CI job validating every skill's manifest and README structure |

## Working with the Repository

The following examples demonstrate common interactions with the Garden Skills repository structure.

### Reading Skill Metadata

To programmatically inspect a skill's definition, read its [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json):

```javascript
import fs from 'node:fs';
import path from 'node:path';

const manifestPath = path.resolve('skills', 'gpt-image-2', 'manifest.json');
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
console.log('Skill name:', manifest.name);
console.log('Version:', manifest.version);

```

### Running Local Demos

Preview a skill instantly without building the full website:

```bash

# From the repository root

npx serve demo/web-design-demo/demo1.html

# Then open http://localhost:5000 in a browser

```

### Packaging Skills for Distribution

Replicate the release process using the `pack-skill.mjs` logic:

```javascript
import { execSync } from 'node:child_process';
import path from 'node:path';

const skill = 'beautiful-article';
const cwd = path.resolve('skills', skill);
execSync(`zip -r ${skill}.zip .`, { cwd, stdio: 'inherit' });
console.log(`✅ ${skill}.zip created`);

```

## Summary

- Garden Skills uses a **monorepo structure** separating skills, websites, demos, and automation scripts into distinct top-level directories.
- Each **skill** is self-contained in `skills/<name>/` with a standardized layout including [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json), documentation, and optional assets.
- The **website** directory contains two Vite projects that dynamically render skill galleries by consuming manifests at runtime.
- **Demos** in `demo/` provide build-free HTML previews for quick skill evaluation.
- **Release scripts** in `scripts/release/` automate versioning, validation, and packaging for the Claude Code Plugin marketplace.

## Frequently Asked Questions

### What is the purpose of the manifest.json file in each skill?

The [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) file serves as the machine-readable contract between a skill and the Claude Code Plugin. It contains metadata such as the skill name, version, description, and entry points that the plugin system uses to display and install the skill. Both the interactive websites and the plugin marketplace consume this file to present skill information to users.

### How does the Garden Skills repository support localization?

The repository includes localized variants of the main [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md) file at the root level, providing project documentation in multiple languages. Additionally, individual skills may contain localized content within their own [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md) files, allowing the design-oriented assets to reach a global audience while maintaining a single source of truth in the monorepo.

### Can I test a skill without setting up the full Vite website?

Yes. The `demo/` directory contains plain-HTML demonstrations that embed skills directly without requiring a build step. Files such as [`demo1.html`](https://github.com/ConardLi/garden-skills/blob/main/demo1.html) and [`demo2.html`](https://github.com/ConardLi/garden-skills/blob/main/demo2.html) in `demo/web-design-demo/` can be opened directly in a browser or served with a simple static server like `npx serve`. This allows for rapid iteration and testing of skill configurations without waiting for a Vite build process.

### Where are the CI/CD workflows defined for validating skills?

All continuous integration workflows reside in `.github/workflows/`. Specifically, the [`validate-skills.yml`](https://github.com/ConardLi/garden-skills/blob/main/validate-skills.yml) workflow runs on pull requests to ensure every skill's [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) follows the required schema and that documentation files are present. These automated checks prevent malformed skills from being merged into the main branch and published to the Claude Code Plugin marketplace.