The SKILL.md Standard
A simple, portable format for teaching AI assistants domain-specific workflows. Write once, run anywhere.
What is SKILL.md?
SKILL.md is a markdown-based format for encoding procedural knowledge that AI coding assistants can follow. Each skill file contains structured instructions for completing a specific type of task.
This standard defines required sections, recommended ordering, and formatting conventions so skills are portable across assistants and easy to reason about.
Portable across Claude, Codex, Cursor, and more
Structured format for consistent AI behavior
Human-readable markdown you can version control
No special syntax — just organized documentation
File Structure
A skill is simply a folder containing a SKILL.md file
skills/
├── bank-reconciliation/
│ └── SKILL.md
├── expense-categorizer/
│ └── SKILL.md
└── invoice-organizer/
└── SKILL.mdRequired Sections
Every SKILL.md file must include these four sections in order
Title & Description
The H1 heading is the skill name in kebab-case. The first paragraph is a one-sentence description of what the skill does.
When to Use
Bullet list of 3-5 scenarios where this skill applies. Helps the AI decide when to load the skill automatically.
Process
Numbered steps (H3 headings) with detailed instructions. This is the core of the skill — be explicit and procedural.
Output Format
Describes exactly what the skill produces: file formats, table schemas, report structures. Include an example.
Optional Sections
SKILL.md Template
Copy this template to start writing your own skill
# skill-name One-line description of what the skill does. ## When to Use - Scenario 1 - Scenario 2 - Scenario 3 ## Process ### 1. First Step Detailed instructions for step 1... ### 2. Second Step Detailed instructions for step 2... ## Output Format Describe expected outputs... ## Best Practices - Practice 1 - Practice 2
Design Principles
Follow these principles when writing skills for best results
Be Specific
Include exact formats, examples, and templates. The more specific your instructions, the more consistent the AI's output will be.
Be Procedural
Break complex tasks into numbered steps. Each step should be independently actionable with clear inputs and outputs.
Be Portable
Skills should work across different AI assistants. Avoid tool-specific syntax or assumptions about the runtime.
Be Complete
Include everything needed to complete the task. Don't assume the AI has domain knowledge beyond the skill file.
Complete Example
Here's a real skill from our accounting collection
# expense-categorizer Classify transactions into accounting categories based on vendor, description, and amount patterns. ## When to Use - Monthly transaction categorization - Chart of accounts mapping - Spend analysis and reporting ## Process ### 1. Receive Transaction Data Accept transactions with these fields: - Date (required) - Description/Memo (required) - Amount (required) - Vendor/Payee (optional) ### 2. Clean and Normalize Standardize transaction data: - Remove card numbers: `VISA ***4521` → remove - Extract vendor: `SQ *COFFEE SHOP` → `Coffee Shop` - Standardize case: `AMAZON.COM` → `Amazon` ### 3. Apply Categorization Rules Match transactions using this hierarchy: 1. Exact vendor match 2. Vendor pattern match (*AIRLINES* → Travel) 3. Amount-based rules 4. Description keywords ### 4. Generate Output Provide: - Categorized transaction list (CSV) - Summary by category - Items flagged for review ## Output Format | Date | Vendor | Amount | Category | Confidence | |------|--------|--------|----------|------------| | ... | ... | ... | ... | High/Med/Low | ## Best Practices - Start with high-confidence categorizations - Batch similar uncertain items for review - Track vendor mappings for consistency
Authoring Checklist
Before publishing, verify your skill meets these criteria
Ready to create your own skills?
Fork our repo and start building domain-specific skills for your workflow.