SKILL.md frontmatter reference

Every YAML frontmatter field a Claude Code SKILL.md recognizes — what each does, when you need it, and how the ClaudSkills registry indexes it. Two fields are required (name, description); everything else is optional metadata that improves discovery and behavior.

Quick reference

Field	Type	Required	Used by
name	string	Yes	Claude Code, registry
description	string	Yes	Claude Code (auto-trigger), registry, SERP snippet
model	string	Optional	Claude Code (model selection hint)
allowed-tools	list	Optional	Claude Code (tool whitelist)
user-invokable	bool	Optional	Claude Code (slash-command exposure)
tags	list	Optional	Registry (tag landing pages, related-skill ranking)
category	string	Optional	Registry (overridden if classifier disagrees)
version	string	Optional	Registry (display only)
license	string	Optional	Registry (attribution display)
author	string	Optional	Registry (display only)
argument-hint	string	Optional	Claude Code (slash-command UI)
metadata.*	nested	Optional	Skill-specific (free-form)

Required fields

name

Short identifier — typically matches the directory slug. Used as the canonical handle in Claude Code's skill list and as the H1 on the registry page. Convention: lowercase, hyphen-separated, under 40 chars. Examples: commit-push-pr, fabric, pre-mortem, osint.

Avoid spaces, capital letters, underscores, and slashes. The registry slugifies whatever you write (so "My Cool Skill" becomes my-cool-skill) but it's cleaner if your value is already slug-shaped.

description

The most important field — drives Claude Code's auto-activation matching AND becomes the meta description on the registry page (which becomes the SERP snippet). Two responsibilities, both critical:

• For Claude: tell it what the skill does AND when to invoke it. Concrete trigger phrases beat clever taglines. The phrase "Use when…" is a useful pattern.
• For SEO: stay in the 150-160 char Google sweet spot. Lead with the value prop, mention the use case.

YAML supports both inline strings and multi-line block scalars:

description: One-line description here.

Or for longer content:

description: |
  Multi-line description block.
  Useful when you need 2-3 sentences without escaping quotes.
  Keeps the YAML readable.

Behavior fields (Claude Code)

model

Hints which Claude model the skill should run on. Most skills don't need this — Claude Code uses the user's session default. Useful for:

• Skills that require strong reasoning → model: opus
• Skills that need fast turnaround on simple text → model: haiku
• Skills with cost-sensitive batch operations → model: haiku

Acceptable values are model family aliases (opus, sonnet, haiku) or explicit model IDs (claude-opus-4-7, etc.). Aliases are more durable across model releases.

allowed-tools

List of Claude Code tools the skill is permitted to use. When set, Claude limits itself to this whitelist while the skill is active — useful for security-sensitive skills that should never write files or shell out.

allowed-tools:
  - Read
  - Grep
  - Bash
  - WebFetch

Common tool names: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, Agent. Omit the field entirely if your skill needs the default unrestricted toolset.

user-invokable

Boolean (default false). When true, the skill becomes available as an explicit slash command in Claude Code (e.g., /my-skill) — the user can invoke it directly even if their prompt doesn't match the description.

user-invokable: true
argument-hint: "[topic to research]"

Pair with argument-hint when the skill expects a parameter. Most skills leave this unset — auto-activation handles 90% of use cases.

argument-hint

String shown to the user in Claude Code's slash-command UI as a placeholder. Only meaningful when user-invokable: true. Examples: "[file path]", "[topic to research]", "[start date] [end date]".

Registry / discovery fields

tags

List of strings the registry uses to build tag landing pages and rank related skills. The ClaudSkills tag taxonomy follows a namespaced convention:

• lang:python, lang:typescript, lang:rust — primary programming language
• framework:react, framework:django, fw:flutter — framework or library
• cloud:aws, cloud:gcp, cloud:cloudflare — cloud platform
• tool:docker, tool:github, tool:salesforce — third-party tool or service
• ai:claude, ai:gemini, ai:openai, ai:mcp — AI provider, model, or runtime
• type:audit, type:integration, type:generator, type:review, type:cli, type:scanner, type:debug, type:agent — behavioral type

Mix freely — most skills carry 3-8 tags spanning multiple namespaces. Untyped tags (no namespace prefix) work too but don't get rolled up into the topic taxonomy.

category

One of the 10 ClaudSkills top-level categories: security, engineering, growth, sales, content, science, product, tools, ads, general. The registry's classifier overrides this field if it disagrees (the classifier is more reliable than author self-declaration across 56k mined skills) — so this field is more a hint than an authority.

version

Semver-ish string. Display only — Claude Code doesn't enforce versioning between sessions. Common values: 1.0.0, 2024.11.0, v3.2-beta.

license

SPDX identifier or freeform string. The registry preserves whatever you set; common values include MIT, Apache-2.0, BSD-3-Clause, UNLICENSE. If your skill ships embedded prompts or example data with a different license, mention it in the body — the frontmatter field captures the primary license.

author

Display string — usually a name or handle. The registry derives attribution from the source GitHub repo's owner; this field is for cases where the repo owner differs from the actual author (e.g., contributions to a monorepo).

Free-form metadata

metadata.*

Anything under a top-level metadata: map is preserved verbatim by the registry but not interpreted. Use it for skill-specific config that the body references:

metadata:
  api_base: https://api.example.com/v1
  rate_limit: 60
  default_model: claude-sonnet-4-6

The body can then reference these values: "Use the api_base from frontmatter for all calls." This is the cleanest way to make config visible at the top of the file rather than buried in body prose.

Complete example

---
name: cold-email-writer
description: |
  Generates cold outreach emails in the user's brand voice from a
  prospect description and value proposition. Use when the user mentions
  cold email, outbound, prospecting, or sales outreach.
model: sonnet
allowed-tools:
  - Read
  - Bash
  - WebFetch
user-invokable: true
argument-hint: "[prospect description]"
tags:
  - type:generator
  - lang:python
  - tool:salesforce
  - ai:claude
category: sales
version: 2.1.0
license: MIT
author: Adam Lankamer
metadata:
  brand_voice_path: ~/.config/cold-email/brand-voice.md
  default_max_words: 120
  default_cta: "Book a 15-min intro call"
---

# Cold Email Writer

[skill body starts here...]

---

Now you know every field. The next question is usually "when do I use a skill versus an MCP server?" — see Claude Code skills vs MCP servers.

Found a missing field or schema change? Email acreatorstore@translatea.com.