Claude Skill Builder: SKILL.md Validator + Template Generator
Fill in 5 fields. Get a valid SKILL.md with canonical Anthropic frontmatter, description-as-trigger checks, and a vague-language linter. Drop it at ~/.claude/skills/ and Claude picks it up live.
Quick answer
A Claude Skill is a folder containing a SKILL.md file with YAML frontmatter (description, optional name, allowed-tools, model) and markdown instructions. Claude auto-invokes it when a request matches the description, or you trigger it manually with /skill-name. Install at ~/.claude/skills/your-skill/SKILL.md for personal use or .claude/skills/your-skill/SKILL.md for project scope.
Lowercase letters, numbers, hyphens. Becomes the folder name at ~/.claude/skills/your-skill/
Adds when-to-use frontmatter. List concrete user phrases or topics — avoid "when needed" or "sometimes".
Sets allowed-tools frontmatter. Tools listed here run without per-use approval when the skill is active.
Want to build a BrandBrain-style social cockpit skill?
Make your own BB-style skill that generates posts, reviews queue, and schedules across LinkedIn, X, Threads, Instagram, and Facebook. Get the actual product at brandbrain.app.
Recipe
How to build your first Claude Skill
Five steps from idea to working skill, end to end.
Spot the repeat
Find a workflow you paste into chat more than three times. A code review checklist, a deploy procedure, a content brief template. That repeat is your skill candidate.
Write the description-as-trigger
Open the builder above and write a description that includes WHAT the skill does AND WHEN to invoke it. "Reviews a PR for security issues. Use when the user asks for a security review or pastes a diff." Claude matches your future requests against this exact string.
Pick allowed-tools sparingly
Only pre-approve tools the skill actually needs. Read + Grep for code review skills. Bash for deploy skills. WebFetch for research skills. Every tool you add gives the skill write power without per-use approval.
Write standing instructions in the body
Plain markdown. Numbered steps for procedures, bullet lists for checklists. Use $ARGUMENTS for anything the user passes after the skill name (for example /review 142 lets $ARGUMENTS hold "142"). Keep it under 500 lines per Anthropic's own guidance.
Drop, test, iterate
Generate, download, save to ~/.claude/skills/your-slug/SKILL.md. Claude Code watches the folder live, so the skill is available within the same session. Type /your-slug to test the manual path, or ask a matching question and watch Claude auto-invoke.
Canonical reference
The SKILL.md frontmatter schema
Verified against code.claude.com/docs/en/skills on 2026-05-15. Only description is recommended. Everything else is optional.
| Field | Required | What it controls |
|---|---|---|
| name | Optional | Display name. Lowercase letters/numbers/hyphens, max 64 chars. Defaults to directory name. |
| description | Recommended | Tells Claude when to auto-invoke. Combined with when-to-use, capped at 1,536 chars. |
| when-to-use | Optional | Extra trigger context. Trigger phrases, example requests, topic keywords. |
| argument-hint | Optional | Autocomplete hint like [issue-number]. |
| arguments | Optional | Named positional args for $name substitution. |
| allowed-tools | Optional | Space-separated. Pre-approves tool use while the skill is active. |
| model | Optional | Override model. inherit, sonnet, opus, haiku, etc. |
| effort | Optional | Effort level: low, medium, high, xhigh, max. |
| disable-model-invocation | Optional | True = manual only. No auto-invoke. Use for /deploy, /commit. |
| user-invocable | Optional | False = hidden from slash menu. Use for background knowledge skills. |
| context | Optional | fork = run in a forked subagent context. |
| agent | Optional | Which subagent type to use with context: fork. |
| paths | Optional | Glob patterns. Skill auto-loads only when working with matching files. |
| hooks | Optional | Hooks scoped to this skill's lifecycle. |
| shell | Optional | bash (default) or powershell for backtick-bang-command injection. |
Picking the right tool
Claude Skill vs MCP server
Different layers of the stack. Most real setups use both.
Use a Skill when...
- + You have a procedure or checklist to encode
- + You want Claude to follow standing instructions
- + The workflow is markdown, not a live data source
- + You want to ship to other Claude users by committing a folder
Use an MCP server when...
- + You need to expose a live tool surface
- + You have structured request and response schemas
- + The integration needs auth, retries, or rate limiting
- + Other clients (not just Claude) need the same interface
Validator
What the validator catches
Slug shape
Lowercase letters, numbers, hyphens only. Max 64 chars per Anthropic spec. No leading or trailing hyphens.
Description-as-trigger
Flags descriptions that say WHAT the skill does but not WHEN to use it. Claude needs the when language to auto-match requests.
Vague trigger phrases
Detects "when needed", "sometimes", "as appropriate" and other low-signal language Claude can't match against real user requests.
Length caps
Description + when-to-use combined is truncated at 1,536 chars in the skill listing. Body soft cap at 10K chars per Anthropic's under-500-lines guidance.
Tool whitelist
Warns on unknown tool names. Lists every standard Claude Code tool (Read, Edit, Write, Bash, Glob, Grep, WebFetch, WebSearch, Task).
Valid YAML frontmatter
Escapes single quotes inside string values, only emits non-default fields, generates copy-paste-ready output.
Want a BrandBrain-style social cockpit skill?
Generate posts in chat, review every draft in one queue, schedule across LinkedIn, X, Threads, Instagram, and Facebook. Get the actual product at brandbrain.app.
FAQ
Claude Skills questions, answered
What is a Claude Skill?
A Claude Skill is a folder containing a SKILL.md file with YAML frontmatter and markdown instructions that extends what Claude can do. Skills follow the open Agent Skills standard. When Claude sees a request that matches a skill's description, it loads the SKILL.md content into the conversation and follows the instructions. You can also invoke a skill manually by typing slash and the skill name (for example /summarize-changes).
What goes in SKILL.md?
SKILL.md has two parts: YAML frontmatter between triple-dash markers, then markdown content. The only recommended frontmatter field is description, which tells Claude when to invoke the skill. Optional fields include name, when-to-use, allowed-tools, model, disable-model-invocation, user-invocable, paths, and arguments. The body is plain markdown with standing instructions Claude follows when the skill runs. Anthropic recommends keeping SKILL.md under 500 lines and moving long reference material into supporting files.
Where do Claude Skills live on disk?
Personal skills live at ~/.claude/skills/skill-name/SKILL.md and are available across every project. Project skills live at .claude/skills/skill-name/SKILL.md and apply only to that repo. Plugin skills live inside a plugin folder under skills/skill-name/SKILL.md and use a plugin-name:skill-name namespace. Enterprise admins can deploy skills via managed settings. When a skill name appears at multiple levels, enterprise overrides personal which overrides project.
How do I install a Claude Skill?
Three install paths. First, manual install: create the folder ~/.claude/skills/your-skill-name/ and drop SKILL.md inside. Claude Code watches these directories live, so the skill is available within the current session. Second, plugin marketplace install: use the Claude Code plugin system to add skills from the anthropics/skills GitHub marketplace. Third, project install: commit .claude/skills/ to your repo so every contributor gets the skill when they clone.
Should I use a Claude Skill or an MCP server?
Pick a Claude Skill when you need to encode a workflow, checklist, or instruction set Claude follows step by step. Pick an MCP server when you need to expose a live tool surface (database, API, file system) with structured request and response schemas. Skills are markdown-only and load into the conversation context. MCP servers are running processes that expose tools, resources, and prompts. Many real setups use both: an MCP server provides the data plane and a skill provides the workflow that uses it.
What is the canonical SKILL.md frontmatter schema?
Per Anthropic docs verified May 2026, the SKILL.md frontmatter supports: name (lowercase letters, numbers, hyphens, max 64 chars, defaults to directory name), description (recommended, used by Claude to decide when to invoke), when-to-use (additional trigger context), argument-hint and arguments (positional argument support with substitutions like $ARGUMENTS, $0, $1), allowed-tools (space-separated list pre-approved when the skill is active), model (override model for the skill), effort (low, medium, high, xhigh, max), disable-model-invocation (manual-only), user-invocable (hide from slash menu), context (set to fork to run in subagent), agent (which subagent type), paths (glob patterns that limit activation), hooks, and shell.
Why is the description called the trigger?
Claude reads all skill descriptions into context at session start. When you make a request, Claude matches the request against descriptions to decide which skill to auto-invoke. A description that only says what the skill does (Generates a PDF summary) will trigger less reliably than one that also says when to use it (Generates a PDF summary. Use when the user uploads a PDF and asks for a summary or key takeaways). The combined description plus when-to-use text is capped at 1,536 characters in the skill listing, so put the key use case first.
Can a Skill run scripts or only follow instructions?
Both. A SKILL.md body can contain plain markdown instructions, dynamic context injection via backtick-bang-command syntax (the command runs and its output is inlined before Claude sees the prompt), references to bundled scripts using the CLAUDE_SKILL_DIR variable, and string substitutions like $ARGUMENTS or $0. Skills can include any language script in their folder. Claude executes the script via Bash if allowed-tools permits it.
Sources
- Anthropic Claude Code Skills docs: code.claude.com/docs/en/skills (verified 2026-05-15)
- Anthropic Skills announcement: claude.com/blog/skills
- Agent Skills open standard: agentskills.io
- Example skill repo: github.com/anthropics/skills
Related
Keep building
Guide
Claude Skills for AI video pipeline
Two production skills (script writer + asset producer) that run an end-to-end AI video workflow.
Tool
Social media post generator
Platform-perfect posts for LinkedIn, X, Threads, Instagram, Facebook.
Guide
Claude Code for marketers
The marketer-facing playbook for Claude Code, skills, and automation.