---
title: "Frontmatter"
description: "Choose and validate metadata for Skillset skills, agents, and rules."
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus.focal.host/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontmatter

<a id="frontmatter"></a>

Markdown [source units](/skillset/glossary/#source-unit) use YAML frontmatter for metadata that affects validation and [rendering](/skillset/glossary/#render). Put shared intent in common fields and use a provider block only for a real provider-specific difference.

| Source type | Conventional path | Exact contract | Behavior |
| --- | --- | --- | --- |
| Skill | `.skillset/skills/<skill>/SKILL.md` | [Schema and example](/skillset/reference/schemas/) | [Skills](/skillset/reference/features/skills/) |
| Project agent | `.skillset/subagents/<agent>.md` | [Schema and example](/skillset/reference/schemas/) | [Agents](/skillset/reference/features/agents/) |
| Rule | `.skillset/rules/**/*.md` | [Schema and example](/skillset/reference/schemas/) | [Rules](/skillset/reference/features/rules/) |

## Start with Shared Metadata

A skill can begin with a small shared definition:

```yaml
---
name: docs-review
description: Review documentation for accuracy and navigation.
tools: readonly
---
```

Use top-level fields for the source type's portable meaning. The nested `skillset` block carries Skillset source metadata such as schema, preprocessing, origin, version baselines, and licensing. Declare machine-checked package, tool, or version requirements under [`supports`](/skillset/reference/features/supports/). That is separate from the Agent Skills `compatibility` field, a short free-text note about the environment a skill needs.

The field sets differ by source type. For example, skills can declare resources and tool intent, agents can declare skills and an initial prompt, and rules can declare path scoping and a dialect. Use the generated [frontmatter schemas and examples](/skillset/reference/schemas/) rather than copying a field list from prose.

## Let Paths Supply Identity

Directory names supply machine identity when the source layout already makes it unambiguous. A skill's directory is its skill id, and a plugin's directory is its plugin id. Do not repeat an id under a second key merely for emphasis.

Skills use the standard top-level `name` and `version` fields when those values are required. Root and plugin source metadata may use `skillset.name`; an explicit plugin name must agree with its directory. Retired forms such as `skillset.id` and skill-local `skillset.name` fail instead of creating competing identities.

## Apply Inheritance Deliberately

Shared metadata participates in the configuration [cascade](/skillset/glossary/#cascade). [Workspace](/skillset/glossary/#workspace) defaults fill omitted values, plugin defaults refine their descendants, file fields refine the source unit, and provider fields take precedence for their [target](/skillset/glossary/#target). See [target overrides](/skillset/configuration/target-overrides/) before adding a provider block.

Licensing follows the same local-first model. A scope can declare `skillset.license`, inherit its parent license, or set `skillset.license: none` to opt out. A top-level `license: none` is not the opt-out; Skillset reads licensing only from the `skillset` block. A same-scope `LICENSE.txt` is also source, but it cannot conflict with an explicit opt-out.

## Keep Specialized Syntax with Its Owner

- Configure tool intent through [tools policy](/skillset/configuration/tools-policy/).
- Learn body expressions and opt-out behavior in [preprocessing](/skillset/reference/source/preprocessing/).
- Use the relevant [feature reference](/skillset/reference/features/) for target rendering and diagnostics.

Scaffold new source with [`skillset new`](/skillset/reference/cli/new/), then validate it with [`skillset check`](/skillset/reference/cli/check/).

Source: https://nimbus.focal.host/skillset/configuration/frontmatter/index.mdx