Claude Code Skills are folder-based instruction packs that Claude Code loads on demand to turn a general assistant into a specialist for your codebase, workflow, or domain. Each Skill is a directory containing a SKILL.md file plus optional helper scripts and assets; Claude Code reads the folder name and description on every session, and pulls in the body when the current task matches. Out of the box, Claude Code in 2026 supports three layered customization primitives: Skills (long-lived expertise the agent loads when relevant), Hooks (deterministic shell hooks that fire at lifecycle events), and Subagents (forked Claude instances with their own context window). This guide explains all three, when to pick which, how to install and ship your first Skill in ten minutes, and how Skills plug into the Totalum AI app builder so a single Skill can scaffold and deploy a real Next.js application.
And the third piece of the trinity, the Claude Code subagents production playbook, covers when to delegate work to an isolated Claude instance and how the Skills/Hooks/Subagents decision rule plays out in production.
If you only have time for one thing: jump to the Claude Code Skills vs Hooks vs Subagents decision table. It is the cheat sheet most teams need.
Quick Answer
- A Claude Code Skill is a folder with a SKILL.md file (plus optional scripts) that Claude Code discovers automatically and loads when the current task matches the Skill's description.
- Skills give Claude Code repeatable expertise ("how we ship a Next.js feature here"). Hooks give it deterministic side effects ("run prettier on every save"). Subagents give it isolated context windows ("hand this sub-task to a fresh agent").
- Search demand exploded in 2026: "claude code skills" hit 9,900 monthly searches (DataForSEO, May 2026), with "claude code hooks" and "claude code subagents" both at 2,900 monthly searches each.
- Installing a Skill takes two minutes: drop a folder into
~/.claude/skills/or.claude/skills/in your repo, write a SKILL.md, restart Claude Code, and the Skill is live. - Skills do not, by themselves, deploy applications. Pairing a Skill with the Totalum MCP server lets the Skill drive a real builder that creates a production Next.js app with auth, database, payments, and a custom domain.
If you want the full enforcement story (PreToolUse, PostToolUse, Stop, SubagentStop, security guard rails, and a Skills plus Hooks recipe), read our Claude Code hooks production playbook.
Skills compose with the cloud Routines and Dynamic Workflows that Anthropic showcased at Tokyo Day 1; the Code with Claude Tokyo 2026 recap walks through every new Claude Code surface.
What Claude Code Skills are (and what they are not)
A Claude Code Skill is, in plain terms, a folder. Inside it lives a SKILL.md file (the instruction set Claude reads) plus optional scripts, templates, or reference documents. Claude Code discovers Skills automatically from two locations: a user-level folder at ~/.claude/skills/ and a repo-level folder at .claude/skills/. You do not register Skills through an API, and you do not enable them per request. When the model sees a task that matches a Skill's stated purpose, it loads the SKILL.md, follows the steps, and uses whatever scripts the folder contains.
In Anthropic's Agent Skills documentation, Skills are described as a way to give Claude reusable, project-specific knowledge without re-prompting on every session. The same folder format works in Claude.ai (Anthropic-hosted), in Claude Code (filesystem-based), and inside Anthropic's Managed Agents (Tokyo announcement, June 2026). The portability is the point: write the Skill once, run it anywhere Claude runs.
What Skills are NOT:
- Not tools. A tool is a single callable action (read a file, send an email). A Skill is a recipe; it can call tools, but it is not itself a tool.
- Not prompts. A prompt is short-lived instruction text. A Skill is loaded on demand from disk and survives across sessions.
- Not MCP servers. An MCP server publishes tools and resources over the Model Context Protocol. A Skill can call MCP-served tools, but the Skill itself is a folder, not a server.
- Not deploy targets. A Skill describes what to do; producing a deployed application still requires an action layer (filesystem, sandbox, or app builder like Totalum).
Claude Code Skills vs Hooks vs Subagents
This is the question most teams ask first. Each primitive solves a different problem, and the right answer is usually a combination. The table below maps each primitive to a use case so you can pick without re-reading the docs every time.
| Feature | Claude Code Skills | Claude Code Hooks | Claude Code Subagents |
|---|---|---|---|
| What it is | A folder with SKILL.md + optional scripts that Claude loads on demand | Shell commands wired to Claude Code lifecycle events (PreToolUse, PostToolUse, Stop, etc.) | A separate Claude instance the parent agent can delegate a sub-task to |
| When it fires | When the current task matches the Skill's description | At a fixed lifecycle event, deterministically, every time | When the parent agent decides delegation will help |
| Lives where | .claude/skills/ in repo or ~/.claude/skills/ globally |
.claude/hooks/ shell scripts or hooks block in settings.json |
Defined inline in a session; runs in a child process with its own context window |
| Knowledge scope | Long-lived expertise loaded when relevant | None; pure side effect or guard rail | Full task ownership in an isolated window |
| Deterministic? | No, the agent decides when to use it | Yes, runs on event regardless of agent reasoning | No, the parent agent decides when to spawn |
| Best for | Repeatable workflows, house style, "how we do X here" | Formatters, linters, security checks, secret scrubbing, build gates | Hard sub-tasks that benefit from a fresh context window |
| 2026 search volume | 9,900 / mo | 2,900 / mo | 2,900 / mo |
| Replaces in 2026 | README-driven prompts, copy-pasted snippets, CLAUDE.md bloat | Husky-style git hooks, ad-hoc post-commit scripts | Spawning a fresh Claude session by hand for a sub-task |
| Token cost | Low; loaded only when matched | Near zero; runs outside the model | Higher; spawns a new context |
Rule of thumb: Skill = things you want the agent to know how to do. Hook = things you want to happen no matter what the agent does. Subagent = things you want the agent to delegate.
When to use a Claude Code Skill
Pick a Skill for recurring expertise: "how we add a new endpoint here," "how we write a migration in this repo," "how we ship a Totalum project from scratch." The Skill is the playbook so the next session does not need to be re-prompted.
When to use a Claude Code Hook
Pick a Hook when you want something to happen every time, with no agent discretion. Common 2026 Hooks: PreToolUse blocking writes outside the repo, PostToolUse running prettier after every file edit, on-Stop running the test suite, redact-secrets on every shell command. Configure in settings.json or as scripts in .claude/hooks/.
When to use a Claude Code Subagent
Pick a Subagent when the sub-task benefits from a clean context window: a long code review you do not want polluting the parent context, a deep research task that returns a single summary, a parallel exploration of two design options. Subagents return only the final answer to the parent.
For a deeper read, see our best AI coding agents in 2026 roundup and our Claude Code vs Codex in 2026 head-to-head.
What shipped around Claude Code Skills in 2026
The category went from "experimental" to "default expectation" in two quarters:
- Anthropic Agent Skills (March 2026): Skills launched across Claude.ai, the Claude apps, and Claude Code. Same SKILL.md format everywhere.
- Claude Skills marketplace (April 2026): discoverable Skills surface inside Claude. Read our Claude Skills marketplace deep dive.
- Vercel skills.sh API GA (June 5, 2026): ~600,000 open-source Skills indexed, distributed via Vercel OIDC.
- Cline CLI 3.0.16 (June 2026): plugin and Skill bundling so the same SKILL.md works in Cline and Claude Code.
- Anthropic Tokyo Managed Agents (June 2026): Managed Agents in customer-controlled sandboxes with private MCP and 20 legal MCP connectors.
- Claude Partner Network Services Track (June 2026): agencies can distribute their Skills (and Totalum builds) inside the Anthropic partner ecosystem. See the Claude Partner Network breakdown.
One Skill format now travels across all four places Claude runs. The full map is in our agent skills marketplace 2026 comparison.
How to install a Claude Code Skill
Installing a Skill is a two-minute operation.
- Pick a location. Use
~/.claude/skills/for Skills you want everywhere on your machine, or.claude/skills/inside your repo for Skills that should travel with the project. - Create a folder. The folder name becomes the Skill name. Example:
~/.claude/skills/ship-totalum-app/. - Write SKILL.md. The first line should be a one-sentence description of what the Skill does (this is what Claude scans on every session). The body is the playbook.
- Add helper scripts (optional). Drop any reference docs, JSON schemas, prompt templates, or shell scripts in the same folder. SKILL.md can reference them by relative path.
- Restart Claude Code (or run
/reload-skills). Claude rescans the Skills folder and lists your new Skill.
That is the full install path. No package manager, no API call, no enable flag. The portability comes from the folder itself: zip it, share it on GitHub, or drop it into Vercel skills.sh.
How to use a Claude Code Skill in practice
Once a Skill is installed, you do not invoke it explicitly. You describe your task in natural language, and Claude Code picks up the matching Skill automatically.
Example session:
You: Add a new "subscribers" table with email + plan, then ship the project to staging.
Claude: I see your ship-totalum-app Skill in this repo. Loading it.
Claude: (reads SKILL.md, runs scaffold-schema.sh, calls Totalum MCP create-table tool...)
Claude: Subscribers table created. Staging URL: https://app-staging.totalum.app/...You can also force a Skill explicitly: /skill ship-totalum-app run with table=subscribers. The slash-syntax landed in Claude Code 1.x and is documented in Anthropic's Skills overview. For everyday work, automatic matching is usually fine.
Build your first Claude Code Skill in 10 minutes
Here is the minimum viable Skill. We will build one that scaffolds a small Next.js feature scaffold and runs the linter. It will not deploy anything yet (we cover the Totalum-driven version in the tutorial below).
Folder: ~/.claude/skills/new-feature/
SKILL.md:
# New Feature
Description: Scaffold a new Next.js feature with route, component, and test, then run the linter and unit tests.
When the user asks to add a new feature, page, or screen to this codebase, use this Skill.
## Steps
1. Confirm the feature name and target route with the user (one short clarifying question).
2. Create `app//page.tsx` from `templates/page.tsx`.
3. Create `app//.tsx` from `templates/component.tsx`.
4. Create `app//.test.tsx` from `templates/component.test.tsx`.
5. Run `npm run lint` and `npm test -- `.
6. Summarize what was added and what the user should review before commit.
## Conventions
- TypeScript only. No JS files.
- Components use the project's design system (see `lib/ui`).
- Tests use Vitest plus React Testing Library.Helper: drop three template files into ~/.claude/skills/new-feature/templates/ and reference them by relative path. That is it.
Restart Claude Code, ask it to "add a new pricing page," and watch the Skill load. You now have a reusable expertise pack that survives across sessions.
SKILL.md anatomy and authoring best practices
The single most important line in any Skill is the description on the first non-heading line. Claude scans descriptions on every session; vague descriptions never get loaded. Good descriptions are imperative and outcome-focused (write "Scaffold a new Next.js feature with route, component, and test, then run the linter and unit tests" instead of "Helper for Next.js work").
Other authoring rules that pay off:
- Keep the body short. Under 1,500 words per SKILL.md. Long Skills get truncated under context pressure.
- List explicit numbered steps instead of prose guidance.
- Reference helper files by relative path. Avoid inlining huge JSON schemas.
- One Skill, one workflow. If your Skill has two purposes, split it.
- Use frontmatter for metadata. Anthropic-hosted Skills support frontmatter with name, description, and tags.
- Test the Skill cold. Open a fresh session; if the description does not trigger a load, it is too vague.
Claude Code Skills security and least-authority
Skills run code on your machine (or inside your sandbox). That makes them a soft attack surface. Treat them like dependencies.
- Pin the source. Pull Skills from Git tags or commit SHAs, not
main. Vercel skills.sh and Anthropic's marketplace pin to immutable versions. - Read the SKILL.md before installing. It is plain markdown. Five minutes of reading prevents most surprises.
- Use Hooks as guard rails. A PreToolUse Hook that blocks
rm,curl | sh, or writes outside the repo neutralizes most malicious Skills. - Scope filesystem access. Run Claude Code with a project-scoped working directory, not your home directory.
- Audit what Skills you load.
claude skills list(or your equivalent) shows the active set. Remove what you do not need. - For agency client work, sandbox per project. Run each client's Claude session inside its own container or Vercel Sandbox. The Tokyo Managed Agents launch makes sandboxing one click.
The combination of pinned sources plus restrictive Hooks plus per-project sandboxes is the 2026 baseline for shipping Skills in production environments.
Where Skills run: filesystem, Vercel Sandbox, or Totalum
A Skill is a folder, but the runtime matters. The same SKILL.md will produce a very different outcome depending on where Claude executes it.
| Runtime | Filesystem | Vercel Sandbox | Totalum |
|---|---|---|---|
| What you get at the end | Files on your laptop | An ephemeral sandbox with built artifacts | A deployed Next.js app on a real URL with auth, DB, payments |
| Persistence | Survives in your repo | Sandbox dies on idle | Project persists; managed forever |
| Auth/DB/Payments | Not included | Not included | Built-in |
| Custom domain | Not included | Not included | Included |
| Best for | Local development, iteration | Many parallel isolated runs of the same Skill | Production apps that need a live URL and a real backend |
| Code ownership | 100% yours, on disk | 100% yours, in the sandbox export | 100% yours, downloadable any time from the Totalum editor |
The three runtimes are complementary. Many teams iterate on a Skill locally, run CI builds inside Vercel Sandbox, and ship the final production app via the Totalum MCP server when the Skill needs to produce something shippable. For the full marketplace and runtime map, see our agent skills marketplace 2026 comparison.
Tutorial: a Claude Code Skill that scaffolds and ships a Totalum app
Time to make a Skill actually ship a real, deployed application. Totalum is its own AI app builder (peer to Lovable, Bolt, and Replit) that exposes its full builder over MCP and REST. Claude Code can drive Totalum the same way it drives any tool: by calling the Totalum MCP server. Your Skill is the playbook; Totalum is the runtime that materializes the project.
For a refresher on the Totalum MCP server setup, our Claude Code MCP tutorial walks through the basics. Connect to Totalum once, and every Claude Code session can build full Next.js applications via MCP calls.
Below is the 7-step Skill. Drop it in ~/.claude/skills/ship-totalum-app/SKILL.md.
Step 1: Scope check
The first step is a scope check. Have Claude ask the user one clarifying question if app purpose, primary user role, must-ship feature, database entities, or auth requirement is unclear. The cost of asking is one short turn; the cost of skipping is a wrong scaffold.
Step 2: Create the project on Totalum
Call the Totalum MCP create-project tool with the app idea in one paragraph. The builder scaffolds a Next.js project, wires BetterAuth, provisions a database, and returns a project_id.
Step 3: Database schema
For each domain entity, call totalum.create-table with { project_id, table_name, fields: [...] }. Totalum generates the schema, the REST API, and a built-in admin panel.
Step 4: UI
For each route, call totalum.generate-ui with { project_id, route, table, components }. The builder produces Next.js routes and components that use the project's design tokens.
Step 5: Auth and payments
Call totalum.enable-auth with { project_id, providers: ["email", "google"] } and totalum.enable-payments with { project_id, plans } to switch on BetterAuth and Stripe.
Step 6: Deploy
Call totalum.deploy with { project_id, environment: "staging" }. Deployment is included on the Business plan and above.
Step 7: Domain
If the user provided a custom domain, call totalum.attach-domain with { project_id, domain }. Otherwise return the staging URL.
The whole flow runs in one Claude Code session. The Skill is the recipe; Totalum is the builder. The result is a real, deployed Next.js application owned by the user and downloadable from the Totalum code editor at any time.
How agencies and SaaS teams use Skills with Totalum
For agencies, Skill-plus-Totalum compresses client builds from weeks to days. Write one SKILL.md per archetype (booking app, marketplace, internal tool, CRM), run it in a sandboxed Claude Code session per client, and the output is a project the client can take to production immediately.
For SaaS teams embedding an AI builder, the pattern flips: expose Totalum's API or MCP behind your brand and let your users (or their agents) ship projects from inside your product. See how to embed an AI app builder in your SaaS. For Skill-driven patterns on other agents, see Cursor cloud agents vs Totalum and Codex on Windows plus Totalum.
Anthropic-native Skills vs Skills with Totalum
The honest answer to "Anthropic-native Skills or Skills with Totalum?" depends on the artifact you want at the end:
- Pure Anthropic-native Skills when the artifact is a file change in an existing codebase (new endpoint, refactor, test suite). The Skill captures the playbook; the result is a diff.
- Skills that drive Totalum via MCP when the artifact is a new application (SaaS MVP, client deliverable, internal tool with auth and database). The Skill captures the playbook; the result is a deployed app with a real URL.
The two patterns also stack. Agency engagements often use a Totalum-driving Skill to bootstrap and repo-local Skills for subsequent feature work. Both live in .claude/skills/ and travel with the project.
Best Claude Code Skills shipping in 2026
An honest short list, updated each cycle based on community signal and our own testing:
- Anthropic template Skills: the canonical SKILL.md examples; the smallest, cleanest starting point.
- changelog-from-diff (community): summarizes a multi-file change into a release-ready changelog entry.
- migration-from-prisma-schema (community): scaffolds a typed migration from a Prisma schema change.
- ship-totalum-app (Totalum): the 7-step Skill above; drives Totalum's MCP to create, build, and deploy a real Next.js application.
- vercel-skills-sh-import (community): pulls a Skill from skills.sh into your local
.claude/skills/with one command.
For pairing Skills with MCP servers, see our best MCP servers in 2026 roundup and the Claude Code MCP servers 2026 directory.
How Claude Code Skills compare to other AI coding agent skill systems
Claude Code is not the only agent with a Skills-style abstraction. Here is how the 2026 surface lines up.
| Agent | Skill primitive | Format | Marketplace | Sandbox option |
|---|---|---|---|---|
| Claude Code | Skills (SKILL.md folder) | Filesystem | Anthropic + Vercel skills.sh | Vercel Sandbox, Totalum, Tokyo Managed Agents |
| Cursor | Composer modes + custom commands | settings.json | None native | Cursor Cloud |
| Cline | Plugins and Skills (bundled CLI 3.0.16) | Filesystem | Cline plugin registry | Cline-managed |
| OpenAI Codex | Plugins (chat-mode + agent-mode) | JSON manifest | OpenAI plugin store | Codex sandbox |
| Antigravity 2.0 (Google Gemini 3.5 Flash) | Tools-only (no Skills primitive yet) | API | None | Vertex AI sandbox |
The takeaway: Claude Code Skills are the most portable primitive in the category right now because the format is plain markdown plus optional scripts. Cursor's Composer modes are richer in UI but less portable. Cline's plugin format is close to Claude Code Skills and explicitly cross-compatible. OpenAI Codex plugins are the most rigid (manifest-driven) and least portable. For deeper comparisons, see Cline vs Claude Code and our Cursor Composer 2.5 plus Totalum tutorial. The full marketplace map is in our agent skills marketplace 2026 comparison.
For broader pillar context on AI agent platforms, see AI agent platform comparison. For the underlying SDK story, see Claude Agent SDK + Totalum. For model context, our Claude Opus 4.8 + Totalum deep dive covers the model that powers most of these Skills in 2026.
FAQ
How do I install a Claude Code Skill?
Create a folder at ~/.claude/skills// (or .claude/skills// inside a repo if you want the Skill to travel with the project). Inside it, write a SKILL.md file whose first non-heading line is a one-sentence description of what the Skill does. Optionally add helper scripts or templates in the same folder. Restart Claude Code (or run the reload-skills slash command) and the Skill is live. No package manager and no API call are required.
How do I use a Claude Code Skill in a real session?
You do not have to invoke a Skill explicitly. Describe the task in natural language; Claude Code scans the Skills folder on every session, matches your task to a Skill's description, and loads the body when needed. You can also force a specific Skill with the /skill slash command, which is useful when two Skills overlap and you want to be deterministic about which one runs.
What are the best practices for writing a SKILL.md?
Make the first description line outcome-focused and imperative (not vague). Keep the body under 1,500 words. List explicit numbered steps rather than prose. Reference helper files by relative path instead of inlining giant schemas. One Skill should own exactly one workflow; if it has two purposes, split it. Test the Skill in a fresh session to confirm the description triggers a load.
How are Claude Code Skills different from custom prompts or CLAUDE.md?
Custom prompts and CLAUDE.md are loaded into the model context on every turn, which means every token costs you. Skills are loaded on demand only when the current task matches the Skill description, which keeps the per-turn cost low. CLAUDE.md is best for high-level house style that applies always. Skills are best for specific recipes you only want to load when the task calls for them.
Are Claude Code Skills safe to share, and what are the security risks?
Skills run code on your machine, so treat them like dependencies. Pin to a Git tag or commit SHA rather than main. Read the SKILL.md before installing (it is plain markdown). Pair Skills with Hooks that block dangerous commands at the PreToolUse boundary. Run Claude Code with a project-scoped working directory, not your whole home. For agency client work, sandbox each client's session inside its own container or Vercel Sandbox; Anthropic's Tokyo Managed Agents make this one click.
When should I use Anthropic-native Skills versus Skills with Totalum?
Use a pure Anthropic-native Skill when the artifact is a file change inside an existing codebase: a new endpoint, a refactor, a regression test. Use a Skill that drives Totalum via MCP when the artifact is a new application: a SaaS MVP, a client deliverable, an internal tool that needs auth, database, payments, and a real URL. The two patterns stack; many agency engagements use a Totalum-driving Skill to bootstrap the project and a stack of repo-local Skills for subsequent feature work.
Ready to build with Totalum?
If you want a Claude Code Skill to produce a real, deployed application (auth, database, payments, hosting, custom domain), connect Claude Code to Totalum's MCP and try the ship-totalum-app Skill above. Start free at totalum.app and you will have a project URL in under ten minutes. Source code is downloadable from the editor; you own it forever.
Building for an agency or embedding an AI app builder in a SaaS? Book a 30-minute discovery call to see Totalum's API and MCP live.