# Custom Metadata Fields for Claude-Skills: Complete Schema Reference

> Explore the eight custom metadata fields in Claude-Skills: author, version, domain, triggers, role, scope, output-format, and related-skills. Understand the complete schema reference for efficient skill development.

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

---

**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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) script parses each [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/update-docs.py) script aggregates `domain`, `role`, and `scope` fields to generate the [`SKILLS_GUIDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/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

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

```yaml
---
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`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md) | Defines the metadata schema and allowed enumerations for all custom fields. | Repository root |
| [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) | Enforces metadata compliance by parsing each [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) and validating field values against [`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md) definitions. | `scripts/` directory |
| [`SKILLS_GUIDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILLS_GUIDE.md) | Auto-generated documentation that aggregates skills by `domain`, `role`, and `scope` using the metadata fields. | Repository root |
| [`scripts/update-docs.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/update-docs.py) | Generates [`SKILLS_GUIDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) files, [`validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/validate-skills.py) ensures schema compliance, and [`update-docs.py`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) file.
- The schema is **documented in [`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md)** and **enforced by [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) to parse every [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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.