# How to Contribute a New Skill to Garden Skills: Complete Developer Guide

> Learn how to contribute a new skill to Garden Skills with this complete developer guide. Follow simple steps to add your skill and enhance the project.

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

---

**To contribute a new skill to Garden Skills, create a directory under `skills/`, add 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) files, insert download markers in the root READMEs, run `npm run readme:sync` and `npm run validate`, then submit a Pull Request.**

Garden Skills is a monorepo that stores each skill in its own folder under `skills/`. Contributing a new skill requires following a standardized structure defined in [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) that ensures consistency, enables automated packaging, and maintains synchronized documentation across multiple languages.

## Create the Skill Directory Structure

Start by creating a new directory at `skills/<new-skill-name>/`. According to [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) (lines 85-99), this folder serves as the isolated container for your skill.

Inside this directory, you must provide at least two required files. You may also include optional subdirectories for additional resources:

- `references/` – On-demand documentation files
- `scripts/` – Deterministic helper scripts
- `assets/` – Templates, fonts, or icons
- `README*` files – Human-readable documentation

## Define the Agent Specification with SKILL.md

Every skill requires a [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file containing a YAML front-matter block followed by Markdown content. As specified in [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) (lines 101-112), the front-matter defines the skill's identity:

```bash
cat > skills/my-awesome-skill/SKILL.md <<'EOF'
---
name: my-awesome-skill
description: A concise description of what the skill does.
---

# My Awesome Skill

Detailed usage instructions go here.
EOF

```

The agent-facing specification uses the `name` and `description` fields to identify the skill to AI systems.

## Configure the Machine-Readable manifest.json

Create a [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) file that serves as the machine-readable contract for release tooling. Based on the schema documented in [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) (lines 115-132), include these fields:

```json
{
  "name": "my-awesome-skill",
  "version": "0.1.0",
  "category": "Design / Frontend",
  "description": "What it does, what it's good for.",
  "homepage": "https://github.com/ConardLi/garden-skills/tree/main/skills/my-awesome-skill",
  "compat": [
    "claude-code",
    "claude-ai",
    "cursor",
    "codex-cli",
    "gemini-cli",
    "opencode"
  ]
}

```

The `compat` array declares which AI assistants can utilize this skill.

## Insert Download Markers in Root READMEs

Before synchronizing links, insert special markers in each localized root README (English, Chinese, Japanese). Locate the "Links:" row for your skill and append the inline marker format:

```markdown
<!-- DOWNLOAD:my-awesome-skill:start --><!-- DOWNLOAD:my-awesome-skill:end -->

```

As implemented in `scripts/release/update-readme.mjs`, these markers allow `npm run readme:sync` to generate versioned download links after release (see [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) lines 48-53 and 107-118).

## Synchronize and Validate Your Changes

Run the synchronization script to populate the markers with correct URLs:

```bash
npm run readme:sync

```

The script `scripts/release/update-readme.mjs` rewrites content between markers to point at versioned ZIP assets.

Validate your contribution locally:

```bash
npm run validate

```

This mirrors the CI checks in [`.github/workflows/validate-skills.yml`](https://github.com/ConardLi/garden-skills/blob/main/.github/workflows/validate-skills.yml) (lines 84-90).

## Submit Your Contribution

Push your branch and open a Pull Request. The CI pipeline automatically runs validation.

After merging, cut the first release:

```bash
npm run release

```

This creates a Git tag, builds a ZIP artifact, and updates README links automatically (lines 65-78).

## Optional: Register in the Claude Code Marketplace

To make your skill discoverable via the Claude Code plugin marketplace, add an entry to [`.claude-plugin/marketplace.json`](https://github.com/ConardLi/garden-skills/blob/main/.claude-plugin/marketplace.json) (see [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) line 59).

## Summary

Contributing to Garden Skills follows a standardized workflow:

- Create a directory under `skills/` with [`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)
- Include optional `references/`, `scripts/`, or `assets/` directories as needed
- Insert `<!-- DOWNLOAD:<skill>:start/end -->` markers in root READMEs
- Run `npm run readme:sync` to generate links via `scripts/release/update-readme.mjs`
- Execute `npm run validate` to verify compliance with CI standards
- Submit a Pull Request; after merge, use `npm run release` to publish

## Frequently Asked Questions

### What are the minimum required files to contribute a new skill to Garden Skills?

You must provide [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) containing YAML front-matter with `name` and `description` fields, and [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) with `name`, `version`, `category`, `description`, `homepage`, and `compat`. These files reside in `skills/<your-skill-name>/`.

### How does the `npm run validate` command check my skill?

The validation script verifies [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) schema compliance, folder layout correctness, and download marker formatting. This local check mirrors the CI workflow defined in [`.github/workflows/validate-skills.yml`](https://github.com/ConardLi/garden-skills/blob/main/.github/workflows/validate-skills.yml) to catch errors before submission.

### Can I include helper scripts or assets with my skill?

Yes. While [`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) are required, you may include a `references/` directory for documentation, a `scripts/` directory for deterministic helpers, and an `assets/` directory for templates or icons per [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) (lines 85-99).

### How do I make my skill discoverable in the Claude Code marketplace?

Add an entry to [`.claude-plugin/marketplace.json`](https://github.com/ConardLi/garden-skills/blob/main/.claude-plugin/marketplace.json) following the existing schema. This optional step registers your skill in the marketplace feed, making it visible to Claude Code users.