# Claude Skills - Format Requirements

## 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`.

```markdown
---
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)

```yaml
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:

```bash
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 |