Claude Code Skills: Build Reusable Workflows with Custom Commands

Skills are, to me, the fastest and most effective way to get an AI agent to perform a predictable number of steps. With the advantage that the process remains conversational: you can intervene, correct, and redirect while it happens.

Sounds complicated. It's not. A skill is a markdown file with instructions. You save it in a folder and invoke it with a slash command. That's it.

The article you're reading right now was generated with a skill. Literally. A /claude-code-article that runs SEO research, checks official documentation, reads style examples, generates the draft in two languages, uploads it to Notion, and publishes it to production. It's a multi-step flow, repeatable, with human intervention points. And it works.

If you've been using Claude Code for a while and still copy-paste the same prompts, or keep inflating your CLAUDE.md with instructions that only apply to specific tasks, skills are your next step.

Anatomy of a skill

Each skill lives in its own directory with a SKILL.md file as its entry point:

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Expected output example
└── scripts/
    └── validate.sh    # Script Claude can execute

The SKILL.md has two parts: a YAML frontmatter that configures behavior, and markdown content with the instructions Claude follows.

---
name: my-skill
description: What this skill does and when to use it
disable-model-invocation: true
---

Instructions that Claude will execute when the skill is invoked...

Where to store skills

Location determines scope:

When skills share the same name across different levels, the highest priority wins: enterprise > personal > project.

For most cases, personal skills (~/.claude/skills/) are the most practical. You can use them across any project without additional configuration.

Your first skill: step by step

Let's create a skill that reviews frontend components against specific criteria. This is a real use case: you have a quality standard and want Claude to apply it consistently.

1. Create the directory

mkdir -p ~/.claude/skills/review-component

2. Write the SKILL.md

---
name: review-component
description: Reviews a frontend component. Use when asked to review, audit, or improve a Vue or React component.
argument-hint: [path-to-component]
---

Review the component at $ARGUMENTS against these criteria:

1. **Structure**: Clear separation of logic, template, and styles?
2. **Props**: Properly typed? Default values where applicable?
3. **Reactivity**: Efficient use of computed/watchers?
4. **Accessibility**: ARIA roles, labels, keyboard navigation?
5. **Performance**: Unnecessary renders or heavy dependencies?

Present findings in a table with a severity column (high/medium/low) and propose a fix for each one.

3. Try it

Invoke it directly:

/review-component src/components/SearchBar.vue

Claude will read the component and apply exactly the 5 criteria you defined. Always the same ones, in the same order, with the same output format.

It can also activate automatically. If you ask "review this component", Claude will read the skill's description and decide to use it if it fits. If you'd rather it only activates when you explicitly invoke it, add disable-model-invocation: true to the frontmatter.

Frontmatter: all options

Who can invoke what

The combination of disable-model-invocation and user-invocable controls access:

Arguments: passing data to the skill

When you invoke /my-skill something, that "something" is available as $ARGUMENTS inside the SKILL.md. You can also access positional arguments:

---
name: migrate-component
description: Migrates a component from one framework to another
---

Migrate the component $0 from $1 to $2.
Preserve all existing behavior and tests.

Running /migrate-component SearchBar React Vue replaces $0 with SearchBar, $1 with React, and $2 with Vue.

If the skill doesn't include $ARGUMENTS in its content, Claude Code automatically appends it at the end as ARGUMENTS: <value>.

Advanced patterns

Inject dynamic context

The !`command` syntax runs shell commands before sending the content to Claude. The command output replaces the placeholder:

---
name: pr-summary
description: Summarizes the changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Modified files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

This is preprocessed. The commands run before Claude sees anything, and the content it receives already has the real data inserted.

Fork to subagent

Add context: fork to the frontmatter when you want the skill to run in an isolated context. The skill becomes the subagent's prompt, without access to your conversation history.

---
name: deep-research
description: Thoroughly investigates a topic in the codebase
context: fork
agent: Explore
---

Investigate $ARGUMENTS thoroughly:

1. Find relevant files with Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

When this skill runs:

1. A new, isolated context is created
2. The subagent receives the skill content as its prompt
3. The agent field determines the execution environment (model, tools, permissions)
4. Results are summarized and returned to your main conversation

This is especially useful for heavy research or processing tasks that would fill your main context window. The subagent works in its own space and returns only the summary.

Supporting files

For complex skills, don't cram everything into the SKILL.md. Use additional files:

content-generator/
├── SKILL.md           # Main flow: steps 1-9
├── templates/
│   └── tip-template.md
└── examples/
    ├── tip-en.md
    └── tip-es.md

Reference these files from your SKILL.md so Claude knows what they contain and when to load them. Keep the SKILL.md under 500 lines and move detailed reference material to separate files.

Skills vs hooks vs MCP vs subagents

Claude Code has several extension mechanisms. Each solves a different problem:

Skills can combine all the others: a skill with context: fork uses subagents, a skill with !`command` can invoke MCP tools, and a skill can have hooks tied to its lifecycle.

Tips from daily use

The description matters more than you think. Claude uses the frontmatter description to decide whether to automatically load a skill. If your skill isn't activating when you expect, check the description before anything else.

Use disable-model-invocation: true for anything with side effects. Deploys, commits, sending messages, publishing content. You don't want Claude deciding to do it on its own because "it seems like the right time."

Skill descriptions consume context. Claude loads the descriptions of all available skills at the start of each session. If you have many, they can exceed the character budget (2% of the context window, with a fallback of 16,000 characters). Use /context to check if any skill is being excluded.

Start simple, iterate. Your first skill can be 10 lines. You don't need complex frontmatter, supporting files, or forking to subagents. Start with the instructions you'd copy and paste manually, put them in a SKILL.md, and evolve from there.

Conclusion

Skills are the building block for repeatable AI workflows. They're not complicated. They're a markdown file with instructions, saved in a folder, invocable with a slash command. What makes them powerful is that they let you repeat a specific number of steps with reasonable predictability, with the ability to intervene when needed, being as simple or complex as you want.

If you find yourself doing the same thing over and over in Claude Code — reviewing components, generating content, preparing deploys, creating PRs with a specific format — that's a skill waiting to be written.

Official documentation: Extend Claude with skills