Most people who customise Claude Code stop at slash commands. A markdown file in .claude/commands/, a few lines of instructions, done. And slash commands are useful — quick, reusable, easy to share.

But they are not skills.

A skill is something fundamentally different. It is not a prompt. It is a folder — with scripts, reference files, templates, hooks, and sometimes entire Python libraries inside it. When Claude activates a skill, it does not just follow a set of instructions. It discovers what is in that folder, reads what it needs, runs what it must, and adapts to the situation.

The difference is the difference between handing someone a recipe card and giving them access to a full kitchen.

What a skill looks like

A slash command is a single file:

.claude/commands/review.md

A skill is a directory:

my-skill/
├── SKILL.md            # Instructions + metadata
├── scripts/            # Executable code Claude can run
├── references/         # Documentation loaded on demand
├── templates/          # Output scaffolds and starting points
└── assets/             # Fonts, images, data files

The SKILL.md is the entry point — it tells Claude what the skill does, when to use it, and what resources are available in the folder. But the real power is in everything else. Scripts that Claude executes. Reference docs it reads when it needs them. Templates it copies and fills. Assets it incorporates into its output.

This structure enables something called progressive disclosure. Claude does not load the entire skill into its context window at once. It reads the metadata first — a hundred words or so — and keeps that in mind throughout the session. When the skill triggers, Claude reads the full instructions. When it needs a specific reference or script, it reads just that file. Nothing is wasted.

Think of it like a well-organised workshop. The tools are on the wall, labelled. You do not carry every tool with you at all times. You walk to the wall when you need one.

How skills differ from everything else

Claude Code has several extension points. They overlap, and the terminology can be confusing. Here is the distinction:

ExtensionWhat it isAnalogy
Slash commandA single markdown file with instructionsA recipe card
SkillA folder with instructions, scripts, references, and assetsA full kitchen
HookA script that fires automatically on an event (file saved, tool used, session ends)A smoke alarm
MCP serverA service that gives Claude access to external tools and dataA phone line to a specialist
PluginA bundle that can include skills, hooks, MCPs, and commands togetherA franchise kit

The practical difference: a slash command tells Claude what to do. A skill gives Claude what it needs to do it well — and the intelligence to decide how.

An example. Imagine you want Claude to review your code. A slash command might say “check for bugs, security issues, and style problems.” That works. But a skill could include a references/security-checklist.md with your organisation’s specific security rules, a scripts/lint.sh that runs your linter programmatically, and a templates/review-report.md that structures the output consistently. Claude reads the checklist, runs the linter, and fills the template. The review is better because Claude has better tools — not just better instructions.

The sophistication spectrum

Not every skill needs to be complex. After cataloguing dozens of skills across different projects, a clear pattern emerges. Skills fall into three tiers:

Thin skills — just SKILL.md

Most skills start here. A single markdown file with instructions, a few hundred to a few thousand words. No scripts, no assets.

When this is enough: The skill is primarily about knowledge — what Claude should know, what mistakes to avoid, what patterns to follow. A skill that teaches Claude your design system, or your team’s API conventions, or the gotchas of a specific library. The value is in what Claude reads, not what it runs.

Example: One of the most effective thin skills in the Claude Code ecosystem is a frontend design skill. It does not teach Claude how to write CSS — Claude already knows that. Instead, it teaches Claude to avoid the patterns that make AI-generated interfaces look generic: the default font choices, the predictable gradient backgrounds, the safe colour palettes that every AI tool reaches for. The skill’s entire value is in pushing Claude away from its defaults and toward something with actual taste. A few hundred words of opinionated guidance, and every interface Claude builds looks noticeably better.

Medium skills — instructions + scripts or references

The skill includes helper scripts Claude can execute, or reference documents it reads on demand. This is where progressive disclosure starts to matter — Claude loads what it needs, when it needs it.

When this is enough: The skill involves a mix of knowledge and action. Claude needs to both understand something and do something with that understanding. A skill that scaffolds a new project, runs validation, or generates structured output from a template.

Example: A migration skill with references/schema-v2.md describing the target schema, scripts/validate-migration.sh to check the result, and templates/migration-report.md for the output format. Claude reads the schema, writes the migration, runs validation, and formats the report — all from one invocation.

Thick skills — production systems

The skill is a small application in its own right. Multiple Python modules, template libraries, validation pipelines, asset directories. These are rare, but they are where skills become genuinely transformative.

When this is the right call: The task is complex enough that instructions alone are insufficient. Claude needs executable logic — colour palette generators, image processing pipelines, animation template libraries, document manipulation tools. The skill gives Claude capabilities it does not have natively.

Example: A GIF creation skill with twenty Python modules — a frame composer, colour palette generator, typography renderer, fifteen animation templates (bounce, spin, fade, morph), and a strict validation pipeline that ensures every output meets Slack’s size constraints. Claude does not figure out how to make a GIF from scratch each time. It uses a well-tested library that handles the hard parts.

The nine types of skills

Skills cluster into recurring categories. Recognising these patterns helps you identify which skills your workflow is missing.

1. Library and API reference

Skills that teach Claude how to use a specific library, SDK, or internal tool correctly.

Use case: You have an internal billing library with edge cases that Claude gets wrong. The skill documents the gotchas, includes code snippets for common operations, and warns Claude about the footguns. Claude stops making the same mistakes.

2. Product verification

Skills that test whether Claude’s output actually works. These pair with tools like Playwright, tmux, or a headless browser to verify behaviour programmatically.

Use case: You just built a signup flow. Instead of manually testing it, you invoke a verification skill that drives a headless browser through the entire flow — signup, email verification, onboarding — asserting state at each step. If something breaks, you know immediately.

3. Data fetching and analysis

Skills that connect Claude to your data stack. They include helper functions for querying databases, specific dashboard IDs, and instructions for common analysis workflows.

Use case: “What happened to signups on Tuesday?” Claude reads the skill, finds the right tables and event names, writes a query, runs it, and gives you the answer. No context-switching to a dashboard.

4. Business process automation

Skills that automate repetitive workflows into one command. Aggregating activity into a standup post. Creating tickets with the right fields. Generating a weekly recap.

Use case: Every morning, you invoke your standup skill. Claude checks your git history, open tickets, and recent Slack activity, then formats a standup post. Because the skill stores a log of previous standups, Claude knows what changed since yesterday.

5. Code scaffolding and templates

Skills that generate boilerplate for specific patterns in your codebase. Especially useful when the scaffolding involves natural language requirements that pure code generation cannot cover.

Use case: “Create a new API endpoint for user preferences.” The skill knows your authentication pattern, your error handling conventions, your test file structure, and your logging standards. Claude scaffolds everything correctly the first time.

6. Code quality and review

Skills that enforce your standards. These can include deterministic scripts for maximum robustness, or multi-agent patterns where one agent writes and another critiques.

Use case: After finishing a feature, you invoke a quality skill that spawns five parallel agents — one checking security, one reviewing performance, one looking at code style, one testing edge cases, one checking accessibility. Each reports independently. You get a comprehensive review in the time it takes a single human reviewer to read the diff.

7. CI/CD and deployment

Skills that help you build, test, deploy, and monitor. They reference other skills to collect data and make decisions.

Use case: Your deploy skill builds the project, runs smoke tests, starts a gradual traffic rollout, monitors error rates against the previous version, and auto-rolls back if the rate spikes. One command, full deployment lifecycle.

8. Runbooks

Skills that take a symptom — an error, an alert, a Slack thread — and walk through a structured investigation.

Use case: The on-call alert fires. Instead of scrambling through dashboards, you invoke the runbook skill with the alert name. Claude checks the usual suspects — recent deploys, database connections, upstream services, error logs — and produces a structured findings report.

9. Infrastructure operations

Skills for routine maintenance — finding orphaned resources, managing dependencies, investigating cost spikes.

Use case: “Why did our storage bill spike this month?” The skill knows your bucket names, your cost query patterns, and your expected baseline. Claude investigates and tells you which bucket grew, when, and what is in it.

Why multi-agent skills are the frontier

The most interesting skills being built right now are not single-agent workflows. They are skills that spawn multiple agents — each with a different perspective, a different job, a different persona — and synthesise the results.

A code review skill that runs one agent is good. A code review skill that runs five agents in parallel — one focused on security, one on performance, one on readability, one on test coverage, one on architectural fit — is categorically better. Each agent sees different things. The combined output catches what no single pass would.

A creative review skill that spawns four personas — an art director, a copywriter, a UX critic, a brand strategist — and has them critique and debate each other’s findings produces a richer, more challenging review than any single prompt could.

This pattern — parallel agents with distinct perspectives, followed by synthesis — is the frontier of what skills can do. It is also the hardest to build well, which is why the paid guide below walks through it step by step.

Getting started

You do not need to build a thick, multi-file skill to begin. Start thin. Here is a complete, working skill you can install in under a minute:

mkdir -p ~/.claude/skills/design-check

Create ~/.claude/skills/design-check/SKILL.md:

---
name: design-check
description: Quick visual design review. Checks colour contrast, spacing consistency, typography hierarchy, and responsive behaviour. Use when the user says /design-check, "check the design", or "does this look right".
---

# Design Check

Review the current project for visual quality. For each item, state PASS or FAIL with a one-line explanation.

## Checklist

- Colour contrast meets WCAG AA (4.5:1 for body text, 3:1 for large text)
- Typography hierarchy is consistent (headings, body, captions — no orphaned sizes)
- Spacing rhythm is even (no elements with inconsistent margins)
- No default browser styles leaking through (blue links, serif fallbacks)
- Responsive at 320px, 768px, and 1440px — no horizontal scrolling
- All images have descriptive alt text
- prefers-reduced-motion disables all animations

Report findings. Do not fix anything — just report.

That is a working skill. Type /design-check in any Claude Code session and it runs. From here:

  1. Test it. Notice where Claude struggles or misses things.
  2. Add a reference file for the thing Claude keeps getting wrong.
  3. Add a script for the thing you keep doing manually.
  4. Keep building from real friction — not hypothetical features.

The best skills are not designed in advance. They are grown from repeated use.

The paid guide includes six advanced skills — multi-agent code audits, adversarial decision reviews, creative councils — each demonstrating a pattern you can adapt to your own workflow.

Art & Algorithms publishes guides, tutorials, and prompt packs at the intersection of art and code. Subscribe for the full archive.