One-Line Summary: Tools are individual callable functions the model invokes by name (read_file, run_tests); skills are higher-level capabilities the model opts into mid-conversation that bundle a system prompt, instructions, and a curated set of tools — the skill is the unit a model decides to adopt; the tool is the unit it calls.
Prerequisites: Function calling, tool use, what is an AI harness
What Are Skills (vs. Tools)?
A tool is a function with a name, description, and JSON schema. The model decides per turn whether to call it. A skill is a richer artifact: a curated bundle (typically a directory) containing instructions on when and how to apply a capability, often with several tools and worked examples. The model decides whether to take on the skill, and once active, the skill biases the agent's behavior toward that capability for the remainder of the task.
The distinction comes from a practical problem. As tool registries grew past a few dozen entries, dumping every tool description into the system prompt became expensive and confusing. Skills are the solution: organize related tools into named bundles, expose only the bundle names by default, and let the model fetch the full skill spec when relevant. It is a layer of indirection that turns a flat tool list into a navigable hierarchy.
How They Work
In Claude Code's skill model, a skill lives in .claude/skills/<name>/ containing:
- A
SKILL.mddescribing what the skill does, when to use it, and how. - Optional code, prompts, or scripts the skill needs.
- A registration manifest declaring tools the skill provides.
The model is told skills exist and their high-level descriptions. When the model decides to use a skill, it asks the harness to load the skill, which adds the skill's instructions and tools to the active context. The skill remains active until explicitly dismissed or until the conversation rotates away from it.
Tools, by contrast, are always in the registry. The model picks one to call, gets the result, picks the next.
Why It Matters
The skills/tools split scales tool-rich harnesses past the point where flat tool lists break. Ruflo's 314 MCP tools across 5 server groups would be unmanageable without skill-level grouping. The split also matches how engineers actually think — "I am doing a code review" is a skill; "I am running ESLint" is a tool inside that skill.
Key Technical Details
- Skills are not free: Loading a skill adds tokens to the context. Skills should be self-contained enough that the cost is justified.
- Skills can recursively reference other skills: A "code review" skill can invoke a "static analysis" skill.
- Skills carry preconditions: A skill that requires Python should not load when the project is JavaScript — the harness can gate skill availability by file globs, language, or other context.
- Skill discovery is harness-mediated: The model does not crawl the filesystem; the harness presents a skill index.
- Tools inside a skill are name-scoped: Two skills can have a
validatetool without collision. - Skills vs. plugins vs. agents: A plugin is a distribution unit; a skill is a capability unit; an agent is a runtime unit. A plugin can ship multiple skills; a skill can be invoked by multiple agents.
How Harnesses & Frameworks Implement This
| Harness / Framework | Skills | Tools | Notes |
|---|---|---|---|
| Claude Code | ✅ first-class | ✅ | .claude/skills/ dir |
| Claude Agent SDK | ✅ | ✅ | Programmatic |
| ruflo | ✅ via plugins | ✅ (314 MCP tools) | Skills surface as plugin-bundled capabilities |
| LangGraph | N/A as a name | ✅ | "Tools" only; "skills" emerge as graph subroutines |
| AutoGen | N/A | ✅ | Per-agent tool registration |
| CrewAI | Partial — agent definition similar to a skill | ✅ | |
| OpenAI Agents SDK | Partial — handoffs approximate skills | ✅ | |
| Codex CLI | Limited | ✅ | |
| Cursor | Limited (rules ~ skills) | ✅ |
Connections to Other Concepts
sub-agents-as-primitives.md— Sub-agents and skills overlap; sub-agents are isolated processes, skills are biases.hooks-and-lifecycle-events.md,slash-commands.md— Other harness primitives.mcp-as-the-universal-tool-bus.md— How tools cross harness boundaries.plugin-and-marketplace-systems.md— How skills ship.../../multi-skill-agent/02-defining-skills-as-tools/skill-as-tool-abstraction.md— Foundational coverage.
Further Reading
- Anthropic, Claude Code Skills documentation.