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

To contribute a new skill to Garden Skills, create a directory under skills/, add the required SKILL.md and 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 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 (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 file containing a YAML front-matter block followed by Markdown content. As specified in CONTRIBUTING.md (lines 101-112), the front-matter defines the skill's identity:

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 file that serves as the machine-readable contract for release tooling. Based on the schema documented in CONTRIBUTING.md (lines 115-132), include these fields:

{
  "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:

<!-- 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 lines 48-53 and 107-118).

Synchronize and Validate Your Changes

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

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:

npm run validate

This mirrors the CI checks in .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:

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 (see CONTRIBUTING.md line 59).

Summary

Contributing to Garden Skills follows a standardized workflow:

• Create a directory under skills/ with SKILL.md and 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 containing YAML front-matter with name and description fields, and 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 schema compliance, folder layout correctness, and download marker formatting. This local check mirrors the CI workflow defined in .github/workflows/validate-skills.yml to catch errors before submission.

Can I include helper scripts or assets with my skill?

Yes. While SKILL.md and 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 (lines 85-99).

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

Add an entry to .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.

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