| name | skill-engineering-standard |
| description | Design and build production-grade AI skills using the Skill Engineering Standard (SES). Use when asked to "build a skill", "create a skill", "design a skill", "write a SKILL.md", "skill engineering", "SES", or when packaging workflows, automations, or instructions into a reusable skill for Claude or OpenClaw. Covers full lifecycle: spec, structure, frontmatter, progressive disclosure, testing, and distribution. Based on the Anthropic Complete Guide + OpenClaw conventions. |
Skill Engineering Standard (SES)
Category: The third evolution of AI engineering.
Prompt Engineering (2024) → Context Engineering (2025) → Skill Engineering (2026)
Skills are reusable, composable units of AI capability — not prompts, not RAG chunks. They are packaged expertise that load on demand, execute reliably, and can be shared, versioned, and deployed anywhere Claude runs.
Origin: Coined by Lennox Saint, February 10, 2026. Open standard hosted at github.com/lennoxsaint/skill-engineering-standard.
The Design Sequence
Work through these stages in order. Don't skip stages — design problems found early are cheap. Design problems found in production are expensive.
Stage 0: Clarify Intent
Answer these before writing a single line:
- What does this skill do? (one sentence, concrete)
- When should it load? (list exact phrases a user would say)
- What does success look like? (describe the output for 2–3 real examples)
- Universal or particular? — works on any Claude install, or specific to this workspace?
Universal skills: no local assumptions, generic paths, ClawHub/GitHub ready.
Particular skills: can reference local tools, workspace config, sibling skills.
Stage 1: Choose Your Skill Category
| Category | What it does | Common patterns |
|---|
| Document & Asset Creation | Produces consistent output (docs, code, reports, designs) | Templates, style guides, checklists |
| Workflow Automation | Orchestrates multi-step processes | Validation gates, MCP coordination, review loops |
| MCP Enhancement | Wraps and orchestrates MCP server tools with domain expertise | Tool sequences, error handling, domain knowledge |
| CLI Wrapper | Provides a natural language interface to a command-line tool | Input mapping, output parsing, error handling |
| Research & Analysis | Retrieves, synthesises, and presents information | Source fetching, structured output, citation |
Most real skills combine two categories. That's fine — pick the dominant one.
Stage 2: Directory Structure
your-skill-name/ ← kebab-case, matches `name` in frontmatter
├── SKILL.md ← REQUIRED. Exactly this name, case-sensitive.
├── scripts/ ← Optional. Executable code (Python, Bash, etc.)
│ └── validate.py
├── references/ ← Optional. Deep docs loaded only when needed.
│ └── api-reference.md
└── assets/ ← Optional. Templates, icons, output assets.
└── report-template.md
Rules:
- Folder name: kebab-case only. No spaces, no capitals, no underscores.
SKILL.md must be exactly SKILL.md — no variations.- Do NOT include
README.md inside the skill folder. (Use it at repo level only.)
- No XML angle brackets (
< or >) anywhere in frontmatter.
- Do NOT use
claude or anthropic in the skill name — reserved words.
Stage 3: Write the Frontmatter
The frontmatter appears in Claude's system prompt on every turn. Every character costs tokens. Be precise, not verbose.
---
name: your-skill-name
description: What the skill does. Use when user asks to [trigger phrase 1], [trigger phrase 2], or mentions [keyword]. Also triggers on [specific scenario].
homepage: https://github.com/you/repo
license: MIT
metadata:
author: Your Name
version: 1.0.0
mcp-server: optional-mcp-server-name
---
Required fields:
name — kebab-case, matches folder namedescription — MUST include: (1) what it does + (2) when to use it (trigger phrases). Max 1024 chars.
Optional fields:
license — MIT, Apache-2.0, etc. Include for open-source skills.homepage — GitHub repo URLcompatibility — environment requirements (1–500 chars)metadata — custom key-value pairs: author, version, mcp-server
For OpenClaw skills, add the openclaw metadata block:
metadata: {"openclaw":{"emoji":"🔧","requires":{"bins":["tool-name"],"env":["API_KEY"]},"install":[{"id":"brew","kind":"brew","formula":"tap/tool","bins":["tool"],"label":"Install via brew"}]}}
Note: OpenClaw requires metadata as a single-line JSON string.
Good vs Bad Descriptions
Good (specific, with triggers):
Analyzes Figma design files and generates developer handoff docs. Use when user uploads .fig files, asks for 'design specs', 'component documentation', or 'design-to-code handoff'.
Bad (vague, no triggers):
Helps with projects.
Bad (technical but no user triggers):
Implements the Project entity model with hierarchical relationships.
Stage 4: Write the SKILL.md Body
The body loads when Claude decides the skill is relevant. Write clear, actionable instructions — not documentation.
Recommended structure:
# Skill Name — Instructions
Brief one-paragraph summary of what this skill does and when it shines.
## Step 1: [First Major Action]
Clear explanation. Include concrete commands and expected output.
```bash
python scripts/fetch_data.py --id PROJECT_ID
Expected output: [describe what success looks like]
Step 2: [Next Action]
...
Examples
[Common Scenario 1]
User says: "..."
Action: ...
Result: ...
[Common Scenario 2]
...
Troubleshooting
| Error | Cause | Fix |
|---|
Connection refused | Server not running | Restart MCP server, check API key |
Rate limit hit | Too many requests | Wait 60s, retry |
References
- Full API reference:
{baseDir}/references/api-reference.md
- Template files:
{baseDir}/assets/
**Content principles:**
- Specific beats vague. Include real command examples, not pseudocode.
- Move heavy docs to `references/` — keep SKILL.md under 300 lines.
- Include at least 2 concrete examples with real user phrases.
- Add a troubleshooting section for every external dependency.
- Use validation gates in workflows: check state before proceeding, never assume.
---
### Stage 5: Progressive Disclosure
Skills load in three levels. Design each level intentionally:
| Level | When loaded | What to put here |
|-------|-------------|-----------------|
| **1 — Frontmatter** | Always (every turn) | Minimal: name, description, triggers only |
| **2 — SKILL.md body** | When skill is selected as relevant | Core instructions, steps, examples, troubleshooting |
| **3 — references/ & assets/** | When explicitly needed mid-task | Deep API docs, large templates, reference data |
**The goal:** Claude should be able to complete 80% of tasks using Level 2 alone. Level 3 is for edge cases and deep detail.
---
### Stage 6: Test Your Skill
**Triggering tests** — does the skill load when it should?
Create a trigger test list:
SHOULD trigger:
- "build me a skill for..."
- "create a SKILL.md for..."
- "I want to package this workflow as a skill"
SHOULD NOT trigger:
- "what are the top skills for a developer?"
- "I have a new skill to learn"
- "my manager has great people skills"
Target: ~90% accuracy on 10–20 test queries.
**Functional tests** — does it produce the right output?
Run the same request 3–5 times. Consistent results = passing test. Variables to check:
- Outputs match expected structure
- All API/MCP calls succeed
- Error cases handled gracefully
- New users succeed without needing to re-prompt
**Performance comparison:**
Run a workflow without the skill vs with the skill. Compare:
- Number of turns needed
- Token usage
- Error rate
- User corrections required
---
### Stage 7: Distribute
**For GitHub open-source release:**
1. Create repo: `github.com/your-username/skill-name`
2. Root-level `README.md` (NOT inside skill folder) with:
- What the skill does
- Installation steps (Claude.ai + Claude Code)
- Screenshots or demo GIF
- License badge
3. Installation steps to include:
Claude.ai
- Download or clone this repo
- Settings → Capabilities → Skills → Upload folder
- Test with: "[trigger phrase]"
Claude Code
- Clone into your skills directory
- Skills load automatically on next session
4. For OpenClaw: place in `~/clawd/skills/your-skill-name/`
5. For ClawHub publish: `clawhub publish ./your-skill-name`
**For the Skill Engineering Standard repo:** submit a PR to [github.com/lennoxsaint/skill-engineering-standard](https://github.com/lennoxsaint/skill-engineering-standard) following the contribution guide.
---
## Quick Reference Checklist
**Before you ship:**
- [ ] Folder named in kebab-case
- [ ] `SKILL.md` present and exactly named
- [ ] Frontmatter has `name` and descriptive `description` with trigger phrases
- [ ] No XML tags in frontmatter, no reserved names (`claude`, `anthropic`)
- [ ] Description < 1024 chars
- [ ] Heavy docs moved to `references/`
- [ ] Scripts in `scripts/` with usage examples in SKILL.md
- [ ] At least 2 concrete examples in SKILL.md
- [ ] Troubleshooting section present
- [ ] Trigger tests pass (~90% accuracy)
- [ ] Functional tests pass (3–5 consistent runs)
- [ ] Root-level README.md written (if distributing)
- [ ] No README.md inside the skill folder
---
## The Three Levels of AI Engineering
This skill is part of the **Skill Engineering Standard** — the open-source framework for the third evolution of AI engineering.
| Era | Focus | Output unit |
|-----|-------|-------------|
| **Prompt Engineering** (2024) | Crafting the right words | A prompt |
| **Context Engineering** (2025) | Managing what the model knows | A context window |
| **Skill Engineering** (2026) | Packaging reusable expertise | A skill |
**Join the movement:** [github.com/lennoxsaint/skill-engineering-standard](https://github.com/lennoxsaint/skill-engineering-standard)
