skill-engineering-standard

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:

1. What does this skill do? (one sentence, concrete)
2. When should it load? (list exact phrases a user would say)
3. What does success look like? (describe the output for 2–3 real examples)
4. 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 name
• description — 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 URL
• compatibility — 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

1. Download or clone this repo
2. Settings → Capabilities → Skills → Upload folder
3. Test with: "[trigger phrase]"

Claude Code

1. Clone into your skills directory
2. 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)