Standard Directory Structure for a Garden Skills Skill: Complete Guide

A Garden Skills skill requires only two files at its root—manifest.json and 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 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.

---
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 supplies the release toolchain with machine-readable metadata. As implemented in skills/web-design-engineer/manifest.json, this file must include name, version, category, description, homepage, and a compat array listing supported agents.

{
  "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 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 and other workflow definitions that the harness relies on during execution.

theme-profiles/

Themed skills include a theme-profiles/ directory containing an 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.

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:

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 and manifest.json coexist with optional directories to support complex workflows.

Summary

• Mandatory files: Every skill requires manifest.json for release metadata and 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 and SKILL.md at the root of your skill folder. The manifest.json provides metadata for release scripts, while 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 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 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.

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