Markdown source units use YAML frontmatter for metadata that affects validation and rendering. 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 | Skills |
| Project agent | .skillset/subagents/<agent>.md |
Schema and example | Agents |
| Rule | .skillset/rules/**/*.md |
Schema and example | Rules |
Start with Shared Metadata
A skill can begin with a small shared definition:
---
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. 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 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. Workspace defaults fill omitted values, plugin defaults refine their descendants, file fields refine the source unit, and provider fields take precedence for their target. See 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.
- Learn body expressions and opt-out behavior in preprocessing.
- Use the relevant feature reference for target rendering and diagnostics.
Scaffold new source with skillset new, then validate it with skillset check.