SKILL.md Complete Guide

SKILL.md is an instruction file that teaches Claude how to perform specific tasks. When Claude receives a relevant request, it reads the matching SKILL.md first and follows the instructions inside. Skills layer domain expertise and optimized workflows on top of Claude's default capabilities.

1. File structure

Skills are organized as folders, not single files.

skill-name/
├── SKILL.md          ← required: main instruction file
├── scripts/          ← optional: scripts for repetitive tasks
├── references/       ← optional: reference docs (loaded only when needed)
└── assets/           ← optional: templates, fonts, icons, etc.

Skill folders usually live under .claude/skills/. Plugin skills installed by the user may also live under remote plugin paths.

2. SKILL.md basic format

Every SKILL.md starts with YAML frontmatter, followed by markdown instruction body.

---
name: skill-name
description: What this skill does and when to use it.
             Claude uses only this description when choosing a skill.
---

# Skill title

## How to work

Write the instructions Claude should follow here.

3. Frontmatter fields in detail

name (required)

Unique identifier for the skill. Convention is to match the folder name.

name: docx

description (required, most important)

Claude relies on this field alone when deciding which skill to use. The description must include two things:

• What the skill does — functional description
• When to use it — trigger conditions (include specific keywords)

description: |
  Skill for creating, editing, and analyzing Word documents (.docx).
  Use whenever the user mentions 'Word document', '.docx', 'report',
  'contract', or 'letterhead', or needs professional document formatting.

compatibility (optional)

Lists required external tools or dependencies. Omit for most skills.

compatibility:
  requires: [node, pandoc]

4. Three-level loading system

Not all skill content sits in Claude's context at once. For efficiency, loading is split into three levels and pulled in only when needed.

Thanks to this structure, you can keep thousands of lines in references/ without wasting context—they load only when needed.

5. Body writing patterns

Basic structure

---
name: my-skill
description: What this skill does and when to use it.
---

# My Skill

## Overview
Briefly explain why this skill exists and what problem it solves.

## Workflow
1. First step
2. Second step
3. Third step

## Output format
Specify what the deliverable should look like.

## Caveats
Common mistakes or patterns to avoid.

## Reference files
- Detailed API docs: `references/api.md` (for complex formatting)
- Template: `assets/template.docx`

Output format definition pattern

## Report structure
Always use this template exactly:

# [Title]
## Summary
## Key findings
## Recommendations

Example pattern

## Commit message format

**Example 1:**
Input: Add user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

**Example 2:**
Input: Fix error when clicking login button
Output: fix(ui): resolve login button click error

Reference file link pattern

## Advanced configuration

Basic usage is covered by instructions in this file.
For advanced table formatting, read `references/tables.md`.
For image insertion, see `references/images.md`.

6. Using the scripts/ folder

Repetitive or complex work (file conversion, packaging, validation, etc.) can live in scripts so Claude does not rewrite the same code every time.

scripts/
├── create_docx.js    ← create docx files
├── validate.py       ← validate output
└── pack.py           ← package files

How to reference scripts in SKILL.md:

## Document creation

Always use `scripts/create_docx.js` to create files.
Do not write the code inline—run the script:

```bash
node scripts/create_docx.js --output result.docx
```

7. Good vs bad examples

---
name: report
description: Creates reports.
---

Please make good reports.
Clean and professional.
ALWAYS use markdown.
NEVER omit tables.

---
name: report
description: |
  Skill for writing professional reports and analysis documents.
  Use when the user needs structured documents—mentions of
  'report', 'document', 'presentation outline', etc.
---

# Report Skill

## Purpose
Goal: structured documents that let readers grasp
the essentials quickly and support decision-making.

Problems with the bad example: description too short to trigger · no rationale (why) in instructions · overuse of ALWAYS/NEVER leads to rigid behavior

8. Using the references/ folder

Use references/ to keep SKILL.md under 500 lines while still holding deep content.

references/
├── advanced-tables.md    ← complex table authoring
├── xml-schema.md         ← XML structure reference
└── api-guide.md          ← external API usage guide

# API Guide

## Table of contents
- [Authentication](#authentication)
- [Document creation](#document-creation)
- [File upload](#file-upload)

## Authentication
...

9. Multi-domain skill setup

When one skill supports multiple environments or platforms, split by domain.

cloud-deploy/
├── SKILL.md         ← shared workflow + platform selection logic
└── references/
    ├── aws.md        ← AWS-specific settings
    ├── gcp.md        ← GCP-specific settings
    └── azure.md      ← Azure-specific settings

Branching by platform in SKILL.md:

## Platform selection

Read the matching references file based on what the user mentions:
- AWS   → `references/aws.md`
- GCP   → `references/gcp.md`
- Azure → `references/azure.md`

If unspecified, ask which platform to use first.

10. Skill authoring checklist

11. Practical example: translation skill

A complete skill file example from start to finish.

---
name: translate
description: |
  Text translation skill. Use when the user says 'translate',
  'into Korean', 'into English', 'into Japanese', etc.
  Covers plain translation, full documents, and specialized
  technical, legal, and medical terminology.
---

# Translate Skill

## Purpose
Deliver translations that preserve tone, nuance, and cultural context—
not word-for-word substitution.

## Translation principles
- Prefer natural phrasing over literal translation
- Use domain-standard terminology
- Follow target-language sentence patterns

## Output format
Output translation only.
If awkward or ambiguous, add briefly below:
the translation:
`[Note] The source phrase X could also mean Y.`

## Specialized translation
For technical, legal, or medical content,
consult `references/domain-terms.md`.

Install location

.claude/skills/translate/SKILL.md

After authoring, test via the skill-creator skill and package as a .skill file to share.

12. Skills in OpenClaw

SKILL.md is not Claude-only. OpenClaw is an open-source autonomous AI agent platform with a skill/plugin system similar to Claude's. Core skill design principles hold regardless of which LLM you use.

Claude vs OpenClaw skills comparison

Shared design principles

Well-designed skills follow the same principles across platforms.

• Single responsibility — one skill, one domain
• Clear triggers — when to use is explicit
• Progressive loading — only essentials stay in context
• Reusable scripts — repetitive work lives in code

13. Universe Skills

In OpenClaw's RL context, a Universe is the environment where an AI agent operates—browser, OS, a specific app, or an API. Universe Skills work across Universes rather than binding to one environment.

Types of Universe

Universe-agnostic skill design

A good Universe Skill behaves the same regardless of runtime. Put environment detection early in the skill.

## Environment detection

Before starting, detect the current environment:
- Browser available → see `references/browser-actions.md`
- API keys present → see `references/api-actions.md`
- Direct OS access → see `references/os-actions.md`

Keep the final output format identical in every environment.

Why Atlas is a Universe Skill

OpenClaw's Atlas plugin is a canonical Universe Skill. Whether the source is a local file, web URL, or API response, it searches and cites with the same Vectorless RAG approach—abstraction over environment is the point.

14. Skill Gap

Skill Gap is the distance between what AI can do today and expert-level accuracy. Closing that gap is central to AI training—and why an entire ecosystem of expert labeling and evaluation platforms exists (Scale, Surge, Outlier, Mercor, Appen, and others).

Structure of Skill Gap

How to close Skill Gap

Skill Gap closes by combining expert knowledge with documents. No single vendor does everything—platforms and tools split roles across labeling · evaluation · workflow management.

Expert labeling & evaluation ecosystem

“Expert labeling” means different things on each platform. Scale and Surge lean toward frontier model quality and RLHF; Outlier and Mercor toward domain expert pools; Appen, Toloka, and Sama toward multilingual volume and vision/speech data; Labelbox and Snorkel toward in-house enterprise pipelines. Teams often mix vendors—or lock rubrics in internal skills and distribute tasks externally.

Common work types

• Expert labeling — doctors, lawyers, engineers rate and correct AI output
• Document-grounded verification — compare against papers, case law, manuals
• Rubric-based evaluation — experts design field-specific criteria
• Multilingual, multi-domain scale — run across languages and fields in parallel

Skills and Skill Gap

A well-designed SKILL.md narrows Skill Gap. Encode expert judgment, checklists, and domain knowledge in the skill so the AI follows that expertise—a skill file codifies professional knowledge.

## Medical report review criteria  ← embed expert judgment in the skill

Always verify:
- Does the ICD-10 code match symptoms?
- Are doses within weight/age guidelines?
- Any contraindicated drug combinations?

If uncertain, note "physician review required" before proceeding.