license (optional):

• • Use if making skill open source
• • Common: MIT, Apache-2.0

compatibility (optional)

• • 1-500 characters
• • Indicates environment requirements: e.g. intended product, required system packages, network access needs, etc.

metadata (optional):

• • Any custom key-value pairs
• • Suggested: author, version, mcp-server
• • Example:

  ```yaml
  metadata:
    author: ProjectHub
    version: 1.0.0 mcp-server: projecthub
  ```

Security restrictions

Forbidden in frontmatter:

• • XML angle brackets (< >)
• • Skills with "claude" or "anthropic" in name (reserved)

Why: Frontmatter appears in Claude's system prompt. Malicious content could inject instructions.

Writing effective skills

The description field

According to Anthropic's engineering blog : "This metadata...provides just enough information for Claude to know when each skill should be used without loading all of it into context." This is the first level of progressive disclosure.

Structure:

[What it does] + [When to use it] + [Key capabilities]

Examples of good descriptions:

# Good - specific and actionable
description: Analyzes Figma design files and generates
developer handoff documentation. Use when user uploads .fig
files, asks for "design specs", "component documentation", or
"design-to-code handoff".

# Good - includes trigger phrases
description: Manages Linear project workflows including sprint
planning, task creation, and status tracking. Use when user
mentions "sprint", "Linear tasks", "project planning", or asks
to "create tickets".

# Good - clear value proposition
description: End-to-end customer onboarding workflow for
PayFlow. Handles account creation, payment setup, and
subscription management. Use when user says "onboard new
customer", "set up subscription", or "create PayFlow account".