How the Skill Frontmatter Name Must Match the Directory Slug in HumanLayer Skills

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 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, 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 (or .agents/skills/migrate-foo/SKILL.md)."

This convention is reiterated in plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md:

"IMPORTANT: the name field in the 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 ..."

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.

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 and expects the frontmatter to confirm this identity.

2. Path consistency – Automated workflows and CI pipelines reference skills using the pattern .claude/skills/<task-slug>/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 demonstrates this alignment:

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

---
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 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/<slug>/ or .agents/skills/<slug>/ directories.
• The 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 and 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 file located at the root of its directory, following the pattern .claude/skills/<slug>/SKILL.md or .agents/skills/<slug>/SKILL.md. The file must contain YAML frontmatter with a name field matching the <slug> 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 <slug>, replacing <slug> with the directory name. Ensure the target skill's SKILL.md contains name: <slug> in its frontmatter, or the command will fail to locate the skill.

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