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

> Learn how to define a skill's name in its YAML frontmatter using the name key. This canonical identifier invokes your skill via /skill-name in Instagit Skills.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: how-to-guide
- Published: 2026-09-07

---

**A skill's name is defined in the YAML frontmatter of its [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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

```markdown
---
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)](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md)

  ```markdown
  ---
  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)](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/skills/improve-claude-md/SKILL.md)

  ```markdown
  ---
  name: improve-claude-md
  …
  ---
  ```

## How the Runtime Extracts the Skill Name from Frontmatter

The skill loader processes [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) files and delegates YAML parsing to the **gray-matter** library, listed in the repository's [`package.json`](https://github.com/humanlayer/skills/blob/main/package.json).

### Core Loading Mechanism

In [`src/skillLoader.ts`](https://github.com/humanlayer/skills/blob/main/src/skillLoader.ts), the extraction workflow follows this pattern:

```js
// 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`](https://github.com/humanlayer/skills/blob/main/SKILL.md) with the required frontmatter structure:

```markdown
---
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

```js
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

```js
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`](https://github.com/humanlayer/skills/blob/main/SKILL.md) frontmatter blocks.

## Key Files Behind Frontmatter Name Resolution

| Role | File Path |
|------|-----------|
| **Example skill definition** | [`plugins/show-me/skills/show-me/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md) |
| **Alternative skill example** | [`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) |
| **Core loader implementation** | [`src/skillLoader.ts`](https://github.com/humanlayer/skills/blob/main/src/skillLoader.ts) |
| **Dependency manifest (gray-matter)** | [`package.json`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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.