Required YAML Frontmatter Fields for Claude Skills: Complete Specification

Every 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.

name

The name field serves as the unique identifier for the skill and must match the directory name containing the 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, 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 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 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. The script defines two critical constants at lines 35-42:

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

When the validation script processes each 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:

---
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 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 only enforces name and description at the top level, the 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 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 file. For example, a skill with name: vue-expert must reside in 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. 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.

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