Skills in Claude Code

I've been using Claude Code daily for a while now. Most of the time it just works — I describe a task, it writes the code, I review and merge. But every so often I'd hit a task where the model knew the shape of the answer but kept missing the specifics. PowerPoint decks. Internal style guides. The way I like my work-experience entries phrased on my own portfolio site. Things that aren't hard, just particular.

CampusX dropped a video that put a name on this gap and showed how the relatively new Claude Code primitive — Skills — closes it. What follows is my walkthrough of those notes, plus what I learned trying to actually ship a library of them on a real project.

Why Skills?

Claude is a general-purpose language model. That phrase covers a lot of ground — reason, write, code, summarise, translate, plan. But there's a real difference between general capability and reliable, high-quality output for a specific task type. The first is what gets it on the marketing site. The second is what makes it useful for the same job, over and over, the way you'd want it done.

The example the video opens with is PowerPoint generation. Ask Claude to make a deck and it will try — it knows what PowerPoint is, it can reason about slide structure, it knows which Python library to reach for. You get a deck that works. The content is roughly right. But it doesn't know your fonts, your title-case rules, the fact that every internal deck at your company ends on a Q&A slide.

And this same gap shows up everywhere.

The pattern is identical across all of them. Claude has the general capability, but the specialised, "the way we actually do it here" version of the task lives in details the model doesn't have access to.

The instinct, of course, is to write a really good prompt.

This is the problem Skills are designed to solve.

What are Skills?

The one-line version: a Skill is a folder of files that teaches Claude how to do one specific thing well. It's reusable, file-based, and bundles the instructions with the resources Claude needs to act on them.

The folder has a fairly strict shape:

SKILL.md is the only required file. It opens with YAML frontmatter — a name, and crucially a description that tells Claude when this skill should fire. The markdown body underneath is where the actual instructions live: workflows, code patterns, pitfalls to avoid, validation steps, and references to the supporting files.

Around SKILL.md, three optional folders show up by convention:

• scripts/ — executable code that Claude can run (think validate.py, unpack.py).
• resources/ — reference docs loaded on demand (a schema, a style guide, an XML grammar).
• assets/ — templates, fonts, and images that end up inside the output the skill produces.

The body of SKILL.md tells Claude when to read a resource or run a script. None of those files load until Claude actually needs them. Which brings us to the part I think is the cleverest bit of the whole design.

Progressive Disclosure

This is the design principle that makes a library of Skills viable in a context window with a finite budget. The core idea: don't present information to Claude until the moment it's needed.

The practical consequence is the bit worth internalising. Each skill in your library costs roughly 30–50 tokens of startup overhead, and that cost doesn't compound — Claude only pulls in the full content of the one it's actually using on this turn.

It's not "load everything, let the model pick". It's "load nothing, let the model ask for what it needs". Once that clicked I started writing skills more aggressively, since the marginal cost of adding one to the library is essentially nothing.

Steps to create a Skill

1. 01
   Identify the need

   A task you do repeatedly where Claude's default output isn't specialised enough. If you keep typing the same correction every chat, you've found a skill.
2. 02
   Create the directory and write SKILL.md

   Name and description first — that's the part Claude reads to decide whether to invoke. Then the instructions in the body.
3. 03
   Add supporting files (if you need any)

   Templates, schemas, scripts — drop them next to SKILL.md and reference them from the body.
4. 04
   Test that it actually fires

   Give Claude the kind of task it's supposed to handle and watch whether it picks the skill up. If it doesn't, your description is the bug — not the body.

The bit I think is most underrated is that the description field carries surprising weight. Write it vague, and Claude won't invoke the skill; you'll wonder why nothing happened. Write it too narrow, and it only fires on the exact phrasing you used as the trigger. Treat the description like an API contract you're writing for a teammate — make the trigger conditions explicit, list the cases it applies to, name the cases it doesn't.

What I learned shipping eight skills on one project

I went and did this on a side project recently. Installed three public skills — an Excalidraw diagram generator, the Supabase agent-skills bundle, and a changelog generator from awesome-claude-skills — and wrote four custom ones for the team's actual workflow: a design-token researcher, a backend-engineer scaffold for the API conventions I keep ending up at, a unit-test author, and a session-changelog writer.

A few things that didn't make it into the video.

Installing is unglamorous (in a good way)

Two patterns covered the whole library:

# Pattern A — clone someone's skill from GitHub
git clone https://github.com/<author>/<skill>.git /tmp/x
mkdir -p .claude/skills/<name>
cp -r /tmp/x/* .claude/skills/<name>/
rm -rf /tmp/x

# Pattern B — install a marketplace plugin
/plugin marketplace add <publisher>/<package>

The custom ones I just wrote by hand — a folder with SKILL.md, frontmatter, body. That's the whole ceremony. No build step, no registration, no tooling. After the first one, the second took three minutes.

Trigger phrases live inside the description

This is where I think most "I followed the docs and it didn't work" stories come from. My custom descriptions all ended up looking like this:

description: "Write and maintain unit tests using Vitest and Playwright. Use when asked to 'write tests', 'add test coverage', 'test this function', 'create e2e test', or when creating new services/API routes that need testing."

Listing the actual trigger phrases inline was the difference between "Claude picks it up reliably" and "Claude forgets the skill exists". The description isn't documentation — it's the matcher. It needs to read like an if-this-then-that block for the model, not a tagline.

The one skill that didn't fire (and what I think went wrong)

I added a ## Skills Usage (MANDATORY) block to CLAUDE.md listing every skill and when to use it. One of the entries was, almost verbatim:

@session-changelog: ALWAYS run at the END of every session that produces code changes. Append a structured entry to CHANGELOG.md summarising what / why / how.

Six of the seven entries worked exactly as written. The changelog one never fired. Not once.

My read: "end of session" isn't a phase the model can actually observe from inside the session. There's no signal in the conversation that says the user is wrapping up now. Skills fire on request-time triggers — what the user just said, or what Claude is about to do — not on temporal cues from outside the conversation. The six that worked all keyed off something concrete in the user's prompt ("write tests", "create API", "research design"). The changelog one keyed off an event the model can't see.

I haven't fully fixed this — but the answer is probably not a smarter description. The fix is a /changelog slash command I trigger manually, or a stop-hook in settings.json that runs the skill on session end. The skill itself was fine. The trigger was the bug.

If there's one thing I'd hand off from a week of using Skills in anger: the model is very good at picking up a skill once the trigger is clearly written into the description. It is not magic. It cannot infer that you'd like the changelog skill to fire just because you wrote the word "mandatory" in capitals.

What I take away

Skills land somewhere between two things I'd already been doing: ad-hoc prompts I'd keep retyping, and the much heavier path of fine-tuning a model on my own data. They're text files. They live in git. You can share them. You can let the model decide when they apply rather than babysitting every conversation with the same five-paragraph prompt.

The other thing worth saying out loud: this isn't a brand-new idea. People were already cobbling this together with CLAUDE.md files, custom slash commands, and gist-shared prompts. The interesting move from Anthropic is baking progressive disclosure into the format itself — so a library of skills doesn't quietly degrade the model's context window the way a library of long prompts would.

The other thing the library makes you do is name the gaps. Until you sit down to write a backend-engineer skill, you don't have to admit that the version of the task you actually want is different from Claude's default. Writing the skill is the conversation with yourself about what your own conventions even are.

References and Resources

• Anthropic Engineering: Equipping agents for the real world with Agent Skills
• Claude Code: Extend Claude with skills
• Agent Skills — Claude API Docs (overview)
• Skill authoring best practices — Claude API Docs
• The Complete Guide to Building Skills for Claude (PDF)
• awesome-claude-skills (ComposioHQ) — the community list I pulled the changelog generator from.

Massive Shoutout to CampusX

These notes started life as scribbles in the margins of the CampusX "Claude Code Skills: Full Guide" video. If you want the full walkthrough — the host's narration, the live demos, the bits I've collapsed into a sentence here — that's where to go. Same channel I credited in my Gen AI without the Hype post; still the clearest walk-throughs of fast-moving AI tooling I've come across. Subscribe to the CampusX YouTube channel if any of this resonated.