Creating Custom Skills in Claude Code

Building Your Own Slash Commands in Claude Code

If you use Claude Code regularly, you've probably found yourself typing the same instructions over and over — things like "analyze this repo and give me a summary" or "run the tests and organize the results." Custom Skills let you turn those repetitive tasks into a single /my-skill command.

What Is a Skill?

A Skill is a custom slash command for Claude Code. Create a single SKILL.md file and you can invoke it with /skill-name. Instead of writing long prompts every time, you can templatize your most-used workflows.

Where Do You Put Them?

TEXT

# Available across all projects (personal)
~/.claude/skills/<skill-name>/SKILL.md

# Available only in a specific project
.claude/skills/<skill-name>/SKILL.md

Personal skills work in every repo on your machine. Project skills only activate within that repo, and committing them shares them with your team. If names collide, the personal skill wins over the project one.

SKILL.md Structure

YAML

---
name: my-skill
description: Explains when this skill should be used
argument-hint: [argument description]
disable-model-invocation: true
allowed-tools: Read, Grep, Glob
---
# Skill Instructions

Perform the task based on $ARGUMENTS.

Key Options

Option	Description
`name`	The name used to invoke it as `/name`. Defaults to the folder name
`description`	Describes the skill — used by Claude to decide whether to auto-invoke it
`argument-hint`	Argument hint shown in autocomplete
`disable-model-invocation`	If `true`, the skill can only be run manually
`allowed-tools`	Tools Claude can use without a permission prompt during the turn that invokes the skill. Unlisted tools stay available

Passing Arguments

YAML

---
name: analyze
---
Please analyze the $ARGUMENTS file.
# /analyze src/main.ts → "Please analyze the src/main.ts file."

# (if this were a convert skill)
Please convert $0 to $1 format.
# /convert data.json csv → "Please convert data.json to csv format."

$ARGUMENTS: the full argument string
$0, $1, $2: positional arguments (shorthand for $ARGUMENTS[0] and so on, counting from 0)
If the content has no $ARGUMENTS, your input is appended to the end of the skill as ARGUMENTS: ....

Real-World Example

Here's a skill I built that collects information from a Flutter open-source project and automatically generates a draft blog post.

YAML

---
name: add-flutter-to-blogman
description: Collects Flutter repo info and generates a draft project introduction post
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Write
---
# Convert a Flutter Project into a Blog Post

Read README.md, pubspec.yaml, and CHANGELOG.md,
then save a project introduction draft as blogman-draft.md.

## Information to Collect

- README.md: description, features, screenshots
- pubspec.yaml: package name, dependencies, version
- CHANGELOG.md: latest changes

## Output

Save to blogman-draft.md

Placed in the personal location (~/.claude/skills/), running /add-flutter-to-blogman in any Flutter repo produces a blog post draft.

Tips

Pre-approve common tools: allowed-tools: Read, Grep, Glob lets those tools run without a permission prompt during that turn. It doesn't block other tools, so use permission settings if you need to prevent edits.
Prevent accidental execution: For risky operations like deployments or deletions, use disable-model-invocation: true so the skill can only be triggered manually.
Split out reference docs: If your SKILL.md gets long, you can place separate .md files in the same folder and reference them from the skill.