# How the Skill Frontmatter Name Must Match the Directory Slug in HumanLayer Skills > Learn how the skill frontmatter name must match the directory slug in humanlayer/skills to ensure your skills load correctly. Avoid common errors and streamline your development. - Repository: [HumanLayer/skills](https://github.com/humanlayer/skills) - Tags: how-to-guide - Published: 2026-09-13 --- **In the humanlayer/skills repository, the `name` field in a skill's frontmatter must exactly match the directory slug where the skill resides, or the skill will fail to load.** The humanlayer/skills repository organizes each skill as a standalone package within specific filesystem locations. Every skill contains a [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) file with YAML frontmatter that declares metadata including the skill's canonical identifier, and this identifier must correspond precisely to the folder name containing the file. ## The Required Naming Convention According to the source code in [`plugins/design-control-loop/skills/design-control-loop/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/SKILL.md), the repository enforces a strict 1:1 relationship between directory structure and metadata: > "**IMPORTANT:** the `name` in the skill's frontmatter must match its directory slug — a skill named `migrate-foo` lives at [`.claude/skills/migrate-foo/SKILL.md`](https://github.com/humanlayer/skills/blob/main/.claude/skills/migrate-foo/SKILL.md) (or [`.agents/skills/migrate-foo/SKILL.md`](https://github.com/humanlayer/skills/blob/main/.agents/skills/migrate-foo/SKILL.md))." This convention is reiterated in [`plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md): > "**IMPORTANT**: the `name` field in the [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) frontmatter must match the skill slug – e.g. a skill with name `fix-eslint-issues` must be in [`.claude/skills/fix-eslint-issues/SKILL.md`](https://github.com/humanlayer/skills/blob/main/.claude/skills/fix-eslint-issues/SKILL.md) ..." The **directory slug** refers to the final path segment of the skill's location—everything after `.claude/skills/` or `.agents/skills/`. The **frontmatter name** is the value assigned to the `name:` key in the YAML block at the top of [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md). ## Why the Match Is Required The strict alignment between frontmatter and filesystem serves three critical functions: 1. **Discovery mechanism** – The CLI tool (`npx skills add`) resolves skills by their slug. When you run a command like `npx skills add humanlayer/skills --skill narrow-react-prop-types`, the tool constructs the path [`.claude/skills/narrow-react-prop-types/SKILL.md`](https://github.com/humanlayer/skills/blob/main/.claude/skills/narrow-react-prop-types/SKILL.md) and expects the frontmatter to confirm this identity. 2. **Path consistency** – Automated workflows and CI pipelines reference skills using the pattern `.claude/skills//SKILL.md`. If the frontmatter `name` differs from the folder name, path construction algorithms break. 3. **Canonical identification** – The slug acts as the unique identifier across the ecosystem. Mismatches create ambiguity about which skill is being executed. ## Implementation Examples ### Valid Structure A correctly configured skill aligns the directory name and frontmatter exactly. For example, the `narrow-react-prop-types` skill in [`plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md) demonstrates this alignment: ```yaml --- name: narrow-react-prop-types description: narrow React component prop types to match live code paths --- ``` The filesystem structure mirrors this: ``` .claude/ └─ skills/ └─ narrow-react-prop-types/ └─ SKILL.md ``` Similarly, the `improve-claude-md` skill at [`plugins/improve-claude-md/skills/improve-claude-md/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/skills/improve-claude-md/SKILL.md) uses `name: improve-claude-md` to match its directory. ### Invalid Structure and Consequences If the frontmatter declares a different name than the directory contains, the skill becomes unreachable. Consider this incorrect configuration: Directory structure: ``` .claude/ └─ skills/ └─ narrow-react-prop-types/ └─ SKILL.md ``` Frontmatter content: ```yaml --- name: narrow-props description: Attempting to narrow React prop types --- ``` In this scenario, running `npx skills add humanlayer/skills --skill narrow-react-prop-types` fails with a "skill not found" error. The CLI locates the directory by slug but rejects the skill because the `name` field (`narrow-props`) does not validate against the expected identifier (`narrow-react-prop-types`). ## Tooling Enforcement The repository's command-line interface relies on this convention for skill resolution. When adding a skill, the tool: 1. Constructs the expected path using the provided slug. 2. Parses the [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) frontmatter. 3. Validates that `name` equals the directory slug. 4. Rejects the skill if validation fails. This enforcement ensures that skills cannot be misidentified or loaded from incorrect paths, maintaining integrity across the humanlayer/skills ecosystem. ## Summary - The frontmatter `name` field and directory slug must be **identical strings** for every skill in the repository. - Skills reside in either `.claude/skills//` or `.agents/skills//` directories. - The [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) file must sit at the root of its respective skill directory. - Validation failures occur immediately when running `npx skills add` if the names mismatch. - Files such as [`plugins/design-control-loop/skills/design-control-loop/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/SKILL.md) and [`plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md) document this requirement explicitly. ## Frequently Asked Questions ### What happens if the name doesn't match the directory slug? The skill will not load correctly. When using the CLI to add or run a skill, you will encounter a "skill not found" error because the tool cannot reconcile the filesystem path with the metadata identity. ### Where must the SKILL.md file be located? Each skill requires a [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) file located at the root of its directory, following the pattern `.claude/skills//SKILL.md` or `.agents/skills//SKILL.md`. The file must contain YAML frontmatter with a `name` field matching the `` segment. ### Is this convention required for all HumanLayer skills? Yes. Every skill in the humanlayer/skills repository must follow this convention. The requirement is explicitly documented in multiple skill specifications, including the Design Control Loop and Build Iterated Agentic Loop skills. ### How do I add a skill using the CLI? Use the command `npx skills add humanlayer/skills --skill `, replacing `` with the directory name. Ensure the target skill's [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) contains `name: ` in its frontmatter, or the command will fail to locate the skill.