93 lines
2.9 KiB
Markdown
93 lines
2.9 KiB
Markdown
# YAML Frontmatter Reference
|
|
|
|
## Required Fields
|
|
|
|
```yaml
|
|
---
|
|
name: skill-name-in-kebab-case
|
|
description: What it does and when to use it. Include specific trigger phrases.
|
|
---
|
|
```
|
|
|
|
## All Optional Fields
|
|
|
|
```yaml
|
|
---
|
|
name: skill-name
|
|
description: [required - under 200 chars]
|
|
license: MIT # Open-source license
|
|
compatibility: Requires Python 3.10+, network access # 1-500 chars, environment needs
|
|
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # Restrict tool access
|
|
metadata: # Custom key-value pairs
|
|
author: Company Name
|
|
version: 1.0.0
|
|
mcp-server: server-name
|
|
category: productivity
|
|
tags: [project-management, automation]
|
|
documentation: https://example.com/docs
|
|
support: support@example.com
|
|
---
|
|
```
|
|
|
|
## Field Details
|
|
|
|
### name (required)
|
|
- Supports either `skill-name` or `namespace:skill-name` (for example `ck:plan`)
|
|
- If namespaced, namespace and skill id both use kebab-case only (no spaces, no capitals)
|
|
- Folder name must match the skill id segment (after `:`)
|
|
- Cannot contain "claude" or "anthropic" (reserved)
|
|
|
|
### description (required)
|
|
- Under 200 characters (1024 max per spec, but 200 for this project)
|
|
- Structure: `[What it does] + [When to use it] + [Key capabilities]`
|
|
- Include trigger phrases users would actually say
|
|
- Mention relevant file types if applicable
|
|
- Use third-person: "This skill should be used when..."
|
|
|
|
### license (optional)
|
|
- Common: MIT, Apache-2.0
|
|
- Reference full terms in LICENSE.txt if needed
|
|
|
|
### compatibility (optional)
|
|
- 1-500 characters
|
|
- Environment requirements: intended product, system packages, network access
|
|
|
|
### allowed-tools (optional)
|
|
- Restricts which tools the skill can use
|
|
- Space-separated tool patterns
|
|
|
|
### metadata (optional)
|
|
- Any custom key-value pairs
|
|
- Suggested: author, version, mcp-server, category, tags
|
|
|
|
## Security Restrictions
|
|
|
|
**Forbidden in frontmatter:**
|
|
- XML angle brackets (`< >`) — frontmatter appears in system prompt, could inject instructions
|
|
- Skills named with "claude" or "anthropic" prefix (reserved)
|
|
|
|
**Allowed:**
|
|
- Standard YAML types (strings, numbers, booleans, lists, objects)
|
|
- Custom metadata fields
|
|
- Long descriptions up to 1024 characters (project standard: 200)
|
|
|
|
## Description Examples
|
|
|
|
**Good — specific with triggers:**
|
|
```yaml
|
|
description: Analyzes Figma design files and generates developer handoff docs.
|
|
Use when user uploads .fig files or asks for "design specs" or "design-to-code".
|
|
```
|
|
|
|
```yaml
|
|
description: Manages Linear project workflows including sprint planning and
|
|
task creation. Use when user mentions "sprint", "Linear tasks", or "create tickets".
|
|
```
|
|
|
|
**Bad — vague or missing triggers:**
|
|
```yaml
|
|
description: Helps with projects. # Too vague
|
|
description: Creates sophisticated documentation systems. # No triggers
|
|
description: Implements the Project entity model. # Too technical
|
|
```
|