What Is a Claude API Skill? A Clear Explanation

2026-09-01 · 5 min read · SubToAPI Team

What Is a Claude API Skill?

A Claude skill is a packaged, reusable capability that gives Claude specialized knowledge or instructions for a specific task, separate from the general model weights it was trained on. Instead of stuffing every instruction into a single system prompt, a skill bundles together instructions, reference material, and sometimes scripts into a folder that Claude can load only when it's relevant to the task at hand.

If you've used Claude API tool use (function calling), a skill is a different but related idea: tools let Claude call code to fetch data or take actions, while skills give Claude domain expertise — how to fill out a specific type of PDF form, how your company formats invoices, how to follow a particular coding style guide. Skills and tools are often used together: a skill might describe a workflow, and that workflow might invoke tools to actually do the work.

Skills vs. Tools vs. System Prompts

These three mechanisms solve overlapping but distinct problems:

System prompts set general behavior and persona for the whole conversation. They're always loaded, which makes them expensive to bloat with edge-case instructions.
Tools (function calling) give Claude the ability to execute actions — call an API, query a database, run a calculator. The API layer handles the tool definitions, and Claude decides when to invoke them.
Skills package task-specific knowledge that Claude loads on demand, only when the conversation actually needs it. This keeps the base context lean while still giving Claude deep, structured guidance for niche tasks.

The practical benefit of skills is progressive disclosure: rather than paying the token cost of every possible instruction on every request, Claude reads a short skill description first and only pulls in the full skill content when the task matches.

How a Skill Is Structured

A typical skill is organized as a small folder with:

A SKILL.md file containing a short description (what the skill does, when to use it) plus detailed instructions.
Optional supporting files: reference documents, templates, example outputs.
Optional scripts that Claude can execute as part of completing the task, when the environment supports code execution.

Here's a simplified example of what a SKILL.md might look like for a skill that formats changelogs:

---
name: changelog-formatter
description: Use when the user asks to generate or format a changelog entry from commit messages.
---

# Changelog Formatter

Given a list of git commit messages, group them into
Added / Changed / Fixed / Removed sections following
Keep a Changelog conventions. Skip merge commits.
Output valid Markdown only, no commentary.

Claude scans the short description field to decide relevance, and only loads the full body when the task actually matches — which is how skills stay efficient even when you have dozens of them registered.

Skills in Practice via the API

At the API level, skills are typically used through Anthropic's Agent SDK or Claude Code, where the skill files live in a known directory and get discovered automatically. If you're building directly against the Messages API without the Agent SDK, you can approximate the same pattern manually: keep your system prompt lean, and inject task-specific instructions only for the requests that need them, rather than sending every domain rule on every call.

Tool use remains the piece you'll interact with most directly when calling the raw API. A skill might describe "how to summarize a support ticket," but if summarizing requires pulling the ticket from your database first, that's a tool call:

const response = await fetch("https://api.subtoapi.app/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-5",
    max_tokens: 1024,
    system: "You summarize support tickets using the fetch_ticket tool. Follow the internal ticket-summary format: Issue, Impact, Next Step.",
    tools: [
      {
        name: "fetch_ticket",
        description: "Fetch a support ticket by ID",
        input_schema: {
          type: "object",
          properties: { ticket_id: { type: "string" } },
          required: ["ticket_id"]
        }
      }
    ],
    messages: [
      { role: "user", content: "Summarize ticket #4821" }
    ]
  })
});

Here, the "Issue, Impact, Next Step" format is effectively a lightweight skill embedded directly in the system prompt, and fetch_ticket is the tool that supplies the underlying data. As your instruction sets grow, you can split them out into separate documents you load conditionally, which is the same principle formal skills packages are built on.

If you're routing requests like this through SubToAPI, tool use, streaming, and usage metadata all work over the standard Messages-compatible endpoint, so this pattern ports over without changes — see the tools docs and messages docs for the exact request shape.

When You Actually Need a Skill

Not every use case needs a formal skill package. Reach for one when:

The same specialized instructions get reused across many different requests or agents.
The instructions are long enough that including them on every call wastes tokens and context.
You want Claude to only pull in certain expertise conditionally, based on what the user asks.

For a one-off prompt or a simple app, a well-written system prompt is usually enough. Skills earn their complexity in larger agentic systems — coding agents, internal tools with many workflows, or products where Claude needs to behave differently depending on task type.

Getting Started

If you're building against the Claude API and want tool use, streaming responses, and per-application API keys without managing separate Anthropic billing for each project, SubToAPI turns your existing Claude access into a standard HTTPS API. Check the quickstart guide to get a sub_live_... key running in a few minutes, or start a free trial.

Questions

Is a Claude skill the same as a plugin? Not exactly. A skill is closer to a structured instruction package that Claude loads conditionally, while a plugin usually implies a broader integration with its own installation and permissions model. Skills are simpler and more portable.

Do I need the Agent SDK to use skills? Automatic skill discovery is a feature of Anthropic's Agent SDK and Claude Code. If you're calling the raw Messages API directly, you can replicate the same effect manually by conditionally including task-specific instructions in your system prompt.

How is a skill different from a system prompt? A system prompt is always loaded for every request in a conversation. A skill is loaded on demand, only when its description matches the current task, which keeps context usage lower across varied workloads.

What Is a Claude API Skill? A Clear Explanation