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/
├── bis-invoice-generator/
│ └── SKILL.md
├── bis-validator-triage/
│ └── SKILL.md
└── peppol-id-checker/
└── 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 Peppol e-invoicing collection
# bis-validator-triage Validate UBL invoices against Peppol BIS 3.0 rules and EN 16931 semantic rules. Return clear error explanations. ## When to Use - Pre-send validation of outbound invoices - Debugging validation failures from access points - Compliance checks before going live ## Process ### 1. Receive Invoice XML Accept UBL 2.1 Invoice or CreditNote XML: - File path or inline XML content - Identify document type from root element - Extract CustomizationID and ProfileID ### 2. Run Schematron Validation Apply validation rules in order: 1. EN 16931 (CEN TC434) semantic rules 2. Peppol BIS 3.0 transaction rules 3. Country-specific CIUS rules (if applicable) ### 3. Parse Validation Results For each failed assertion: - Extract rule ID (e.g., BR-01, PEPPOL-EN16931-R001) - Get human-readable error message - Identify XPath location in document - Classify severity (fatal/warning) ### 4. Generate Triage Report Provide: - Summary: pass/fail with counts - Grouped errors by category - Fix suggestions for common issues - Links to specification documentation ## Output Format | Rule ID | Severity | Location | Message | Fix | |---------|----------|----------|---------|-----| | BR-01 | fatal | /Invoice | ... | ... | ## Best Practices - Always validate before sending to production - Fix fatal errors before warnings - Test with Peppol testbed for new integrations
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.