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]

## Core Principles

> **Iron Law:** [The most critical rule that must never be violated]

1. **Principle 1** — Reason why this matters
2. **Principle 2** — Reason why this matters
3. **Principle 3** — Reason why this matters

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

## Workflow

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

**Hard Gate:** [What must be true before moving to Phase 2]

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

**Hard Gate:** [What must be true before moving to Phase 3]

### Phase 3: Phase Name
- Action items for this phase

## Common Pitfalls

| Pitfall | Consequence | Solution |
|---------|-------------|----------|
| [Mistake 1] | [What goes wrong] | [How to avoid] |
| [Mistake 2] | [What goes wrong] | [How to avoid] |
| [Mistake 3] | [What goes wrong] | [How to avoid] |

## Red Flags

Stop and reassess if you see:
- [Sign 1 that approach is wrong]
- [Sign 2 that approach is wrong]
- [Sign 3 that approach is wrong]

## Decision Framework (optional)

| Situation | Decision | Rationale |
|-----------|----------|-----------|
| [Scenario 1] | [What to do] | [Why] |
| [Scenario 2] | [What to do] | [Why] |

## Output Requirements (or "Output")

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

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

SKILL.md Constraints

• Target 200-400 lines. Use progressive disclosure — SKILL.md contains workflow, principles, pitfalls, red flags. References contain deep expert knowledge.
• 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 400-800 lines each. Long enough for deep expert knowledge, structured for easy navigation.
• 2-4 reference files per skill, each covering a focused domain area.
• 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. Well-structured — Achieves all of the above with the new template format (Core Principles, Workflow with Hard Gates, Common Pitfalls, Red Flags).

Example Skill Structure

Here is a minimal but complete skill:

requirement-analysis/
├── SKILL.md                              # 200-400 lines
├── references/
│   ├── extraction-techniques.md          # ~500 lines: methods for pulling requirements from RFPs
│   └── gap-analysis-framework.md         # ~600 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 200-400 lines with all required sections
• [ ] Core Principles section has at least 1 Iron Law or 3+ principles
• [ ] "When to Use" section has 3+ specific trigger conditions and anti-triggers
• [ ] Workflow has phases with Hard Gates between them
• [ ] Common Pitfalls table has at least 3 entries
• [ ] Red Flags section has at least 2-3 signs
• [ ] references/ contains 2-4 files of 400-800 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)
• [ ] No duplication between SKILL.md and references