# Required YAML Frontmatter Fields for Claude Skills: Complete Specification

> Learn the required YAML frontmatter fields for Claude Skills including name, description, license, and metadata. Ensure your Claude Skills pass validation with this complete specification.

- Repository: [Jeffallan/claude-skills](https://github.com/jeffallan/claude-skills)
- Tags: api-reference
- Published: 2026-02-16

---

**Every [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) file in the Jeffallan/claude-skills repository must include `name`, `description`, and `license` at the top level, plus six mandatory sub-fields (`triggers`, `role`, `scope`, `output-format`, `domain`, `related-skills`) nested under a `metadata` key to pass validation.**

The Jeffallan/claude-skills repository defines a structured format for AI agent capabilities using Markdown files with YAML frontmatter. Understanding the required YAML frontmatter fields for each skill ensures your contributions pass the automated validation pipeline and integrate correctly with the Agent Skills specification.

## Top-Level Required Fields

The validator enforces two mandatory keys at the root of the frontmatter block, while a third is required by project convention documented in [`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md).

### name

The `name` field serves as the unique identifier for the skill and must match the directory name containing the [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) file. It accepts only lowercase letters, numbers, and hyphens. For example, `vue-expert` corresponds to the `skills/vue-expert/` directory.

### description

This field contains a trigger-only sentence that tells the system when to invoke the skill. According to the specification in [`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md), the description must start with the phrase `Use when` and cannot exceed 1024 characters. Example: `Use when building Vue 3 applications with Composition API, Nuxt 3, or Quasar.`

### license

While the validator script explicitly checks only for `name` and `description` in the `REQUIRED_FIELDS` constant, the [`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md) documentation mandates that every skill include `license: MIT` to comply with the project's open-source licensing requirements.

## Mandatory Metadata Sub-Fields

All skill-specific configuration resides under the `metadata` key. The validation script defines a separate `REQUIRED_METADATA_FIELDS` list in [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) that checks for six specific sub-fields:

- **triggers**: Comma-separated keywords that cause the skill to be selected by the agent system.
- **role**: Classification of expertise level, must be one of `specialist`, `expert`, `architect`, or `engineer`.
- **scope**: Defines the skill's function, such as `implementation`, `review`, `design`, or `debugging`.
- **output-format**: Expected deliverable type, typically `code`, `document`, `report`, or `test`.
- **domain**: High-level category like `frontend`, `backend`, `api-architecture`, or `database`.
- **related-skills**: Comma-separated list of sibling skill directory names for cross-referencing capabilities.

## Validation Logic in the Source Code

The enforcement of these requirements occurs in [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py). The script defines two critical constants at lines 35-42:

```python
REQUIRED_FIELDS = ["name", "description"]
REQUIRED_METADATA_FIELDS = [
    "triggers", "role", "scope", 
    "output-format", "domain", "related-skills"
]

```

When the validation script processes each [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) file, it parses the YAML frontmatter and verifies that all keys in `REQUIRED_FIELDS` exist at the top level, and that all keys in `REQUIRED_METADATA_FIELDS` exist within the `metadata` mapping. Missing any of these fields causes the CI pipeline to fail.

## Complete Example of Valid Frontmatter

Here is the minimal valid frontmatter structure that passes validation, based on the `vue-expert` skill implementation:

```yaml
---
name: vue-expert
description: Use when building Vue 3 applications with Composition API, Nuxt 3, or Quasar.
license: MIT
metadata:
  triggers: Vue 3, Composition API, Nuxt, Pinia
  role: specialist
  scope: implementation
  output-format: code
  domain: frontend
  related-skills: typescript-pro, fullstack-guardian
---

```

Optional fields like `author` and `version` may be added under `metadata` without breaking validation, as the script only checks for the presence of the required six sub-fields.

## Summary

- Every skill file must include `name`, `description`, and `license` at the top level of the YAML frontmatter.
- The `metadata` key must contain six mandatory sub-fields: `triggers`, `role`, `scope`, `output-format`, `domain`, and `related-skills`.
- Validation occurs in [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) through the `REQUIRED_FIELDS` and `REQUIRED_METADATA_FIELDS` constants.
- The `name` field must match the directory name and use only lowercase alphanumeric characters and hyphens.
- Descriptions must begin with `Use when` to comply with the Agent Skills specification.

## Frequently Asked Questions

### What happens if I omit the license field in my skill's frontmatter?

While the automated validator in [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) only enforces `name` and `description` at the top level, the [`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md) documentation explicitly requires `license: MIT` for all skills. Omitting this field violates project conventions and may result in manual rejection during code review even if automated tests pass.

### Can I add custom fields to the metadata section?

Yes, you can include optional metadata fields such as `author`, `version`, or `last-updated` without causing validation failures. The `REQUIRED_METADATA_FIELDS` list in [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) only checks for the presence of the six mandatory keys; additional entries are ignored by the validator and allowed by the specification.

### How does the name field relate to the file structure?

The `name` field must exactly match the directory name containing the [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) file. For example, a skill with `name: vue-expert` must reside in [`skills/vue-expert/SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/skills/vue-expert/SKILL.md). This convention ensures the validation script can correctly map frontmatter declarations to physical file locations during the CI pipeline checks.

### Are there restrictions on the description field format?

Yes, the description must follow the Agent Skills specification detailed in [`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md). It must begin with the phrase `Use when` to indicate trigger conditions, and it cannot exceed 1024 characters. This format helps the agent system understand exactly when to invoke the skill based on user context and query patterns.