Originally published at claudeguide.io/how-to-build-custom-claude-code-skill
How to Build a Custom Claude Code Skill (Step-by-Step)
A Claude Code skill is a markdown file that gives Claude a specialized, repeatable workflow — a named procedure Claude can follow on demand or when triggered by a specific condition. Skills let you encode your team's runbooks, deployment checklists, and code review procedures into Claude once and reuse them indefinitely, without re-explaining them every session. For the broader Claude Code feature set, see the Claude Code Complete Guide in 2026.
This guide covers the full authoring cycle: file structure, triggers, bash preambles, interactive prompts, and a complete worked example.
What a Skill Is (and Isn't)
A skill is a .md file that lives in ~/.claude/skills/ (user-level, available in every project) or .claude/skills/ (project-level, checked into your repo). When Claude encounters a matching trigger — a slash command, a keyword in your message, or a condition you define — it loads the skill's instructions and follows them.
Skills are different from:
- CLAUDE.md — project context loaded automatically at session start; not invoked on demand
- MCP tools — external process integrations; skills are pure instructions with no external runtime
- Custom slash commands — slash commands can invoke skills, but a skill contains the actual procedure
The SKILL.md File Structure
Every skill file follows the same shape:
---
name: skill-name
description: "One-line summary of what this skill does"
trigger: /slash-command-name
---
# Skill Name
Brief description of when and why to use this skill.
## Preamble
bash
Optional: shell commands to run before Claude starts
## Instructions
1. Step one
2. Step two
3. Step three
## AskUserQuestion
[Optional: questions to ask the user during the workflow]
yaml
Frontmatter Fields
| Field | Required | Purpose |
|---|---|---|
name |
Yes | Identifier used internally |
description |
Yes | Shown in /skills list |
trigger |
Yes | What invokes the skill |
The trigger field accepts:
- A slash command:
/deploy-check - A keyword phrase:
"when I say 'run checks'" - A condition:
"after completing a code change"(auto-invoke)
Triggers: When Claude Auto-Invokes a Skill
Skills can be invoked two ways:
Explicit (slash command): The user types /skill-name. Claude loads the skill and follows its instructions immediately.
Automatic (keyword or condition trigger): Claude detects the trigger condition during a normal conversation. For example:
trigger: "whenever the user asks to deploy or push to production"
With this trigger, Claude auto-invokes the skill if you say "let's push this" or "deploy to prod" — without needing to type a slash command.
Auto-invocation triggers are powerful but should be specific. Overly broad triggers (like "whenever Claude completes a task") will fire too often and slow down normal work.
Writing a Bash Preamble
The preamble is a bash block that Claude runs before executing the rest of the skill instructions. It serves two purposes:
- Gather context — collect current state (git status, test results, env variables) so Claude has accurate data before making decisions
- Fail fast — exit early with a clear error if prerequisites aren't met
Example preamble that checks prerequisites:
bash
# Check we're in a git repo
git rev-parse --git-dir
40 slash command templates. Token-optimized variants. JSONL file for direct import. Tested in production sessions.
[→ Get Claude Code Power Prompts 300 — $29](https://shoutfirst.gumroad.com/l/agfda?utm_source=claudeguide&utm_medium=article&utm_campaign=how-to-build-custom-claude-code-skill)
*30-day money-back guarantee. Instant download.*
Top comments (0)