How the manifest.json Name Field Relates to the Folder Name and SKILL.md in Garden-Skills

In the garden-skills ecosystem, the name field in manifest.json must exactly match the skill's folder name under skills/ and the name value in SKILL.md front-matter to ensure deterministic discovery and consistent documentation.

In the ConardLi/garden-skills repository, every skill is a self-contained package identified by a canonical string that appears in three specific locations. Understanding how the manifest.json name field synchronizes with the directory structure and documentation files is essential for developers adding new capabilities to the platform.

The Three Components of Skill Identity

manifest.json → name

The manifest.json file declares the canonical skill identifier in its name field. Located at skills/<skill-name>/manifest.json, this JSON field stores the string that runtimes like Opencode, Claude-code, and Cursor use to register and expose the skill to users. The platform discovers skills by scanning skills/*/manifest.json and uses this field to require the correct module.

Folder Name Convention

The directory containing the skill's assets must be named identically to the name field in manifest.json. For example, a skill with "name": "web-video-presentation" must reside in skills/web-video-presentation/. This exact match removes ambiguity during the loading process and allows the platform to map a skill name to its physical location without heuristics.

SKILL.md Front-Matter

The SKILL.md documentation file begins with a YAML front-matter block that repeats the identifier: name: web-video-presentation. Documentation tools and CLI helpers read this value to generate help pages and verify that the documentation describes the exact code package declared in the manifest.

Why Synchronization Matters

This tight coupling across three locations guarantees deterministic discovery, consistent documentation, and version-controlled integrity. Any mismatch between the folder name, manifest.json name field, or SKILL.md front-matter causes immediate loading errors, such as "manifest name does not match folder," which are caught early by the test suite.

Implementation Requirements

When adding a new skill to the ConardLi/garden-skills repository, you must align all three identifiers.

Directory layout example:

skills/
└── web-video-presentation/
    ├── manifest.json
    ├── SKILL.md
    └── ...

manifest.json content:

{
  "name": "web-video-presentation",
  "version": "1.2.2",
  "category": "Web Video / Presentation"
}

SKILL.md front-matter:

---
name: web-video-presentation
description: 把一篇文章或口播稿，做成"看起来像视频"...
---

Summary

• The manifest.json name field serves as the canonical identifier that runtimes use to register skills.
• The folder name under skills/ must exactly match the manifest's name field to enable deterministic discovery.
• The SKILL.md front-matter repeats this identifier to link documentation with code.
• Mismatches between these three components trigger loading errors and test failures.
• New skills require simultaneous updates to all three locations to maintain ecosystem integrity.

Frequently Asked Questions

What happens if the manifest.json name field doesn't match the folder name?

The platform throws a loading error indicating that the manifest name does not match the folder. This validation ensures that the skill registry maintains a strict one-to-one mapping between identifiers and physical locations.

Is the SKILL.md front-matter name field optional?

No. While the runtime primarily uses manifest.json, the SKILL.md front-matter is required for documentation generation and CLI helpers. Omitting it breaks the documentation pipeline and validation tests.

Can I use spaces or special characters in the skill name?

The examples show kebab-case identifiers like web-video-presentation. While the JSON and YAML formats support various characters, matching the folder name requirement typically restricts you to URL-safe characters compatible with filesystem constraints.

Do I need to update all three files when renaming a skill?

Yes. Changing a skill's identifier requires updating the name field in manifest.json, renaming the folder under skills/, and updating the front-matter in SKILL.md. Failure to synchronize all three causes immediate registry errors.

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