feat(reference-curator): Add pipeline orchestrator and refactor skill format
Pipeline Orchestrator: - Add 07-pipeline-orchestrator skill with code/CLAUDE.md and desktop/SKILL.md - Add /reference-curator-pipeline slash command for full workflow automation - Add pipeline_runs and pipeline_iteration_tracker tables to schema.sql - Add v_pipeline_status and v_pipeline_iterations views - Add pipeline_config.yaml configuration template - Update AGENTS.md with Reference Curator Skills section - Update claude-project files with pipeline documentation Skill Format Refactoring: - Extract YAML frontmatter from SKILL.md files to separate skill.yaml - Add tools/ directories with MCP tool documentation - Update SKILL-FORMAT-REQUIREMENTS.md with new structure - Add migrate-skill-structure.py script for format conversion Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,73 +1,162 @@
|
||||
# Claude Skills - SKILL.md Format Requirements
|
||||
# Claude Skills - Format Requirements
|
||||
|
||||
## 📝 Claude Skills SKILL.md Format
|
||||
## Overview
|
||||
|
||||
Every Claude Skill's SKILL.md file MUST start with YAML frontmatter between triple dashes:
|
||||
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 (Recommended)
|
||||
|
||||
For Claude Desktop skills, metadata is stored in a separate `skill.yaml` file:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
└── desktop/
|
||||
├── skill.yaml # Metadata (name, description, allowed-tools, license)
|
||||
├── SKILL.md # Content only (no frontmatter)
|
||||
├── tools/ # MCP tool documentation
|
||||
│ ├── firecrawl.md # Tool-specific docs
|
||||
│ └── notion.md
|
||||
├── references/ # Guidance docs
|
||||
└── examples/ # Usage examples
|
||||
```
|
||||
|
||||
### skill.yaml Format
|
||||
|
||||
```yaml
|
||||
---
|
||||
# Required fields
|
||||
name: skill-name-here
|
||||
version: 1.0.0
|
||||
description: Brief description of what the skill does
|
||||
author: Your Name/Team
|
||||
tags:
|
||||
- tag1
|
||||
- tag2
|
||||
- tag3
|
||||
---
|
||||
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
|
||||
```
|
||||
|
||||
### SKILL.md Content
|
||||
|
||||
With metadata separated into skill.yaml, SKILL.md contains only the skill directive:
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
Rest of your skill content goes here...
|
||||
Purpose and overview...
|
||||
|
||||
## Workflow
|
||||
|
||||
Step-by-step instructions...
|
||||
|
||||
## MCP Tool Usage
|
||||
|
||||
Tool-specific guidance...
|
||||
```
|
||||
|
||||
### ✅ Example:
|
||||
### 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`
|
||||
|
||||
## Legacy Format (Deprecated)
|
||||
|
||||
The old format with frontmatter embedded in SKILL.md is deprecated:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: seo-gateway-strategist
|
||||
version: 1.0.0
|
||||
description: Creates comprehensive SEO-focused gateway page strategies for Korean medical/service websites
|
||||
author: OurDigital Dr.D
|
||||
tags:
|
||||
- seo
|
||||
- strategy
|
||||
- korean-marketing
|
||||
- gateway-pages
|
||||
- content-planning
|
||||
name: skill-name
|
||||
description: Description
|
||||
allowed-tools: mcp__firecrawl__*, Read, Write
|
||||
---
|
||||
|
||||
# SEO Gateway Page Strategist
|
||||
|
||||
This skill helps you create...
|
||||
# Skill content...
|
||||
```
|
||||
|
||||
## 🔑 Key Requirements for Claude Skills
|
||||
|
||||
1. **YAML Frontmatter is MANDATORY**
|
||||
- Must be at the very beginning of SKILL.md
|
||||
- Must be wrapped in triple dashes (---)
|
||||
- Must include at minimum: name, version, description
|
||||
|
||||
2. **File Structure**
|
||||
- All files must be inside the top-level folder
|
||||
- SKILL.md must be in the root of the skill folder
|
||||
- Subfolders (templates/, scripts/, examples/) are allowed
|
||||
|
||||
3. **Naming Conventions**
|
||||
- Use lowercase with hyphens for skill name
|
||||
- No spaces or special characters in folder/file names
|
||||
- Version should follow semantic versioning (x.y.z)
|
||||
|
||||
## 📂 Correct Folder Structure
|
||||
|
||||
```
|
||||
skills-name/ # Top-level folder
|
||||
├── SKILL.md # Must have YAML frontmatter
|
||||
├── README.md # Documentation
|
||||
├── scripts/ # Optional subfolder
|
||||
│ └── keyword_analyzer.py
|
||||
├── templates/ # Optional subfolder
|
||||
│ └── *.md
|
||||
└── examples/ # Optional subfolder
|
||||
└── *.md
|
||||
```
|
||||
Use the migration script to convert to the new format.
|
||||
|
||||
Reference in New Issue
Block a user