/skills-best-practices

name: skills-best-practices
description: Build high-quality Agent Skills for Claude following official Anthropic best practices. Covers SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, patterns, troubleshooting, and distribution across all surfaces (Claude.ai, Claude Code, API, Agent SDK). Use when creating a skill, reviewing skill quality, debugging why a skill won't trigger, structuring skill directories, or writing skill descriptions.
metadata:
  version: "0.6.3"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/skills-best-practices
    emoji: "📐"

Skills Best Practices

Comprehensive reference for building Agent Skills that follow Anthropic's official guidelines. Skills are folders containing instructions, scripts, and resources that teach Claude how to handle specific tasks. They follow the [Agent Skills open standard](https://agentskills.io).

Quick Start

A minimal skill is a directory with a `SKILL.md` file:

my-skill/
├── SKILL.md          # Required - instructions with YAML frontmatter
├── references/       # Optional - detailed docs loaded on demand
├── scripts/          # Optional - executable code
└── assets/           # Optional - templates, fonts, icons

Minimal `SKILL.md`:

---
name: my-skill-name
description: What it does. Use when [specific triggers].
---

# My Skill Name

[Instructions here]

Only `name` and `description` are required in frontmatter.

Core Design Principles

Progressive Disclosure (Most Important)

Skills load information in three levels to minimize token usage:

| Level | When Loaded | Token Cost | Content | |-------|------------|------------|---------| | **1: Metadata** | Always (startup) | ~100 tokens | `name` + `description` from frontmatter | | **2: Instructions** | When skill triggers | <5k tokens (recommended) | SKILL.md body | | **3: Resources** | As needed | Effectively unlimited | Bundled files, scripts |

Keep SKILL.md under **500 lines**. Move detailed docs to separate files and reference them:

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [reference.md](reference.md)

Claude reads referenced files only when the task requires them.

Composability

Skills work alongside other skills. Don't assume yours is the only one loaded.

Portability

Skills work across Claude.ai, Claude Code, API, and Agent SDK without modification (if dependencies are available).

Writing the Description (Critical)

The description is the **single most important field** - it determines when your skill activates. Claude uses it to decide relevance from potentially 100+ available skills.

Rules

• Write in **third person** ("Processes files..." not "I help you process files...")
• Include **WHAT** it does + **WHEN** to use it
• Max 1024 characters, no XML angle brackets
• Be slightly "pushy" - Claude tends to **undertrigger** rather than overtrigger
• Include specific trigger phrases users would naturally say

Good vs Bad

# GOOD - specific, actionable, includes triggers
description: Extract text and tables from PDF files, fill forms, merge
  documents. Use when working with PDF files or when the user mentions
  PDFs, forms, or document extraction.

# BAD - too vague
description: Helps with documents.

# BAD - missing triggers
description: Creates sophisticated multi-page documentation systems.

More examples in [references/description-guide.md](references/description-guide.md).

Frontmatter Reference

Required Fields

| Field | Rules | |-------|-------| | `name` | Kebab-case, max 64 chars, lowercase + numbers + hyphens only. No "claude" or "anthropic" | | `description` | Non-empty, max 1024 chars, no XML tags. WHAT + WHEN |

The agentskills.io standard and the Claude API require both fields. Claude Code is more lenient: `name` falls back to the directory name, and `description` falls back to the first markdown paragraph. Write both anyway for portability.

The spec also defines optional `license`, `compatibility`, and `metadata` fields. `compatibility` is capped at 500 characters and states environment requirements (intended product, system packages, network access).

Optional Fields (Claude Code)

| Field | Purpose | |-------|---------| | `argument-hint` | Autocomplete hint, e.g. `[issue-number]` | | `when_to_use` | Extra trigger context, appended to `description` in the skill listing | | `arguments` | Named positional arguments for `$name` substitution (space-separated string or list) | | `disable-model-invocation` | `true` = only user can invoke (for deploy, commit) | | `user-invocable` | `false` = hidden from `/` menu (background knowledge) | | `allowed-tools` | Pre-approves tools (no permission prompt); space-separated, e.g. `Read Grep Glob`. In the spec allowlist but tagged **(Experimental)** | | `disallowed-tools` | Removes tools from Claude's pool while the skill is active; clears on your next message | | `model` | Override model for this skill; accepts `inherit`. Lasts the current turn only | | `effort` | Override effort level: `low`, `medium`, `high`, `xhigh`, `max` | | `context` | `fork` = run in isolated subagent | | `agent` | Subagent type when `context: fork` (e.g. `Explore`, `Plan`) | | `hooks` | Hooks scoped to this skill's lifecycle | | `paths` | Glob patterns limiting when skill activates |

> **Publishing caveat:** every field above except `allowed-tools` is Claude Code-specific. They work in Claude Code at runtime, but the **official `agentskills validate` spec validator rejects them** - it allows only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`, with no relax flag. If your repo or CI runs that validator (most ClawHub-publishing repos do), a skill using these fields fails validation unless you strip them from the copy you validate/publish. The ClawHub registry itself tends to tolerate extra top-level fields