Use Custom Skills on Claude Code

If you regularly use AI, especially for coding, you know there is an obvious upgrade to the usual to-and-fro in chats. What if you could save a particular workflow in AI and run it without writing a super-long prompt every time you need it? Claude Skills now lets you do exactly that. This nifty little feature turns the “smart intern” Claude into a “trained teammate” with exactly the skills you are looking for.

So, what exactly are Claude Skills? How do they work? How to build one for yourself? And how to configure it properly? Here, we will explore all these questions around Claude Skills. Treat this as the only guide you will need to understand Claude Skills completely, even if you are just starting out.

So without any delay, let’s dive right in.

What are Claude Skills?

If you think of Claude as a new hire, Claude Skills will be the manual or SOP you hand to him for reference. Instead of directing the fresher on a particular task every time, he can refer to the manual/ SOP and get it done himself. In AI terms, it means you can train Claude on a specific set of instructions that can be called upon whenever needed. This acts as a much more convenient alternative to writing a lengthy prompt every time and observing different outcomes.

Essentially, Claude Skills sits inside Claude Code and acts as per its name – “Skills.” Much like you train a person on a new skill, Claude Skills is basically adding such a skill to Claude Code. Every time that skill is called upon, it executes the workflow it is meant for flawlessly.

But Isn’t That Just a Saved Prompt?

Sort of. But smarter. You will have to type in a new prompt or call upon a saved prompt for every single session. A Skill, on the other hand, gets saved once and loaded automatically when relevant. Claude reads it on demand, rather than storing it in memory permanently. This means it doesn’t eat into your conversation context unless it’s actually needed. What’s more, a skill doesn’t just contain instructions but also structure. It can define the approach, context, and how that task should be executed.

Think of it like a cookbook sitting on the shelf. You don’t memorise every recipe. You pull it out when needed, follow it, and put it back. Claude Skills work the same way.

How Claude Skills Work

At its core, a Skill is a folder. Inside that folder lives one essential file: SKILL.md. Written in plain Markdown, this file does all the heavy lifting. It tells Claude what the Skill is for, when to use it, and exactly how to execute it.

Here is what a basic SKILL.md looks like:

---
name: write-report
description: Generates a weekly performance report.
Use when the user asks for a report summary.
---

When writing a report, always:
1. Start with a one-line summary
2. Use bullet points for key metrics
3. End with recommended next steps

That’s it. A name, a description, and the instructions. Claude reads this file when it detects your request matches what the Skill is built for, follows the instructions, and delivers a consistent output, every single time.

The real magic is in the description field. Claude uses it to decide which Skill to load. So if you have 10 different Skills set up, Claude scans through their descriptions and picks the one that fits your request. A well-written description is the crux of this whole system.

Also worth noting: Claude loads the Skill only when it’s needed. It doesn’t sit in the memory, hogging your context window during every conversation. Think of it as a pop-up reference guide that appears when relevant, disappears when not.

Also read: ChatGPT vs Claude: The 2026 Battle of the AI Model Families

Claude Skills Structure and Storage

Here is how the Claude Skills are structured and stored.

The Folder Structure

Every Skill lives inside a dedicated subfolder under .claude/skills/ in your project. Here is what that looks like:

your-project/
└── .claude/
└── skills/
├── write-report/
│ └── SKILL.md
└── analyse-data/
└── SKILL.md

Each Skill gets its own named subfolder, and inside it sits the SKILL.md file. That’s all you need. You can have as many Skills as your workflows demand. For instance, one can write reports, one can review code, and another can format data. There’s no hard limit.

One handy detail: Claude actively watches this folder. Edit a SKILL.md mid-session and the changes kick in immediately, no restart required.

Where Skills Actually Live

Depending on how you’re working with Claude, Skills can live in a couple of places:

Project-level Skills sit inside your project’s .claude/skills/ folder. These are specific to that project and are perfect for team workflows, codebases, or client-specific processes.

Global Skills live in a home-level directory, typically ~/.claude/skills/. These are available across all your projects. Useful for personal workflows you want everywhere. Just like a consistent writing style or a standard code review process.

Anthropic’s pre-built Skills (for tasks like creating Word documents, Excel sheets, or PDFs) come bundled separately and are managed for you. Your custom Skills sit alongside them in the same structure, and Claude treats both equally.

Discovery Rules: How Claude Picks the Right Skill

With multiple Skills available, Claude needs a way to choose. Here’s how that decision actually works:

Claude reads the description field of every available SKILL.md and matches it against your request. If your message contains keywords or intent that align with a Skill’s description, that Skill gets loaded.

This means two things. First, vague descriptions lead to missed triggers. If your description says “helps with documents,” Claude might not load it when you ask to “write a quarterly report.” Second, overly broad descriptions can cause the wrong Skill to fire. Specificity is everything.

A good rule of thumb: write your description as if you’re telling Claude exactly when to use it. “Use when the user asks to generate a performance summary or weekly report” will always outperform “for reports.”

Build Your First Claude Skill

Right, enough theory. Let’s actually build one.

Say you regularly ask Claude to review your Python code, checking for bugs, suggesting improvements, and flagging anything that looks off. Instead of typing out that brief every single time, you’re going to turn it into a Skill.

Step 1: Set Up the Folder

Navigate to your project directory and create the Skills folder if it doesn’t exist already:

mkdir -p .claude/skills/code-review

This creates a code-review subfolder inside .claude/skills/. That subfolder is your Skill’s home.

Step 2: Create the SKILL.md File

Inside the code-review folder, create a file called SKILL.md:

touch .claude/skills/code-review/SKILL.md
```
Now open it and add this:
```
---
name: code-review
description: Reviews Python code for bugs, readability issues,
and improvements. Use when the user asks to review, check,
or audit their code.
---

When reviewing code, always:
1. Start with a one-line summary of what the code does
2. List any bugs or logical errors found
3. Flag readability or style issues
4. Suggest specific improvements with examples
5. End with an overall quality rating out of 10

Save the file. That’s your first Skill, done.

Breaking Down the Frontmatter

Before we proceed, let me break down something important that we covered in the code above. The block at the top of your SKILL.md that is wrapped in dashes is called frontmatter. It’s not part of the instructions Claude follows. Instead, it’s metadata that helps Claude find and identify the Skill. Here’s what each field does:

• name: A short identifier for your Skill. Keep it lowercase with hyphens, no spaces. This is mostly for your own organisation. Claude does not use the name to trigger the Skill.
• description: This is the one that actually matters. Claude reads this field to decide whether your Skill is relevant to a given request. The more specific and trigger-focused it is, the better Claude gets at loading the right Skill at the right time.

There are two optional fields worth knowing as well:

• version: Lets you track iterations of a Skill. This is useful if you’re maintaining Skills across a team and want to know which version is deployed where.
• tags: Lets you label Skills by category (e.g., coding, writing, data). This is not used by Claude for discovery, but is handy for keeping things organised when your Skills library grows.

For most personal workflows, name and description are all you need. The optional fields become useful once you’re managing Skills at scale or sharing them across a team.

Step 3: Test It

Open Claude Code in the same project directory and type something like:

"Can you review this code for me?"

Then paste your code. Claude will detect that your request matches the code-review Skill’s description, load the SKILL.md, and follow the instructions inside. It gives you a structured review every time, not just whatever it feels like doing that day.

Step 4: Refine As You Go

Your first draft won’t be perfect, and that’s fine. Run the Skill a few times and notice where Claude’s output differs from what you actually want. Then go back into SKILL.md and tighten the instructions. Because Claude watches the folder actively, every edit takes effect immediately.

This is the core loop of building good Skills: write, test, observe, refine. Most people get to a solid Skill within two or three iterations.

A Few Things to Keep in Mind

Keep your instructions specific but not bloated. If your SKILL.md runs into several pages, Claude is spending a lot of context loading it. Aim to include only what Claude wouldn’t do correctly on its own. That is the real value of a Skill.

Also, make sure to use one Skill per task. Don’t try to bundle your code review, your report writing, and your email drafting into one SKILL.md. Build separate Skills and let Claude’s discovery rules handle the routing.

Triggering a Skill: Auto vs Manual

One of the smartest things about Claude Skills is that you do not always have to call them manually like a command-line wizard from 2004. Claude Skills can work in two modes: automatic invocation and manual invocation. The difference is simple, but important.

Auto-Invocation: Claude Decides

This is the default mode and the one you’ll use most. Claude scans the descriptions of all available Skills and matches them against your request. If your message aligns closely enough with a Skill’s description, Claude loads it automatically. In this scenario, no extra instruction from you is needed.

For example, if you have a code-review Skill with the description “Use when the user asks to review, check, or audit their code” and you type “can you check this function for me?”, Claude connects the dots and loads the Skill.

This is why the description field is so critical. Auto-invocation lives and dies by how well that one field is written. A vague description means Claude either misses the trigger or fires the wrong Skill entirely.

Manual Invocation: You Trigger the Skill

Manual invocation is exactly what it sounds like. You run the Skill directly using /skill-name. For example, /explain-code src/auth/login.ts calls that specific Skill on demand. This is useful when you want more control, especially for actions like deployment, commits, or other tasks that should not randomly spring to life just because Claude got enthusiastic.

Manual invocation is also useful when your request is worded in a way that wouldn’t naturally trigger the description match, or when you want to be absolutely certain a specific Skill is being used and not just Claude’s default behaviour.

Also Read: Top 5 GitHub Repositories to get Free Claude Code Skills (1000+ Skills)

Which One Should You Use?

For day-to-day use, auto-invocation is the goal. After all, it is the whole point of building Skills in the first place. If you’re constantly having to manually call your Skills, that’s a signal your descriptions need tightening. Think of manual invocation as a fallback, not a habit, at least for daily workflows. Here is a quick checklist for descriptions that auto-invoke reliably:

• Start with what the Skill does (“Generates…”, “Reviews…”, “Formats…”)
• Follow with the exact trigger scenario (“Use when the user asks to…”)
• Include likely keywords your requests will naturally contain

Of course, your Skill may involve making a critical decision, in which case you may not want to run it automatically. If you want a Skill to stay manual-only, Claude lets you enforce that with disable-model-invocation: true in the frontmatter. That tells Claude: do not auto-load this, only run it when I explicitly ask for it.

Advanced Features

Once you understand the basics, Claude Skills starts feeling less like a saved prompt and more like a small workflow engine. Here are some advanced features that propel its practicality even further.

Three-level progressive loading

This is the big one. Claude does not load an entire Skill at once. It loads the Skill in the following stages:

1. the YAML metadata at startup
2. the SKILL.md instructions when the Skill is triggered
3. any extra files, resources, or scripts, only when they are referenced.

This staged model keeps context usage efficient and is one of the biggest reasons Skills are more scalable than giant prompts.

Bundled resources and scripts

A Skill can include much more than just SKILL.md. You can bundle templates, reference docs, examples, API notes, and executable scripts inside the same folder. Claude can read those files when needed, or run scripts and use only their output. This makes the Skill both richer and more efficient.

Allowed-tools for tighter control

Claude Skills can restrict which tools are allowed during execution. This is useful when you want a Skill to stay focused and avoid wandering into tools it does not actually need. Think of it as giving Claude a toolbox, but only handing over the tools relevant to that job.

Invocation control with disable-model-invocation and user-invocable

These settings decide how a Skill can be used. disable-model-invocation stops Claude from auto-triggering the Skill, while user-invocable controls whether it appears as a slash command users can call directly. This gives you much finer control over when a Skill should act automatically and when it should wait for explicit permission.

Dynamic arguments like $ARGUMENTS

Claude Skills support string substitutions such as $ARGUMENTS, $ARGUMENTS[0], and $0. This allows one Skill to behave dynamically depending on the input passed to it, instead of forcing you to create separate Skills for every slight variation of the same task.

Subagent execution

Claude Code also supports running a Skill in a forked subagent context using fields like context: fork and agent. In practice, this means a Skill can hand work off to a more specialised execution flow instead of doing everything inside the main conversation path. That makes advanced Skills feel more modular and more powerful.

Other advanced frontmatter controls

The docs also list fields like model and hooks, which allow further control over how a Skill runs and behaves during execution. Beginners do not need these on day one, but they become useful once you start building more structured and controlled workflows.

Best Practices for Claude Skills

Now that we have learnt what Skills are and how to build one for ourselves, we need to focus on how best to use them. Claude Skills can save you time, or they can quietly misfire, burning your time and efforts. The difference usually comes down to a few decisions made up front. These are:

• Keep one Skill focused on one job: A Skill that does too many things becomes hard to trigger accurately and harder to debug when something goes wrong. If you find yourself writing “and also” more than once in your SKILL.md, split it into two Skills.
• Write a clear, trigger-focused description: Your description is what Claude uses to decide whether to load a Skill at all. Vague descriptions like “helps with writing tasks” will either miss triggers or fire at the wrong time. Write it as an instruction: “Use when the user asks to draft, edit, or review a blog post.”
• Use supporting files instead of stuffing everything into SKILL.md: If your instructions are getting long, that’s a signal to break them out. Move detailed references, templates, or style guides into separate files and let SKILL.md point to them. Claude only loads what it needs, so keep the main file clean.
• Keep risky actions manual-only: Anything that writes files, calls external services, or makes irreversible changes should have disable-model-invocation: true set. You want deliberate control over those Skills, so there are no accidental triggers mid-conversation.
• Test with realistic prompts before relying on it: Don’t just test with “trigger my Skill.” Type the kind of thing you’d actually say in a real session and see if Claude picks it up correctly. If it doesn’t, your description needs tightening.
• A Skill is a tool, not an operating system: It’s tempting to keep adding instructions until a Skill handles every edge case imaginable. Resist that. A focused Skill that does one thing reliably is worth ten bloated ones that sort of do everything.

Also read: OpenClaw vs Claude Code: Which AI Coding Agent Should You Use in 2026?

Pitfalls and Troubleshooting

Claude Skills usually do not fail for dramatic reasons. Most of the time, the issue is either a vague description, unclear instructions, or a setup that has become more clever than usable. The official docs highlight three core problems: the Skill does not trigger, it triggers too often, or Claude does not see all your Skills.

Skill not triggering

If Claude refuses to use your Skill, start with the description. Claude uses the description to decide when to apply a skill, so it should sound like the way you would naturally ask for that task. If you normally say, “review my code,” but your description says something abstract like “audit software artefacts,” do not be surprised if Claude misses the connection. Anthropic also suggests checking whether the Skill appears when you ask, “What skills are available?” and invoking it directly with /skill-name if needed.

Wrong Skill triggering

This is not called out as a separate official troubleshooting heading, but it is a very real, practical problem. If two Skills have overlapping descriptions, Claude may pick the closest match and still get it wrong. The fix is boring but effective: make each description distinct and specific enough that there is no confusion about when that Skill should be used. This follows directly from how the docs say descriptions guide invocation.

Skill triggers too often

If Claude keeps dragging a Skill into conversations where it barely belongs, the docs recommend tightening the description so it is more specific. And if you want full control, set disable-model-invocation: true so the Skill becomes manual-only. That is usually the right move for risky or high-impact workflows.

Skill fires, but ignores part of the instructions

This is more practical guidance than an official Anthropic troubleshooting label, but it is worth including. If your SKILL.md tries to do too much, Claude may not apply every part consistently. The docs themselves recommend keeping the main skill focused and moving extra material into supporting files for complex setups. In other words, do not turn one Skill into a full-blown constitution.

Changes are not showing up

If you updated SKILL.md and Claude still behaves like it is living in the past, first check that you edited the correct skill in the correct directory. The docs note that skills can exist at personal, project, enterprise, plugin, nested-directory, and –add-dir locations. Higher-priority locations win when names clash. That means editing one copy while Claude is loading another is absolutely possible.

Supporting file is not being read

Claude does not magically inspect every file in the skill folder just because it exists. The docs explicitly say you should reference those files from SKILL.md so Claude knows what they contain and when to load them. If tone-guide.md is being ignored, the problem may simply be that your instructions never pointed Claude to it.

Claude does not see all your Skills

This one is more technical. Claude loads Skill descriptions into context so it knows what is available, but if you have too many skills, they can exceed the available character budget. Anthropic says you can use /context to check for excluded skills, and the budget can also be overridden if needed.

Conclusion

Claude Skills won’t make you a better thinker. That part’s still on you. But they will stop you from wasting time explaining yourself to an AI every single session, like it has the memory of a goldfish.

The idea is simple: identify a workflow you repeat, write clear instructions once, and let Claude handle the execution consistently from that point on. One focused Skill, one clear description, a handful of supporting files if needed, and you can go from “smart chatbot” to “trained teammate.”

My suggestion is this – start small. Build a Skill for the one task you find yourself prompting Claude for most often. Test it with realistic inputs, tighten the description until auto-invocation works reliably, and resist the urge to turn it into a 400-line instruction manual covering every conceivable scenario.

Remember – the best Skill you’ll ever build is the one you actually use.