# Standard Directory Structure for a Garden Skills Skill: Complete Guide

> Learn the standard directory structure for a Garden Skills skill. Organize your skill with manifest.json, SKILL.md, scripts, references, and assets for portability and scale.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: how-to-guide
- Published: 2026-09-02

---

**A Garden Skills skill requires only two files at its root—[`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) and [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md)—but typically organizes additional resources into optional directories like `scripts/`, `references/`, and `assets/` to maintain portability and scale.**

Every skill in the **ConardLi/garden-skills** repository lives as a self-contained package under the `skills/` directory. Regardless of whether the skill handles web design, article generation, or knowledge retrieval, it follows a unified layout that enables the platform's shared release and execution tooling. Understanding this standard directory structure ensures your skill integrates seamlessly with agent harnesses and CI/CD pipelines.

## Required Root Files

At minimum, every Garden Skills skill must expose two metadata files at its root to be recognized by the tooling.

### SKILL.md

The [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file serves as the skill definition that agents parse to understand capabilities. It contains YAML front-matter declaring the skill's name, version, category, and compatibility matrix.

```yaml
---
name: beautiful-article
version: 2.5.1
category: Writing / Content
description: Turn any source into a beautiful, share-ready article.
compat:
  - claude-code
  - opencode
---

```

### manifest.json

The [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) supplies the release toolchain with machine-readable metadata. As implemented in [`skills/web-design-engineer/manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/manifest.json), this file must include `name`, `version`, `category`, `description`, `homepage`, and a `compat` array listing supported agents.

```json
{
  "name": "web-design-engineer",
  "version": "1.3.0",
  "category": "Design / Frontend",
  "description": "Build and redesign high-quality visual Web artifacts using HTML/CSS/JavaScript/React …",
  "homepage": "https://github.com/ConardLi/garden-skills/tree/main/skills/web-design-engineer",
  "compat": [
    "claude-code",
    "claude-ai",
    "cursor",
    "codex-cli",
    "gemini-cli",
    "opencode"
  ]
}

```

## Optional Resource Directories

As skill complexity grows, you populate additional directories alongside the mandatory files to keep resources organized.

### scripts/

The `scripts/` directory holds helper scripts that bootstrap workspaces or run post-processing tasks. For example, [`skills/beautiful-article/scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/scripts/scaffold.sh) initializes a Vite + React + TypeScript workspace that the skill's agent subsequently populates.

### references/

Store in-depth design documentation, templates, and checklists in `references/`. The Beautiful Article skill uses this directory extensively for files like [`article-types.md`](https://github.com/ConardLi/garden-skills/blob/main/article-types.md) and other workflow definitions that the harness relies on during execution.

### theme-profiles/

Themed skills include a `theme-profiles/` directory containing an [`index.json`](https://github.com/ConardLi/garden-skills/blob/main/index.json) registry and per-theme subfolders. Each subfolder holds token bundles and authoring profiles specific to that visual theme.

### assets/

Static resources such as icons, scaffold templates, and example files belong in `assets/`. The Beautiful Article skill stores its Vite+React+TS scaffold template under `assets/scaffold-template/` for use by [`scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/scripts/scaffold.sh).

### src/ and tests/

When a skill contains custom runtime logic, add language-specific code directories like `src/` or `tests/` at the same level as the other folders. These are optional and only required when the skill implements custom handlers beyond declarative definitions.

## Real-World Example: Beautiful Article Skill

The **Beautiful Article** skill in `skills/beautiful-article/` demonstrates the complete standard directory structure:

```text
skills/beautiful-article/
├── SKILL.md                # Main skill definition

├── manifest.json           # Release manifest

├── README.md / README.zh-CN.md
├── references/             # Design docs, templates, checklists

│   ├── article-types.md
│   └── … (many other .md files)
├── theme-profiles/         # Theme registry + individual theme folders

│   ├── index.json
│   └── … (andy, bayer, …)
├── scripts/                # Scaffold, conversion, PDF scripts

│   ├── scaffold.sh
│   ├── html-to-pdf.sh
│   └── … (python helpers)
└── assets/
    └── scaffold-template/  # Vite+React+TS template used by scaffold.sh

```

This layout showcases how the required [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) and [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) coexist with optional directories to support complex workflows.

## Summary

- **Mandatory files**: Every skill requires [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) for release metadata and [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) for agent-facing definitions at the root.
- **Optional directories**: Add `scripts/`, `references/`, `theme-profiles/`, `assets/`, `src/`, or `tests/` as functionality expands.
- **Repository location**: Skills reside under `skills/<skill-name>/` within the ConardLi/garden-skills repository.
- **Scaffolding**: New skills can start minimal with just the two required files and grow into the full structure as needed.

## Frequently Asked Questions

### What files are absolutely required when creating a new Garden Skills skill?

You need only [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) and [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) at the root of your skill folder. The [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) provides metadata for release scripts, while [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) defines the skill's capabilities and constraints for agent consumption according to the source code. All other directories are optional and added based on your skill's complexity.

### Where should I put helper scripts that scaffold a workspace for my skill?

Place bootstrap scripts in the `scripts/` directory. For example, [`skills/beautiful-article/scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/beautiful-article/scripts/scaffold.sh) initializes a Vite+React+TypeScript workspace. This convention keeps automation logic separate from documentation and skill definitions while ensuring the release tooling can locate utilities consistently.

### How do I organize theme-related resources in a Garden Skills skill?

Themed skills should create a `theme-profiles/` directory containing an [`index.json`](https://github.com/ConardLi/garden-skills/blob/main/index.json) registry file and individual subfolders for each theme. Each subfolder holds token bundles and authoring profiles specific to that visual theme, allowing the skill harness to dynamically load styling parameters.

### Can I include custom source code or tests in a skill package?

Yes. While not required for declarative skills, you may add optional directories like `src/` or `tests/` when your skill contains custom runtime logic or validation suites. These live alongside standard directories like `scripts/` and `references/` at the root of your skill folder, following standard language-specific conventions.