Frontmatter Reference

Agent frontmatter

---
name: python-craftsperson
description: |
  Use this agent when writing, reviewing, or maintaining Python code.
version: 1.3.1
model: sonnet
deprecated: true
deprecated_reason: Replaced by python-craftsperson-v2
deprecated_replacement: python-craftsperson-v2
---
FieldRequiredTypeDescription
nameYesstringKebab-case identifier
descriptionYesstringWhen to use — include examples for matching
modelYesstringsonnet, opus, haiku, or inherit
versionNostringSemver version
deprecatedNobooleantrue to mark deprecated
deprecated_reasonNostringWhy deprecated — include actionable info
deprecated_replacementNostringReplacement artifact name

Skill frontmatter (SKILL.md)

---
name: blog-image-generator
description: Generate images for blog posts.
version: 1.0.0
---
FieldRequiredTypeDescription
nameYesstringKebab-case, must match parent directory name
descriptionYesstringWhat + when to use
versionNostringSemver version
deprecatedNobooleantrue to mark deprecated
deprecated_reasonNostringWhy deprecated
deprecated_replacementNostringReplacement artifact name

marketplace.json

{
  "name": "marketplace-id",
  "owner": { "name": "Author", "email": "author@example.com" },
  "metadata": { "description": "...", "version": "1.0.0" },
  "plugins": [{
    "name": "plugin-id",
    "description": "...",
    "source": "./",
    "agents": ["./agents/my-agent.md"],
    "skills": ["./skills/my-skill"]
  }]
}

The metadata block — and both of its fields, description and version — is optional, matching the Claude Code marketplace spec; a partial or absent metadata block parses fine. (cmx once required both fields, so a source that omitted either failed to load during the survey that backs cmx list and cmx doctor.)