Custom Metadata Fields for Claude-Skills: Complete Schema Reference

Claude-Skills defines eight custom metadata fields—author, version, domain, triggers, role, scope, output-format, and related-skills—that live under the metadata: block in every skill's YAML front matter, enforced by the scripts/validate-skills.py validation script.

The Jeffallan/claude-skills repository standardizes AI capability definitions through structured YAML front matter. Beyond required top-level keys like name, description, and license, each skill includes a metadata object containing custom fields that govern discovery, versioning, execution scope, and cross-skill relationships.

Complete List of Custom Metadata Fields for Claude-Skills

The schema defines eight distinct fields within the metadata block. According to the project configuration in CLAUDE.md (lines 62-70), these fields are mandatory for validation and documentation generation.

1. author

Identifies the skill creator's GitHub profile.

• Format: URL string (https://github.com/username)
• Example: https://github.com/jeffallan

2. version

Tracks the skill's semantic version for compatibility management.

• Format: Quoted string following SemVer ("MAJOR.MINOR.PATCH")
• Example: "1.2.0"

3. domain

Categorizes the skill into high-level technical areas.

• Allowed values: frontend, backend, devops, data, security, mobile, ai-ml, general
• Example: frontend

4. triggers

Defines searchable keywords that activate the skill during query matching.

• Format: Comma-separated list (no spaces)
• Example: react,vue,angular,css,html

5. role

Specifies the expertise level of the skill author.

• Allowed values: specialist, expert, architect, engineer
• Example: expert

6. scope

Determines the type of work the skill addresses.

• Allowed values: implementation, review, design, system-design, testing, analysis, infrastructure, optimization, architecture
• Example: implementation

7. output-format

Controls how the skill's results are rendered.

• Allowed values: code, document, report, architecture, specification, schema, manifests, analysis, analysis-and-code, code+analysis
• Example: code

8. related-skills

Creates bidirectional links to complementary skills.

• Format: Comma-separated directory names (must match existing skill folders)
• Example: design-mentor,accessibility-auditor

Metadata Schema Validation and Enforcement

The repository enforces metadata compliance through automated validation. The scripts/validate-skills.py script parses each SKILL.md file and verifies that:

1. The metadata block exists
2. All eight custom fields are present
3. Values match the allowed enumerations defined in CLAUDE.md
4. related-skills references resolve to existing directories

Validation failures block CI/CD pipelines, ensuring that only properly formatted skills enter the main branch. This strict schema guarantees that the SKILLS_GUIDE.md documentation generator and the skill discovery CLI can rely on consistent data structures.

Practical Usage of Metadata Fields

The custom metadata fields drive several platform features beyond simple documentation:

Discovery and Triggering

The triggers field powers the search index. When users query the CLI or web interface with keywords like "react" or "terraform", the system matches against these comma-separated values to surface relevant skills.

Documentation Generation

The scripts/update-docs.py script aggregates domain, role, and scope fields to generate the SKILLS_GUIDE.md. This creates hierarchical views grouping skills by technical area (frontend, backend, devops) and expertise level (specialist vs. architect).

Version Management

The version field enables semantic versioning in CI pipelines. Downstream systems can parse the quoted SemVer string to detect breaking changes or enforce compatibility requirements when loading skills.

Cross-Skill Navigation

related-skills creates a graph of complementary capabilities. The UI uses this to display "You might also like" suggestions, linking implementation skills to review or design counterparts.

Output Rendering

The output-format field instructs the rendering engine how to structure responses. Values like analysis-and-code trigger mixed-mode output, while code returns pure snippets without explanatory text.

Example Skill Definitions with Custom Metadata

Below are concrete implementations demonstrating the metadata schema in production skills.

Frontend Expert Skill

---
name: frontend-expert
description: Use when a developer needs advanced help with modern front-end frameworks.
license: MIT
metadata:
  author: https://github.com/yourname
  version: "1.2.0"
  domain: frontend
  triggers: react,vue,angular,css,html
  role: expert
  scope: implementation
  output-format: code
  related-skills: design-mentor,accessibility-auditor
---

This configuration targets implementation tasks for React, Vue, and Angular projects. The output-format: code ensures responses contain only source code, while related-skills links to design and accessibility companions.

DevOps Engineer Skill

---
name: devops-engineer
description: Use when setting up CI/CD pipelines, infrastructure as code, or monitoring solutions.
license: MIT
metadata:
  author: https://github.com/devops-guru
  version: "0.9.3"
  domain: devops
  triggers: ci,cd,terraform,kubernetes,monitoring
  role: specialist
  scope: design
  output-format: analysis-and-code
  related-skills: cloud-architect,security-reviewer
---

Here, scope: design indicates architectural focus rather than implementation details. The analysis-and-code output format delivers both explanatory text and configuration files (e.g., Terraform modules) in a single response.

Key Files in the Metadata Ecosystem

The custom metadata fields are centralized in specific files that govern validation, documentation, and skill definition.

File	Purpose	Location
CLAUDE.md	Defines the metadata schema and allowed enumerations for all custom fields.	Repository root
scripts/validate-skills.py	Enforces metadata compliance by parsing each SKILL.md and validating field values against CLAUDE.md definitions.	scripts/ directory
SKILLS_GUIDE.md	Auto-generated documentation that aggregates skills by domain, role, and scope using the metadata fields.	Repository root
scripts/update-docs.py	Generates SKILLS_GUIDE.md by reading metadata from all skill directories.	scripts/ directory
skills/*/SKILL.md	Individual skill definitions containing the metadata: block with all eight custom fields.	skills/<skill-name>/

These files create a robust pipeline: skill authors define metadata in their SKILL.md files, validate-skills.py ensures schema compliance, and update-docs.py propagates the metadata into human-readable guides.

Summary

• Claude-Skills defines eight custom metadata fields (author, version, domain, triggers, role, scope, output-format, related-skills) that reside under the metadata: key in every SKILL.md file.
• The schema is documented in CLAUDE.md and enforced by scripts/validate-skills.py, ensuring all skills meet consistency requirements before merging.
• Enumerated values control domain (e.g., frontend, devops), role (e.g., expert, architect), scope (e.g., implementation, design), and output-format (e.g., code, analysis-and-code).
• The metadata powers skill discovery (via triggers), documentation generation (via scripts/update-docs.py), version management, and cross-skill navigation (via related-skills).

Frequently Asked Questions

What is the purpose of the triggers field in Claude-Skills metadata?

The triggers field defines a comma-separated list of keywords that activate the skill during search queries. When users interact with the CLI or web interface, the system indexes these values to surface relevant skills matching the query terms, functioning as a search index for skill discovery.

How does Claude-Skills validate that metadata fields contain correct values?

The repository uses scripts/validate-skills.py to parse every SKILL.md file and verify that all eight custom metadata fields are present. The script checks values against the allowed enumerations defined in CLAUDE.md (lines 62-70), ensuring that fields like domain, role, and scope contain only valid options before allowing CI/CD pipeline completion.

What is the difference between scope and output-format in the metadata schema?

The scope field describes the type of work the skill addresses, using values like implementation, design, or review to indicate the activity phase. In contrast, output-format controls the rendering shape of the response, specifying whether the skill returns code, analysis, analysis-and-code, or other structured formats to the end user.

Can I reference other skills within a skill definition?

Yes, the related-skills field allows you to create bidirectional links to complementary skills by listing comma-separated directory names that correspond to existing skill folders. This enables the "You might also like" feature in the UI and helps users navigate from implementation skills to related design or review skills within the ecosystem.

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