our-claude-skills/reference/SKILL-FORMAT-REQUIREMENTS.md

Claude Skills - Format Requirements

Going-forward standard: each skill also gets a root SKILL.md (official Agent Skills format, natively loadable) alongside the code/ + desktop/ packaging described below. To add one to an existing skill, see SKILL-MIGRATION-GUIDE.md. This document remains the spec for the dual-platform packaging layers.

Overview

This document describes the format requirements for Claude Skills in this repository. Skills support dual-platform development (Claude Code and Claude Desktop) with separated concerns.

Desktop Skill Structure

For Claude Desktop skills:

skill-name/
└── desktop/
    ├── SKILL.md             # MUST have YAML frontmatter (name, description)
    ├── skill.yaml           # Optional extended metadata
    ├── tools/               # MCP tool documentation
    │   ├── firecrawl.md         # Tool-specific docs
    │   └── notion.md
    ├── references/          # Guidance docs
    └── examples/            # Usage examples

SKILL.md Format (REQUIRED)

Claude Desktop REQUIRES YAML frontmatter with at least name and description.

---
name: skill-name-here
description: |
  Brief description of what the skill does.
  Include trigger keywords in the description.
  Triggers: keyword1, keyword2.
---

# Skill Name

Purpose and overview...

## Workflow

Step-by-step instructions...

## MCP Tool Usage

Tool-specific guidance...

skill.yaml (Optional, for extended metadata)

name: skill-name-here
description: Brief description of what the skill does and trigger keywords

# Optional fields
allowed-tools:
  - mcp__firecrawl__*
  - mcp__notion__*
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - WebFetch

license: MIT  # or Internal-use Only

triggers:
  - keyword1
  - keyword2

tools/ Directory

Document MCP tools used by the skill:

File	Purpose
firecrawl.md	Firecrawl MCP tool usage
notion.md	Notion MCP tool usage
perplexity.md	Perplexity MCP tool usage
chrome-devtools.md	Chrome DevTools MCP tool usage
claude-core.md	Claude core tools (Read, Write, Edit, Bash, Glob, Grep)
webfetch.md	WebFetch tool usage

Code Skill Structure

For Claude Code skills:

skill-name/
└── code/
    ├── CLAUDE.md            # Action-oriented directive
    ├── scripts/             # Executable Python/Bash scripts
    └── references/          # Documentation

Key Requirements

1. Metadata (skill.yaml)

• name: Required, lowercase with hyphens
• description: Required, include trigger keywords
• allowed-tools: Optional, list of permitted tools
• license: Optional, MIT or Internal-use Only

2. File Structure

• All files must be inside the skill folder
• Desktop version in desktop/ subdirectory
• Code version in code/ subdirectory
• Subfolders (tools/, references/, examples/) are allowed

3. Naming Conventions

• Use lowercase with hyphens for skill name
• No spaces or special characters in folder/file names
• Skill numbers are two-digit prefixes (00-99)

Full Directory Structure

XX-skill-name/
├── code/                    # Claude Code version
│   ├── CLAUDE.md            # Action-oriented directive
│   ├── scripts/             # Executable Python/Bash
│   └── references/          # Documentation
│
├── desktop/                 # Claude Desktop version
│   ├── skill.yaml           # Metadata
│   ├── SKILL.md             # Content only
│   ├── tools/               # MCP tool documentation
│   ├── references/          # Guidance docs
│   └── examples/            # Usage examples
│
└── README.md                # Overview (optional)

Migration Script

To migrate existing SKILL.md files with frontmatter to the new structure:

python scripts/migrate-skill-structure.py --dry-run   # Preview
python scripts/migrate-skill-structure.py             # Execute

The script:

1. Extracts YAML frontmatter to skill.yaml
2. Strips frontmatter from SKILL.md
3. Creates tools/ directory
4. Generates tool stub files based on allowed-tools

Required vs Optional Fields

SKILL.md Frontmatter (Required)

Field	Required	Description
name	Yes	Skill identifier in kebab-case
description	Yes	Multi-line, include trigger keywords

skill.yaml (Optional)

Field	Description
name	Same as SKILL.md
description	Same or extended
allowed-tools	List of permitted tools
license	MIT, Internal-use Only
triggers	Explicit trigger list