How a Skill's Name Is Defined in Its Frontmatter: A Complete Guide to YAML Metadata in Instagit Skills

A skill's name is defined in the YAML frontmatter of its SKILL.md file using the name: key, which becomes the canonical identifier for invoking the skill via /skill-name.

The humanlayer/skills repository uses a standardized frontmatter convention to declare skill metadata. Every skill resides in a SKILL.md file with triple-dashed YAML delimiters at the top. The name field in this frontmatter serves as the single source of truth for how the skill is registered, looked up, and executed by the Instagit runtime.

Understanding the SKILL.md Frontmatter Structure

The frontmatter sits at the very beginning of every skill definition file, bounded by --- lines. This YAML block contains essential metadata, with name being the required identifier.

Example: The show-me Skill

---
name: show-me
description: Help the user understand the current topic visually …
---

The name: show-me entry designates how users invoke this skill. The runtime parses this value to build its internal skill registry.

Additional Skill Examples

Multiple skills in the repository follow this identical pattern:

• narrow-react-prop-types – [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)

  ---
  name: narrow-react-prop-types
  …
  ---

• improve-claude-md – [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)

  ---
  name: improve-claude-md
  …
  ---

How the Runtime Extracts the Skill Name from Frontmatter

The skill loader processes SKILL.md files and delegates YAML parsing to the gray-matter library, listed in the repository's package.json.

Core Loading Mechanism

In src/skillLoader.ts, the extraction workflow follows this pattern:

// src/skillLoader.ts – illustrative snippet
import fs from 'fs';
import matter from 'gray-matter';

export function loadSkill(path) {
  const raw = fs.readFileSync(path, 'utf8');
  const { data, content } = matter(raw);   // parses the front‑matter
  const skillName = data.name;              // <-- the skill’s name
  // …register the skill under `skillName` and keep `content` for execution
  return { name: skillName, meta: data, body: content };
}

The matter() function returns a data object containing all frontmatter keys. The runtime specifically accesses data.name to obtain the skill identifier.

Practical Code Examples

1. Defining a New Skill with Frontmatter

Create a SKILL.md with the required frontmatter structure:

---
name: my-awesome-skill
description: Does something spectacular.
---

# Skill Implementation

Write the body of the skill here. It will be passed to the skill runner.

The loader extracts my-awesome-skill as the public identifier. The content below the second --- delimiter becomes the skill's executable body.

2. Programmatically Reading a Skill's Name

import fs from 'fs';
import matter from 'gray-matter';

function getSkillName(skillPath) {
  const md = fs.readFileSync(skillPath, 'utf8');
  const { data } = matter(md);
  return data.name;
}

// Example usage
const name = getSkillName(
  'plugins/show-me/skills/show-me/SKILL.md'
);
console.log(name); // → "show-me"

This pattern mirrors how the Instagit runtime discovers skills on startup.

3. Invoking a Skill by Its Frontmatter Name

import { invokeSkill } from '@instagit/runtime';

const skillName = 'show-me';
await invokeSkill(skillName, { /* skill‑specific args */ });

The runtime matches skillName against the name values parsed from all discovered SKILL.md frontmatter blocks.

Key Files Behind Frontmatter Name Resolution

Role	File Path
Example skill definition	plugins/show-me/skills/show-me/SKILL.md
Alternative skill example	plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md
Core loader implementation	src/skillLoader.ts
Dependency manifest (gray-matter)	package.json

These files demonstrate how the name: field in YAML frontmatter functions as the definitive skill identifier throughout the humanlayer/skills ecosystem.

Summary

• Frontmatter location: Top of every SKILL.md file, delimited by ---
• Name key: The name: field holds the canonical skill identifier
• Parser dependency: gray-matter handles YAML extraction in src/skillLoader.ts
• Registration flow: Parsed name value becomes the lookup key for /skill-name invocations
• Consistency: All skills in the repository follow this identical frontmatter convention

Frequently Asked Questions

What happens if the name field is missing from frontmatter?

The loader would receive undefined for data.name, likely causing registration failure or runtime errors when attempting to invoke the skill. The repository enforces this field through convention rather than schema validation.

Can skill names contain spaces or special characters?

While YAML supports various strings, the Instagit runtime expects name values compatible with URL-style invocation paths. The examples use kebab-case (show-me, narrow-react-prop-types), suggesting this as the recommended format for maximum compatibility.

Is the skill name case-sensitive?

According to the loading implementation in src/skillLoader.ts, the name is stored as-is from the YAML parser. Invoke calls must match the frontmatter declaration exactly, including case, for successful skill resolution.

Where does the skill description appear in the frontmatter?

The description: key sits alongside name: in the same YAML block. This metadata supports documentation and discovery but does not affect the runtime identifier.

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