Skills — Author SKILL.md

What it does

A SKILL.md file defines a custom slash command (skill) that Claude Code runs. It's a structured document that bundles a description, optional configuration, and a list of allowed tools into a reusable automation. When you author a skill, it becomes available as /skill-name in your project — a faster, more reliable way to orchestrate multi-step tasks than ad-hoc instructions each time.

Skills live in .claude/skills/ — one file per skill. The frontmatter declares the skill's metadata (name, description, target directory scope), and the body is plain Markdown that becomes the skill's instructions. When invoked, Claude Code reads the SKILL.md, respects the allowed-tools constraint, and routes the work to a specialized subagent.

When to use it

Author a skill when you have a repeatable, multi-step workflow that your team runs regularly:

• A pre-push validation check that runs npm run check, npm audit, and a build — faster than repeating the steps each time
• A code review harness that sweeps multiple files for a specific kind of bug
• A daily content pipeline (fetch posts, validate, publish) that runs on schedule
• A deployment or release checklist that combines checks, rollback safety, and notifications

Skills are not for one-off tasks or one-liner commands. CLAUDE.md notes are better for ephemeral guidance ("when you see X, do Y"); skills are better for named, repeatable workflows your team invokes by name.

Try it yourself

Create a new .claude/skills/ directory if it doesn't exist, then write a SKILL.md with frontmatter declaring name, description, and allowed-tools. Frontmatter is YAML between triple-dashes — declare tools your skill needs (e.g., ["Read", "Bash", "Edit"]). The body is your skill's instructions; it will be shown to the user before execution, so write it clearly. Save it, then invoke it as /your-skill-name in the terminal to see your skill in the available list.

Gotchas

Frontmatter is strict. Missing or malformed YAML (unclosed quotes, misaligned indent) will silently fail to load the skill. Validate with cat .claude/skills/your-skill.md | head -20 and check that name:, description:, and allowed-tools: are present and spelled exactly.

allowed-tools is a hard constraint. If your skill logic needs Bash, but you only declared ["Read", "Edit"], the subagent cannot call Bash — it will refuse and the skill fails. List every tool the skill's instructions might invoke. This is not a documentation step; it's a security sandbox.

Skills and CLAUDE.md are different scopes. CLAUDE.md is codebase-wide guidance that every agent respects (auth patterns, commit rules, anti-patterns). Skills are named workflows. If your instruction is a one-time guard rule ("never do X in this repo"), put it in CLAUDE.md. If it's a repeatable procedure ("run this multi-step check"), author a skill.

Scoped skills. A skill can target a subdirectory via the scope: frontmatter field (e.g., scope: apps/web). Scoped skills show up only when you're working in that directory. Omit scope: for project-wide skills.