b6a478e1df
## Summary - Add portable installation tool (`install.sh`) for cross-machine setup - Add Claude.ai export files with proper YAML frontmatter - Add multi-agent-guide v2.0 with consolidated framework template - Rename `00-claude-code-setting` → `00-our-settings-audit` (avoid reserved word) - Add YAML frontmatter to 25+ SKILL.md files for Claude Desktop compatibility ## Commits Included - `93f604a` feat: Add portable installation tool for cross-machine setup - `9b84104` feat: Add Claude.ai export for portable skill installation - `f7ab973` fix: Add YAML frontmatter to Claude.ai export files - `3fed49a` feat(multi-agent-guide): Add v2.0 with consolidated framework - `3be26ef` refactor: Rename settings-audit skill and add YAML frontmatter Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
173 lines
4.4 KiB
Markdown
173 lines
4.4 KiB
Markdown
# 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 |
|