Skill Format Specification

This document defines the format, structure, and quality standards for skills in SkillStore. Follow this specification when creating new skills or reviewing existing ones.

What is a Skill?

A skill is a self-contained unit of domain knowledge that teaches Claude Code how to perform a specific task. Each skill is a directory containing:

skill-name/
├── SKILL.md              # Required — process overview, triggers, navigation
├── references/           # Optional — detailed guides, frameworks, checklists
│   ├── guide-name.md
│   └── checklist-name.md
└── assets/               # Optional — sample outputs showing realistic deliverables
    └── sample-output.md

Skills use progressive disclosure: SKILL.md provides just enough to get started, references contain deep knowledge loaded on demand, and assets show what good output looks like.

SKILL.md Format

YAML Frontmatter (Required)

Every SKILL.md starts with YAML frontmatter:

---
name: skill-name
description: Use when [specific trigger condition]. Provides [specific value].
---

Fields:

Markdown Body Structure

The body follows a fixed structure. All sections are required unless noted otherwise.

# Skill Name

Brief description — what the skill does and the value it provides. 1-2 sentences.

## Triggers (or "When to Use")

Activate this skill when:
- [Specific trigger condition 1]
- [Specific trigger condition 2]
- [Specific trigger condition 3]

## Inputs (optional)

Gather before starting:
1. **Input name** — what it is and where to find it
2. **Input name** — what it is and where to find it

## Process

### Step 1: Phase Name
- Action items for this phase
- Reference: `references/relevant-guide.md`

### Step 2: Phase Name
- Action items for this phase
- **Skip if:** [condition when this step is unnecessary]

## Output Requirements (or "Output")

- [Deliverable 1]
- [Deliverable 2]
- [Quality standard or format requirement]

See `assets/sample-output.md` for a complete example.

## Key Rules (optional)

- [Critical constraint or best practice]
- [Common mistake to avoid]

## Quick Reference (optional)

| Situation | Action |
|-----------|--------|
| [Scenario 1] | [What to do] |
| [Scenario 2] | [What to do] |

SKILL.md Constraints

• Maximum 100 lines. This is a hard limit. SKILL.md is a navigation hub, not an encyclopedia.
• Keep process steps concise. Each step should be 2-5 bullet points.
• Detailed frameworks, techniques, and checklists belong in references/, not SKILL.md.
• Use Load: references/file.md or See references/file.md to point Claude Code to deeper content.

References Directory

References contain the detailed knowledge that skills draw upon. They are loaded on demand when Claude Code reaches the relevant process step.

Guidelines

• Target 120-200 lines each. Long enough to be comprehensive, short enough to fit in context.
• 2-3 reference files per skill is the sweet spot. More than 4 suggests the skill scope is too broad.
• Each reference must be self-contained — it should make sense without reading SKILL.md first.
• Focus on practical frameworks, not theoretical background. Include:
• Step-by-step procedures
• Decision matrices and lookup tables
• Copy-paste-ready templates
• Actionable checklists
• Use Markdown tables for structured data (multiplier tables, comparison matrices).

Naming

Use kebab-case names that describe the content:

references/
├── estimation-techniques.md     # Techniques and multiplier tables
├── wbs-template.md              # WBS structure and decomposition rules
└── bias-corrections.md          # Cognitive bias adjustments for estimates

Assets Directory

Assets contain sample outputs that demonstrate what a good deliverable looks like for this skill. They serve as both documentation and implicit quality benchmarks.

Guidelines

• Every skill should have at least 1 asset — typically sample-output.md.
• Show a realistic scenario, not a trivial example. Use industry-specific content.
• The sample output should follow the skill's own output requirements and templates.
• Include enough detail that someone could use it as a starting template.

Naming

assets/
├── sample-output.md             # Primary example deliverable
├── sample-output-complex.md     # Optional: complex scenario variant
└── sample-rfp-analysis.md       # Optional: scenario-specific example

Naming Conventions

Quality Benchmark: The Estimation Skill

The estimation skill in devflow-presale is the gold standard. Study it as a reference for quality:

What it does well:

1. Clear inputs — Lists exactly what to gather before starting (requirements, tech context, team profile, constraints, historical data).
2. Structured process — Five numbered steps with clear deliverables at each stage (Scope Decomposition, WBS Creation, Effort Sizing, Buffer Calculation, Output).
3. Concrete techniques — Names specific methods (3-point PERT estimation formula, complexity multipliers with percentage ranges).
4. Key rules — Actionable constraints ("Never estimate without a WBS", "Flag any task above 40 hours", "Round to 0.5 man-day precision").
5. Reference integration — Each process step points to a specific reference file for detailed techniques.
6. Sample output — The assets/sample-output.md shows a complete estimation deliverable.
7. Concise — Achieves all of the above in 77 lines.

Example Skill Structure

Here is a minimal but complete skill:

requirement-analysis/
├── SKILL.md                              # 60-80 lines
├── references/
│   ├── extraction-techniques.md          # ~150 lines: methods for pulling requirements from RFPs
│   └── gap-analysis-framework.md         # ~120 lines: checklist for identifying scope gaps
└── assets/
    └── sample-output.md                  # ~100 lines: realistic analyzed RFP with categorized requirements

The SKILL.md would define triggers (new RFP received, scope change request), a 3-4 step process (document review, requirement extraction, gap analysis, output), and point to references for detailed techniques.

Anti-Patterns

Avoid these common mistakes when creating skills:

Quality Checklist

Before submitting a skill, verify:

• [ ] SKILL.md has valid YAML frontmatter with name and description
• [ ] name matches directory name (kebab-case)
• [ ] description includes trigger conditions and value proposition
• [ ] SKILL.md is under 100 lines
• [ ] "When to Use" section has 3+ specific trigger conditions
• [ ] Process has numbered steps with concrete actions
• [ ] Each process step references a relevant reference file
• [ ] references/ contains 2-3 files of 120-200 lines each
• [ ] assets/ contains at least one realistic sample output
• [ ] Sample output follows the skill's own output format
• [ ] References are self-contained and practical (not theoretical)