Claude Code skills: Tips, tricks, and how to build your own

Skills are one of the most confusing and important tools for agentic work. A skill can be any type or amount of text that you provide for a model, ranging from a way to capture a common prompt as a shorter alias to extensive instructions for multi-agent orchestration. For a while, Claude Code treated “commands” and “skills” as separate features and then collapsed both into skills; a number of viral “skills” repos are actually a mix of skills and sub-agents, which is a different domain.

Let’s de-mystify this. Everything in agentic work is just context—rules, instructions, or information. That’s true for CLAUDE.md, skills, and sub-agents alike. What changes across these tools is when that context is available and how it is executed.

In this post, we’ll discuss:

What is a skill?
What should go in a skill?
Skill formatting and gotchas
Optimizing skills for context
Writing your own skills

This is a post focused on Claude Code, but the skills format is standard across most agent harnesses such as Pi or OpenAI’s Codex, so everything here should be transferable.

What is a skill?

The best way to think of a skill is information or instructions that a model needs some of the time.

Instructions or information that you want all agents to have, all of the time, go into your user CLAUDE.md, in ~/.claude/CLAUDE.md.

Rules that you want agents to have on all of the time for a specific project can live in the CLAUDE.md of the folder level, for instance ~/Documents/my-project/CLAUDE.md.

When you open Claude Code in ~/Documents/my-project/ or the agent navigates there, it will have both the user-level rules, and the repo-specific ones automatically.

Skills are different.

You can activate them as a user manually, by typing them as a “slash command”: /name-of-skill.

Or, you can allow Claude to load them whenever it so chooses, by providing a description. A description is an always-on instruction for Claude on when to load the full skill.

For example:

You want Claude to do some research from primary sources, and load your research-standards skill. Claude doesn’t need to know about these rules when it is writing Python—they are situational.
You want Claude to follow the same git workflow every time, and encode these rules in a git-workflow skill. Like the research-standards skill, Claude doesn’t need to know about git workflow when you’re doing non-code activities, and should fire it up when it needs to add a new repository branch.

Once the skill is loaded, its rules and information is added to Claude’s context, and now it has new information or steps to follow.

Think of this all as Neo learning kung fu in The Matrix.

Like CLAUDE.md, skills can be scoped to folders, so you can choose to make them available all the time, or just in certain areas. That becomes important for context, as we’ll talk about in the Skill Descriptions section below.

What should go in a skill?

Skills largely divide into two buckets. A set of specific instructions to follow, or information to supplement the model’s training data.

Anything can go in a skill. A few examples:

A shorthand to capture a commonly-used prompt

For a while, I used my /anything-else skill to end many sessions.

Re-examine the work in this conversation, including code, decisions just made, and anything the work touched, drifted from, or cemented. Surface things I haven't thought of — especially cross-file consequences, drift from stated intent (ticket, plan, project rules, loaded skill), assumptions silently locked in, adjacent risks, and knowledge worth capturing.

1. What could be wrong? (bugs, edge cases, silent failures)
2. What could be better? (missed opportunities, improvements, features)

This is really no different than saving this prompt in a text expander, like aText or espanso.

Providing the model distilled information on a topic

When I work on MySQL queries, I would like the model to have access to the performance best practices from the official documentation rather than trust that its training data—which is imperfect at best—has captured all of that nuance and detail.

You could have the model do a web fetch, or use an MCP, and get that data from the docs every time. That avoids staleness and inaccuracy on fast-moving projects, but is also slower—the model has to do the search, find the right pages, digest the relevant information—and wastes tokens re-reading the same pages over and over. My bias is to capture that information once, distill it to the essentials, and then occasionally update.

I tend to generate a new skill or two whenever I am working on a specifically technical topic, such as MySQL performance or VS Code extension development.

I’ll also usually write a skill for any API or MCP I am dealing with, so Claude can scout it once and then have a quick reference on what to do next time. This has been very helpful with tools such as the Datadog MCP.

One of my favorite tricks here is to ask the model to dump anything it knows about the topic from training data into bullet points, then to do the research to build the skill and see what gaps it has that need to be covered.

Another key method here is to track your own practical learnings and edge cases on this topic in the skill over time.

Instructions and tools

Sometimes you want your skill to be a combination of context about a topic as well as instructions to take to address it, or better, deterministic scripts that it can use each time.

You might have a skill that comes with a Python script for querying an API, printing a reliable artifact you can confirm, and then asking the model to analyze the data after it has run the script. This gives you a dependable workflow so the agent can’t miss a step or make a wrong move.

A meta-skill to write skills

This is compound engineering at work. One of the first things I did when I started using Claude was to write skills for writing CLAUDE.md files, agents, and skills themselves.

I have been using my skill-writer skill for months with some minor adjustments. At the time of this writing, I have created almost 70 skills. I will not say “written,” because I didn’t write them, Claude did.

I hope this is your take-away from this post: anything you ever learn how to do, put it in an agent skill, so Claude can do it for you forever.

Some of my most-used skills:

ascii-diagram - generates text diagrams for plans and Markdown files
bash-scripting - my style guide and testing rules for shell scripts
extended-planning - a phased brainstorming workflow for Claude, to avoid jumping to conclusions. Less needed now for frontier models, crucial for Opus 4.6.
iOS-app-dev - does what it says on the tin
tutorial - researches and writes a blog post-length document in a custom format to teach me a small technical topic
workspace-map - Index of my laptop’s files, folders, and where everything should go when Claude creates a new project or is sorting my downloads

Let’s get into the practical details.

Getting started

Always-available skills go in the ~/.claude/skills folder. Put them in a sub-folder, and place the skill instructions in the file SKILL.md. I like to add a README.md in each skill for human use, explain what the skill does and the expected outcome when you run it, in addition to a recommendation on what models it is suited for.

This is important: most of my skills were tuned for Opus 4.6 through 4.8. 4.8 follows them attentively; Opus 5 is sloppy and does not.

A skill can be as simple as:

~/.claude/hello-world/SKILL.md

With the text:

Say 'Hello World'

You would invoke, or run, this by writing it as a slash command after opening claude:

/hello-world

Here’s how that looks. Pretty exciting stuff.

Running the /hello-world slash command in Claude Code, which prints "Hello world"

This skill has no name or description, so Claude doesn’t know about it and can’t load it by itself.

So more practically, your skill should include “frontmatter” written in the YAML language, which here is just a set of key-value pairs and a --- underline to divide it from the instructions and add configuration options and metadata for skill usage.

---
name: hello-world
description: Says "Hello world." Run when the user asks for a skill demonstration.
---

Say 'Hello World'

Now you can tell Claude, /hello-world or “Give me a skill demonstration.”

There’s a lot more that can go into your frontmatter here, which I’ll leave to the Claude Code documentation.

Let’s talk about descriptions—they are more important than you think.

Skill descriptions

When an agent loads, it sees a list of skill names and their descriptions. Descriptions are how an agent knows when to use a skill and what it is about.

Loading this all at start-up has both pros and cons:

The pros:

Your agent does not have to look up what skills are available. It already has the list in its context along with the rules on when to load them. Current models such as Opus 4.8 and beyond are very good at loading skills consistently and autonomously—a more challenging topic back in the Opus 4.5 era. These become instructions that you don’t have to think about triggering.

A great example here is my git-workflow skill. Any time Claude needs to do a Git activity, it loads the skill and it knows the handful of steps I expect it to execute, and I don’t have to remind it—or better, remember myself.

The cons:

Descriptions add to context. You are paying for every token, whether or not you are going to need that skill in that session or not. This adds up fast for longer sessions or large skill libraries. Keep in mind that every skill or plugin you install carries this cost.
Descriptions are instructions. You are literally telling Claude when to take an action—invoke the skill—and so each skill available adds to the burden of rules that Claude has to remember and reason about. An agent can only follow so many rules at once before performance degrades.

Rule overwhelm is less of a concern these days, as modern agents are capable of following many directives over long-horizon sessions, but loading a hundred skills into context for Haiku 4.5 is probably a downgrade you were not expecting.

Optimizing skills for context

Two easy recommendations, and one more complicated one:

Make skills user-invokable only. This removes the description from context, and eliminates the token/rule clutter risk.
Reduce the description to bare minimum. Skill descriptions are for agents, not humans. They should be as concise as possible.

The description of my bash-scripting skill is:

description: Always load for .sh and shell script file CRUD.

“CRUD” is a programmer acronym for “create, read, update, delete.” Claude knows what this means, and this is all it needs to know about when to load the bash-scripting skill.

It does not need to know what the bash-scripting skill does in advance—loading the skill will tell it, so don’t duplicate that information in the description.

Break out larger skills into a map

I have a mix of narrower and more specific skills that just do one thing, and all-in-one skills such as iOS-app-dev that have grown substantially over time.

I organize this by keeping the core instructions in SKILL.md, and using that file to list and point out to additional topic-based sets of instructions in a “supplements” folder, giving us:

~/.claude/skills/example-skill/SKILL.md`
~/.claude/skills/example-skill/supplements/extra-info.md`

When it needs more information on that particular domain, Claude can go and read the extra files as needed.

This is more hit-and-miss than loading the skill itself, but generally it works for me.

Anthropic’s own official Skill Creator skill follows a similar structure and splits additional files into “scripts,” “references,” and “assets.”

Write your own skills!

There are now many, many popular skills on the internet for you to choose from, perhaps most notably the work of Matt Pocock, who is behind Grill Me and many others.

A new one goes viral almost every week, whether it is Caveman or Ponytail.

I am here to tell you: there is no special sauce. Most skills are literally just text files with a few paragraphs of information. Ponytail (which I think is pretty smart, for the record) is 30 lines. Nothing is stopping you from writing your own, using Skill Creator, or pointing Claude at Anthropic’s links on the topic at the bottom of this post and asking it to write you your own skill-writer skill. If you see an idea you like, fork it.

One reason to write your own, besides it being fun and easy, is that publicly available skills do not know about your model, its effort level, or the rest of the rules in your harness. They may be duplicative or worse, contradictory, creating confusion and poor performance. They may be too complex for your model, or not specific enough.

I had some jarring experiences going from Opus 4.6 to 4.7 with my (initially two-line) /anything-else skill, and likewise Opus 5 tends to do poorly with much of my current library.

AI performance is about providing the right information—and as little as possible beyond it—to the right model at the right effort at the right time, so use your judgement, and evaluate your skill library over time as models change.

My open-source skills

OK, you might want to check out just a couple of 3rd-party skills. Here are some of mine, free and open-source on GitHub. You can install them as a Claude plugin, see directions in the READMEs.

Opinionated CSS - A style guide and best practices for modern CSS, heavily influenced by Harry Roberts, Andy Bell, and others.
Technical Writing Voice - My best attempt at getting Claude to write in a way I can tolerate
Greenfield - This is the one I do really recommend. Instead of shipping you a workflow that may or may not match up with your models and project, this skill helps you build your own.

Topics beyond this post

Installing skills from plugins, or packaging skills into them
Sub-agents, and attaching skills to them
Customizing tools allowed or not to pair with skills
Argument hints, and using them as script-style flags for different functionality

See the official docs for more about these items.