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

> Understand how the manifest.json name field connects to your folder name and SKILL.md in Garden-Skills for seamless skill discovery and documentation.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: deep-dive
- Published: 2026-09-01

---

**In the garden-skills ecosystem, the `name` field in [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) must exactly match the skill's folder name under `skills/` and the `name` value in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) name field, or [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/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:

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

```

[`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) content:

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

```

[`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) front-matter:

```yaml
---
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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json), the [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json), renaming the folder under `skills/`, and updating the front-matter in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md). Failure to synchronize all three causes immediate registry errors.