This chapter shows ONE common extension pattern: a metadata.json sidecar alongside SKILL.md. The specific keys below are conventions used by one public catalog (agentskills.co.il) and are useful as a worked example; other catalogs pick different keys, and some skip the sidecar entirely in favor of a locale field or language-coded subfolders. The SIDECAR pattern is the lesson, not the specific schema. If your skill is purely personal, you can skip this chapter entirely.
Why a sidecar JSON instead of nested YAML
Claude Desktop's strict YAML parser rejects nested keys inside SKILL.md frontmatter outright, refusing to load the skill at all. So the established pattern is to keep SKILL.md frontmatter minimal (name, description, license, and nothing else) and pull catalog-specific data into a separate metadata.json file alongside SKILL.md. Hosts that read only SKILL.md frontmatter (like Claude Desktop) load cleanly. Catalog tooling that reads metadata.json gets the cataloging data it needs.
Example metadata.json fields
{
"name": "id-validator",
"version": "1.2.0",
"license": "MIT",
"display_name": "ID Validator",
"display_description": "Validate national ID numbers using a check-digit algorithm. Useful for forms, test data, and catching bad IDs before submission.",
"audience": "developers",
"level": "beginner",
"tags": ["id", "validation", "checksum"],
"supported_agents": ["claude-code", "cursor", "windsurf", "claude-desktop"],
"recommended_skills": ["currency-formatter", "date-validator"]
}
display_name is the catalog title.display_description is the catalog marketing copy.audience is typically one of: developers, non-technical, professionals, mixed. Drives the catalog filter and the default writing register.level is typically one of: beginner, intermediate, advanced.tags is a string array. Catalogs filter on these.supported_agents uses canonical slugs: claude-code (not claude), gemini-cli (not gemini), cursor, windsurf, claude-desktop. Wrong slugs render as empty icons on cards in most catalog UIs.recommended_skills is an array of slugs catalogs typically render as "related skills" on the detail page. Pick skills users genuinely need alongside yours, not promotional cross-links. An ID validator recommending a phone-number formatter is honest. An ID validator recommending an unrelated marketing skill is spam.
A note on multilingual catalogs: some accept { he, en } objects for display_name, display_description, and tags instead of flat strings, so the catalog can show different copy per locale. That is a per-catalog convention, not the default shape; check your target catalog's schema before assuming either form.
The most common mistake in Chapter 3: guessing your target catalog's sidecar schema instead of reading its contribution guide. Different catalogs use different keys for the same concepts (audience vs target_users, tags vs keywords, flat strings vs {he, en} objects). Get the exact schema from the catalog before authoring; otherwise you will rework the sidecar at submission time.