Agent Skill vs Tool: What Is the Difference?

An agent skill is reusable operating procedure. A tool is a callable capability.

Use a tool when an agent needs to reach outside the model: read a GitHub pull request, call Slack, search Gmail, run a shell command, inspect a browser, query a database, or create a draft email. Use a skill when the agent needs a repeatable procedure: review a migration, triage an inbox, test a web flow, turn a sales call into a follow-up brief, or investigate a metric change without skipping required checks.

OpenAI's Codex documentation describes skills as the authoring format for reusable workflows and says a skill is a directory with SKILL.md plus optional scripts/, references, and assets (OpenAI Codex skills). OpenAI's function-calling guide describes tools as the way models interface with external systems and access data or actions, often through JSON-schema-defined function tools (OpenAI function calling).

The distinction changes what you build: if the agent cannot access the thing, add a tool. If the agent can access the thing but behaves inconsistently, write a skill.

Question	Agent skill	Tool
What is it?	Instructions, resources, examples, scripts, and boundaries for a repeatable job	Callable function, connector, command, API, browser action, or MCP capability
What does it answer?	"How should the agent do this job?"	"What can the agent do or access?"
Typical format	SKILL.md, references, scripts, assets, examples	JSON schema, MCP tool, local shell command, browser action, SaaS connector
Trigger	Selected because the task matches a reusable workflow	Invoked during execution to read data, compute, or mutate state
Best use	Procedure, judgment, sequencing, evidence, stop rules	External data, side effects, deterministic computation, system integration
Common failure	Vague instructions, huge scope, no completion evidence	Overbroad permissions, bad schema, unsafe mutation, confusing tool descriptions
Review standard	Did the agent follow the workflow and produce inspectable evidence?	Did the call run with the right inputs, permissions, and result handling?

This is why What Is an Agent Skill? defines a skill as a reusable job, not a clever prompt. A skill can mention tools and include scripts, but its main job is procedural: what to inspect first, when to stop, what evidence to return, and how to avoid scope drift.

A tool is any capability the agent can call. Examples matter because "tool" is used loosely across agent stacks.

In OpenAI function calling, a function tool has a name, description, parameters, and schema enforcement. A get_weather, create_ticket, or lookup_customer function is a tool because the model can request the call and pass arguments to application code.

In MCP, a server can expose tools that clients list and call. The MCP tools specification treats tool results as structured or unstructured content and recommends user-visible approval flows for safety-sensitive actions (MCP tools specification). A GitHub MCP server might read repository files, list pull requests, fetch issues, or post comments. GitHub's docs describe OAuth or token-based scopes controlling what can be accessed (GitHub MCP server setup).

Browser tools are another concrete category. The Playwright MCP server lets an agent interact with a web page through structured accessibility snapshots: it can navigate, click, type, inspect roles and text, capture screenshots, and monitor network behavior (Playwright MCP). That lets the agent touch a web app. It does not tell the agent how to run a checkout QA pass or decide whether a visual regression is acceptable.

Slack, Gmail, and GitHub connectors are tools too. Slack's MCP server documentation says integrated apps can search channels, send messages, and perform Slack actions through MCP clients, with workspace admins approving integrations (Slack MCP server). Google Workspace MCP docs describe tools that can search emails, retrieve files, list calendar events, create draft emails, upload files, and schedule meetings while inheriting user permissions and governance controls (Google Workspace MCP servers). Those connectors are powerful because they bridge real systems. They are risky for the same reason.

A skill is the layer that turns capability into a repeatable job.

Anthropic's Agent Skills overview says custom skills package domain expertise and organizational knowledge, while its engineering write-up frames skills as organized folders of instructions, scripts, and resources that agents can discover and load dynamically (Anthropic Agent Skills, Anthropic engineering post). Codex uses the same progressive-disclosure idea: the agent first sees the skill name, description, and file path, then loads SKILL.md only when the skill is relevant.

That packaging detail matters because a useful skill is not just "more instructions." A strong skill usually defines:

• the repeatable job
• required inputs and trusted sources
• the fastest truth path
• which tools to use and in what order
• approval or safety boundaries
• visible completion evidence
• what to do when the task is blocked
• how to collect feedback after the run

That is why How to Write an Agent Skill That Actually Works starts with the skill contract before the long body. A skill for "QA this onboarding flow" should name the route, account state, browser tool, device widths, assertions, screenshots, data reset rule, and final report format. The tool can click. The skill decides what a serious QA pass means.

Imagine a DevRel team has a GitHub MCP server connected to its docs repo. The tool layer can read files, list pull requests, fetch CI results, search issues, and post comments. That still does not create a good review.

A migration-review skill would add the missing operating procedure:

1. Read the migration guide and changed files before opening unrelated context.
2. Identify only changes that touch the migrated API.
3. Compare each usage against the new documented pattern.
4. Run the focused tests or explain why they cannot run.
5. Return blocking findings first, each with file path, line reference, and remediation.
6. Do not post a GitHub review comment unless the user explicitly asks.

Without the GitHub tool, the agent may lack repository evidence. Without the skill, it may read too broadly, miss the migration rule, over-comment on style, or post too early. If the agent already has repo and CI access, another connector will not fix inconsistent judgment. A narrower skill might.

A Playwright MCP tool can navigate to a checkout page, fill a field, click a button, inspect accessibility roles, and capture screenshots. Those are actions. They are not a QA strategy.

A checkout QA skill might require the agent to:

• start from a clean test account and a seeded cart
• run desktop and mobile widths
• verify the happy path first, then card decline, missing address, and expired session
• watch console errors and failed network requests
• never use a real payment method
• capture screenshots at the cart, payment, confirmation, and error states
• finish with a pass/fail table, reproduction steps, and the exact environment

The tool supplies hands. The skill supplies the checklist, guardrails, and proof. If the "Pay" button is hidden behind a cookie banner, the browser tool can reveal it. The skill decides whether that is a blocker.

Slack and Gmail are where the distinction becomes operationally important. A Gmail or Google Workspace tool may search email, retrieve attachments, create drafts, and schedule meetings. A Slack tool may search messages, read channel history, and send replies. Those capabilities are useful, but the raw tool surface is too broad for most business workflows.

An inbox-triage skill should constrain the work:

• inspect unread threads from the last business day
• classify each as customer issue, internal decision, scheduling, sales, or ignore
• do not send anything without approval
• draft replies only for threads with clear owner and context
• cite the source thread or message timestamp
• surface ambiguous or sensitive threads instead of guessing

The tool has permission to read and draft. The skill decides the policy for acting. That boundary helps teams avoid stale drafts, private-data leakage, and false urgency.

Tools can mutate systems. They can send messages, delete files, update issues, run code, purchase services, or expose private data. MCP's tools specification recommends clear UI for exposed tools, visible indicators when tools run, and confirmation prompts so a human can deny invocations. The same themes appear in community discussions: permission boundaries, context leakage, prompt injection, and vague threat models show up in r/mcp security threads (Reddit r/mcp thread).

Skills are safer in one sense because they are instructions. They do not automatically send the Slack message or merge the pull request. But skills still carry procedural risk. A bad skill can instruct an agent to overuse a tool, skip approval, trust unverified sources, write secrets into logs, or continue when required context is missing. Anthropic's engineering post notes that skills can introduce vulnerabilities or direct agents toward unintended data exfiltration when they include instructions or code.

For skill authors, the practical safety rule is:

• Put permissions in tools.
• Put judgment and boundaries in skills.
• Put approval at the point where a tool can affect the outside world.

For example, the GitHub tool should enforce OAuth scopes. The review skill should say when posting is allowed. The host should ask for confirmation before publishing, merging, deleting, emailing, or changing production data.

Start with the failure mode.

If the agent cannot retrieve the pull request, search Slack, open the browser, query the warehouse, or create a draft email, you are missing a tool. Build the smallest capability with narrow permissions.

If the agent can access everything but produces uneven work, you are missing a skill. Write the workflow: where to start, which evidence matters, what order to follow, what not to touch, when to ask, and what final answer proves the job was done.

If the work repeats and touches external systems, you need both. A data-quality investigation might need warehouse queries, dashboard APIs, and chart rendering, while the skill requires metric definitions, freshness checks, grain validation, baseline comparison, caveats, and follow-up questions. A support escalation might need Gmail, Slack, CRM, and issue-tracker tools, while the skill defines classification, priority, privacy, draft policy, and handoff evidence.

Use this decision table:

Situation	Build or use
The agent needs data or an action from another system	Tool
The same job repeats across people, repos, accounts, or customers	Skill
The agent has access but keeps skipping important checks	Skill
The action has side effects or sensitive data	Tool permissions plus skill boundaries plus host approval
The output needs a stable format for review or analytics	Skill
The model needs deterministic computation	Tool or script referenced by a skill
The team wants to improve the workflow after real usage	Skill with feedback collection

That last row matters for Skillfully's audience. Skill authors are operating reusable workflows, not polishing one-off prompts. Once a skill is used repeatedly, the important questions become: where did it fail, which instruction was vague, which tool was missing, and what feedback should change the next version? How to Test an Agent Skill Before You Publish It goes deeper on that validation loop.

The cleanest architecture is layered:

1. Tools expose narrow capabilities. A GitHub tool reads pull requests. A Slack tool searches messages. A browser tool clicks and types. A warehouse tool runs approved queries.
2. Skills define workflows. A review skill, triage skill, QA skill, or metric-diagnostics skill tells the agent how to use those capabilities in sequence.
3. The host enforces approvals. The runtime or client decides what needs confirmation, what runs in a sandbox, and what credentials are available.
4. Feedback improves the skill. After the run, the skill author looks at whether the workflow succeeded, failed, or needed a missing prerequisite.

Avoid two extremes.

Do not bury workflow logic inside tool descriptions. A post_slack_message tool description should explain the inputs and risk, not the entire communication policy for customer escalations.

Do not make skills pretend to be tools. A skill cannot access a private repo, read Gmail, or click a browser unless the host supplies those capabilities. If a skill depends on a tool, name that dependency plainly.

The best design is simple to audit: tools are small and permissioned; skills are specific and inspectable; approvals are visible; feedback is captured after the attempt.

Is an MCP tool the same thing as an agent skill?

No. An MCP tool is a callable capability exposed by an MCP server. An agent skill is reusable procedure. A skill may instruct the agent to use an MCP tool, but they solve different problems.

Can a skill include code?

Yes. Codex and Anthropic-style skills can include scripts, references, and assets. The distinction is that the skill packages the job: when to run the script and how to use its output.

Should every tool have a matching skill?

No. Simple tools like get_current_time or format_json may not need a skill. Skills become valuable when work repeats, crosses systems, or needs visible evidence.

If the question is "can the agent do this action?" you are talking about a tool. If the question is "does the agent know how to do this job well?" you are talking about a skill.

A capable agent stack needs both, but they should stay distinct. Tools give reach. Skills give discipline. Approvals give control. Feedback gives the skill author a way to improve the workflow after real use.