Claude Skills: Concepts, Setup, and Practical Usage Guide

If you use Claude every day, you know the scenario: pasting the same instructions, the same checklists, the same multi-step procedures into chat over and over again. After a while, this repetition costs you both time and consistency. To solve this problem, Anthropic developed Claude Skills: a shareable, version-controllable architecture that lets you give Claude new capabilities through a single Markdown file.

In this article, we explain what Skills are, how they work, how they differ from MCP and Hooks, and walk you step-by-step through creating your first skill.

What Are Claude Skills?#

Claude Skills is an extension system designed to give Claude long-lived instructions and procedures. Each skill is defined by a SKILL.md file inside a folder. This file consists of two parts: YAML frontmatter (the skill's identity and behavior) and Markdown content (the instructions Claude follows).

An analogy might help: think of it as a procedure manual you give to an assistant on the job. "When writing a blog post, follow these steps, apply these rules, and report back to me." A skill does the same job for Claude — and persistently.

When Is a Skill Useful?#

If you're experiencing any of the following, it's time to write a skill:

• You keep pasting the same long instructions over and over
• A procedure in your CLAUDE.md has grown into a "workflow" rather than "facts"
• You want everyone on your team to work with the same rules
• You want to make a task triggerable as a /command

The most powerful aspect of skills is this: their content is only loaded when invoked. So long reference material doesn't take up space in the context window — it activates when you need it.

Skills, MCP, and Hooks: Which Does What?#

The Claude ecosystem has three different extension mechanisms, and they're often confused. Let's clarify the differences:

In simple terms:

• Skill → "Teach Claude what to do"
• MCP → "Give Claude what it can access"
• Hook → "When Claude does something, automatically run something else"

MCP is used to open AI to the outside world. Skills, on the other hand, shape Claude's internal behavior. These three features aren't actually alternatives to each other but complementary tools.

How Does a Skill Work?#

A skill's workflow is as follows:

There are two invocation methods:

1. Manual invocation: You trigger it directly by typing /skill-name
2. Automatic triggering: Claude reads the description field and loads the skill if it decides it's relevant

Skill content is loaded only once in a session and stays in context throughout. That's why writing instructions as "always-applicable rules" rather than "one-time steps" is the best practice.

Where Do Skills Live?#

Where you put a skill determines who can access it:

If multiple skills with the same name exist, priority works in this order: Enterprise > Personal > Project. Plugin skills use a plugin-name:skill-name namespace, so they don't conflict.

SKILL.md Structure#

A skill folder is organized like this:

my-skill/
├── SKILL.md           # Required — main instructions
├── template.md        # Optional — template file
├── examples/          # Optional — example outputs
│   └── sample.md
└── scripts/           # Optional — executable scripts
    └── helper.sh

SKILL.md is required and has the following structure:

---
name: my-skill
description: What this skill does and when to use it
---
 
Your skill instructions go here.
 
## Steps
 
1. First step
2. Second step
3. Third step

Frontmatter Fields#

YAML frontmatter fields manage the skill's behavior. Here are the most commonly used ones:

The description field is critically important because Claude reads it to decide when to use the skill. The first 250 characters are truncated in autocomplete, so put the most important keywords up front.

Create Your First Skill Step by Step#

Let's do a practical example: a skill that standardizes git commit messages. We use this skill at Çelenk Yazılım — it generates commit messages following the Conventional Commits format.

Step 1: Create the Folder#

We're creating a project-level skill:

mkdir -p .claude/skills/commit-message

Step 2: Write the SKILL.md File#

---
name: commit-message
description: Generates git commit messages following Conventional Commits standard. Selects type (feat, fix, refactor, etc.) based on changes and writes a descriptive title. Use when committing to git.
disable-model-invocation: false
allowed-tools: Bash(git diff *) Bash(git status *)
---
 
Generate a commit message in Conventional Commits format:
 
## Steps
 
1. Inspect the output of `git status` and `git diff --staged`
2. Determine the type of change:
   - **feat:** New feature
   - **fix:** Bug fix
   - **refactor:** Code restructuring without behavior change
   - **docs:** Documentation change
   - **style:** Formatting, punctuation
   - **test:** Adding/updating tests
   - **chore:** Build, configuration changes
3. Write a short, clear title (max 72 characters)
4. Add an explanatory body if necessary
5. Generate the commit message and show it to the user for approval
 
## Rules
 
- Write "why"-focused, not "what"-focused
- Use imperative mood: "Add" not "Added"
- If there's a breaking change, mark it with `BREAKING CHANGE:` note

Step 3: Test the Skill#

You can test it in two ways:

By calling it directly:

/commit-message

By trying to trigger it automatically:

I'm going to commit, can you prepare the message?

In both cases, Claude will read the git diff output, analyze the changes, and suggest an appropriate commit message.

Practical Skill Examples#

Here are a few skill ideas we use in real projects that you can also adapt:

1. Code Review Skill#

Reviews pull requests, checks code style, bugs, and security issues. Analyzes git diff output and produces a structured report.

2. Blog Post Skill#

The blog-yaz skill we used to create this post generates SEO-friendly MDX blog posts. It includes keyword research, internal linking, and frontmatter standardization. The entire process is triggered with a single /blog-yaz command.

3. PR Creation Skill#

Analyzes changes from the current branch against main, generates a title and description, and runs gh pr create.

4. Test Generation Skill#

Reads a function, analyzes edge cases, and generates a test file in the appropriate test framework (Jest, Pytest, etc.).

5. Documentation Skill#

Reads a code file, extracts public APIs, and generates documentation in JSDoc/Docstring/Markdown format.

Advanced Features#

Skills offer powerful features beyond basic usage.

Passing Arguments#

You can pass arguments to skills and use them inside:

---
name: fix-issue
description: Fix a GitHub issue
---
 
Fix GitHub issue #$ARGUMENTS:
 
1. Read the issue description
2. Understand the requirements
3. Implement the solution
4. Write tests
5. Create a commit

A call to /fix-issue 123 replaces $ARGUMENTS with 123.

For indexed access, use shortcuts like $0, $1, $2.

Dynamic Context Injection#

The !`command` syntax runs a shell command before the skill content is sent to Claude. The output is pasted in place:

---
name: pr-summary
description: Summarize a pull request
allowed-tools: Bash(gh *)
---
 
## PR context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
 
## Task
Summarize this PR and identify risk areas.

This way, when the skill is invoked, Claude works with live data instead of static instructions.

Running in a Subagent#

When you add context: fork, the skill runs in an isolated subagent. It gets a separate context from your main conversation:

---
name: deep-research
description: Research a topic in depth
context: fork
agent: Explore
---
 
Research $ARGUMENTS thoroughly:
 
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with file references

This approach lets you delegate heavy research tasks without polluting your main context.

Sharing and Versioning Skills#

One of the most powerful aspects of Skills is their shareability. There are three main sharing models:

1. Project Skills: Commit the .claude/skills/ folder to git. Anyone who clones the repo automatically gets access to the same skills.
2. Plugins: Distribute your skills to others by creating a skills/ folder in a plugin.
3. Managed Settings: Deploy organization-wide via managed settings.

Best Practices and Pitfalls#

A few things to watch when writing skills:

Do's#

• Keep SKILL.md under 500 lines. Move longer reference material to separate files and reference them from SKILL.md.
• Write the description field with rich keywords. Automatic triggering depends on this field.
• Put the most important words first. The first 250 characters are critical.
• Add supporting files (templates, examples) to your folder. Reference them from inside the skill.
• Test it. Validate the skill by calling it both manually and automatically.

Don'ts#

• Don't add dangerous operations without disable-model-invocation: true. Operations like deploy or push shouldn't be auto-triggered by Claude.
• Don't grant overly broad allowed-tools permission. Only allow commands the skill needs.
• Write persistent rules instead of temporary task instructions. Skill content is valid throughout the session.
• Don't forget the word "use" in description. "Reviews code" is weaker than "Use for code review" for triggering.

Conclusion#

Claude Skills is a powerful feature that makes AI-assisted workflows sustainable and shareable. With a single SKILL.md file, you can ensure everyone on your team works with the same standards, reduce repetitive tasks to a single command, and customize Claude for your own workflows.

The real power of skills emerges when combined with MCP-developed tools and Hooks. Skills tell what to do, MCP provides what to access, and Hooks manage when to trigger. This triple combination is the foundation of modern AI-based development processes.

Resources#

• Anthropic Claude Code — Skills Official Documentation
• Agent Skills Open Standard
• Anthropic Claude Code Overview
• Model Context Protocol Documentation