How to Write Custom SKILL.md Files for OpenClaw

Your agent is creative. Too creative, sometimes. Skills give it the constraints it needs for repeatable, reliable work.

The secret? Write them like checklists, not blog posts.

Skill Structure

A skill is just a folder with a SKILL.md file. Drop it in ~/.openclaw/skills/ and OpenClaw picks it up automatically.

~/.openclaw/skills/
├── my-custom-skill/
│   └── SKILL.md
├── another-skill/
│   ├── SKILL.md
│   └── helper-script.sh

Include helper scripts or templates alongside — your agent can access them when the skill is active.

Frontmatter

Every SKILL.md starts with YAML frontmatter:

---
name: deploy-to-vercel
description: Deploy projects to Vercel
version: 1.0.0
triggers:
  - deploy
  - vercel
  - push to production
---

Key fields:

• name — Unique identifier
• description — What it does (shown in listings)
• triggers — Keywords that auto-load the skill when mentioned

Say "deploy this to Vercel" and OpenClaw matches the triggers and loads the instructions automatically.

Writing Effective Instructions

This is where most people go wrong — prose when they should write procedures.

❌ Bad:

When deploying to Vercel, you should think about 
the environment variables and make sure they're set 
correctly.

✅ Good:

## Pre-Deploy Checklist
1. Verify `.env.production` exists
2. Run `npm run build` locally — must pass
3. Check `vercel.json` has correct settings

## Deploy Steps
1. Run `vercel --prod`
2. Wait for deployment URL
3. Test /api/health endpoint
4. Notify #deployments channel

## If Build Fails
1. Check build logs: `vercel logs <url>`
2. Common issues:
   - Missing env vars → Check Vercel dashboard
   - TypeScript errors → Run `npm run typecheck`

Numbered steps. Specific commands. Edge cases covered. Your agent follows the procedure instead of improvising.

Real Example

A skill I use for generating images:

---
name: image-gen
description: Generate images with Gemini API
triggers:
  - generate image
  - create image
---

# Image Generation Skill

## Setup
- Script: `scripts/gemini-image.sh`
- API key: `GEMINI_API_KEY` env var

## Usage
```bash
./scripts/gemini-image.sh "your prompt here"
```

## Errors
- Rate limited → Wait 60 seconds, retry
- Invalid key → Check env var is set

Script location, usage syntax, error handling. No ambiguity.

The Golden Rule

Ask yourself: "Could a diligent junior developer follow this exactly?"

If yes, your agent nails it every time. If no, it improvises — and for repeatable workflows, that's the last thing you want.

Skills should be strict so your agent can be reliable.