What are Agent Skills? Your Guide to Skills

What are Agent Skills?

Agent Skills (or Skills) are a new standard introduced by Anthropic for giving agents "modular capabilities" that are dynamically loaded [1]. Skills solve the problem of loading specific context and code only when needed, rather than including unnecessary context that will inevitably degrade agent performance (context bloat).

Examples of "modular capabilities," AKA Skills are:

1. Skills to work with Google Sheets

2. Skills for how your team conducts code review

3. Skills for coding agents on React best practices

With Skills, agents can dynamically load context on how to work with Google Sheets, how your team reviews code, and how to best work with React. Skills can also include code/scripts for use cases like Google Sheets or GitHub API calls.

What makes Agent Skills different from tools, MCP, and slash commands is that Skills package discovery, context, and code execution together in an efficient vehicle, without bloating the context window (more on this later).

How do Agent Skills work?

Discovery

While Agent Skills may seem complex, under the hood, Skills are just a directory of markdown files and scripts that conform to the Skills standard. The entry point to an Agent Skill is the SKILL.md file with a name and description at the top of the file. The Skill name and description are the only context loaded with each prompt.

The rest of the SKILL.md file should have context relevant to your skill. For example, in our proofreading Skill for reviewing articles, we may want to include specific instructions on how the agent should proofread, what tools to use, or how to use subagents to parallelize work.

---
name: proofreading
description: Context on how to proofread articles
---
## What I do
Provide additional instructions on how to proofread

## When to use me
Use this skill only for written articles (NOT CODE).
Use this skill when the user asks for a
- proofread
- grammar check
- writing improvements
- a similar ask to the ones above
...

<example>
User: Check this article for grammar, a light tone, places to add imagery (especially smell).
Agent: I'll spin up 3 subagents:
1. Check grammar paragraph by paragraph
2. Read through the entire article to check for tone
3. Read through the article section by section, and comment on imagery opportunities, focusing on smell
</example>

<reasoning>
The user asked for many different checks. Grammar and imagery are very specific writing checks that are hard to comment on for the entire article. Instead, chunk the article by paragraph or H2 sections.
</reasoning>

Context loading

The agent uses the Skill name and description to determine whether a skill is needed, and the additional context is loaded only when the skill is called on. This pattern is known as "progressive disclosure,” where context is delivered in stages rather than all upfront [2].

You can further build on progressive disclosures by using the SKILL.md as a table of contents to reference other markdown files in your Skills directory. This allows your agent to progressively discover additional context.

Code execution

In addition to markdown files, scripts can also be included to run commonly used code, giving Skills a tool calling feel.

For example, in our proofreading skill, we may want to include scripts that interact with file/document integrations (Notion, Google Drive, Confluence), so agents can upload revisions directly to our users' SaaS tools. This type of 3rd-party action is the type of problem Paragon's integration infrastructure simplifies. ActionKit handles authentication and simplifies 3rd-party APIs, making it simple to work with your users' Notion, Google Drive, or Confluence in a tool call or Skill script.

fetch(`https://actionkit.useparagon.com/projects/${project_id}/actions/#CONFLUENCE_UPDATE_PAGE`, {
  method: "POST",
  body: JSON.stringify(pageBody),
  headers: {
    "Authorization": `Bearer ${paragonToken}`,
    "Content-Type": "application/json",
  },
})

With markdown for context and scripts for code execution, an Agent Skill can be structured like the example below and loaded into any agent that supports Skills (i.e. Claude Code, OpenCode, Cursor)

Agent Skills in action

You’ve seen the mechanics of Skills and how they’re developed. Here's how Skills are used by an agent like OpenCode (this example uses the proofread-skill we’ve been referencing above).

1. Agent loads the skill from SKILL.md into its context

2. Agent creates a plan using the subagent instructions in the SKILL.md

3. Agent spins up subagents and provides an in-depth proofread

When should you implement Agent Skills

Agent Skills are not magic. Agent Skills are just markdown files and scripts wrapped in a harness that makes it easy for LLMs to discover markdown files, load context from files dynamically, and run code from scripts.

If you're building an agent, you should consider implementing Skills if your agent has:

1. Specialized capabilities that only need to be applied in specific situations

Skills progressively disclose context so that long markdown files and descriptions don't get sent with every prompt. At the same time, when your agent needs those files and descriptions, they are loaded when intent for a skill is detected.

2. Context management requirements with long & complex tasks

All agents (no matter what model) perform better with less context bloat. Progressive disclosure reduces unnecessary context for those long-running tasks where your agent may be in a loop, with multiple messages and tool calls to keep in context.

3. Extensibility features where developers and users alike can add capabilities and code

Heavyweight standards like MCP and A2A require familiarity with code and intimate knowledge of the standard. In contrast, Agent Skills are just markdown files in folders that anyone can author. Your developers can ship agent features faster, and your users may even want to extend your agent with their own custom skills!

When Agent Skills are not the right solution

Skills were developed to solve the context management problem. Skills aren’t a catch-all solution for every agent use case. For example:

1. RAG with dynamic context

In a way, Skills are performing Retrieval-Augmented Generation where the retrieved context is static markdown files. When you need to retrieve external context that’s dynamic and up-to-date, existing RAG solutions like vector search, graph queries, and text-to-SQL are better solutions. While indexing and keeping data up-to-date in databases can be a heavy engineering effort, it's still the best way to supply agents with a wealth of user-specific knowledge.

It's one of the reasons Paragon users use Managed Sync. Paragon manages the infrastructure for pulling your users' 3rd-party integration data (Google Drive files, CRM records, and ServiceNow tickets) so you can pull the data with just an API call.

fetch(`https://sync.useparagon.com/projects/${project_id}/syncs`,{
  method: "POST",
  body: JSON.stringify({
    "integration": "googledrive",
    "pipeline": "files",
  }),
  headers: {
    "Authorization": `Bearer ${paragonToken}`,
    "Content-Type": "application/json",
  },
})

2. Routine code execution

Skills can execute code through scripts, but tools are still the preferred method for code execution that needs to be consistently run. Tools send their descriptions with every call. Thus, they are more discoverable and consistent than scripts that are discoverable only through nested markdowns. In general, it's best to keep code that needs to be commonly run in tools, and code specific to a capability in Skills.

3. Overarching context

Progressive disclosure, the pattern used by Agent Skills, avoids full upfront context loading. But the cost of progressive disclosure is that if the Skill is not called upon, then the Skill's context is never loaded. In Vercel's article on AGENTS.md vs Skills, they found that Skills weren't always reliably triggered in their NextJS benchmarks.

System prompts are still the most reliable way to ensure context on an agent's purpose and important instructions are always respected by the agent.

4. Multi-tenancy, authentication, and client-server architecture

This deserves a more in-depth discussion on the role of MCP Servers, which brings us to…

How do Agent Skills fit with MCP?

When a new standard is released, it's natural to question if the new standard (Agent Skills) replaces old standards (MCP).

For certain MCP use cases, Agent Skills is an ergonomically better way to provide context and code for agents to run. Writing SKILL.md files is much easier than developing MCP Servers, and sharing these Skills via markdown files is also easier than connecting an MCP Client to an MCP Server.

But what MCP offers over Skills is:

1. Multi-tenancy: MCP Servers can serve multiple MCP Clients and provide each client with a different tools, prompts, and resources.

2. Authentication: Remote, multi-tenant MCP servers use HTTP which can securely transport OAuth credentials and tokens (important for 3rd-party APIs and integrations).

3. Defined tools: Tools are a first-class primitive for LLMs and don't require a local environment or sandbox to execute in an MCP server (Skill scripts are bash commands; for multi-tenant apps, bash is dangerous to run without a dedicated sandbox per tenant).

Use MCP if your agent needs to handle multiple tenants within a single server/environment. MCP's Server-Client architecture is heavier than Skills' directory-based structure, but the MCP standard is built to be able to run remotely with authentication.

Many MCP Servers have already been developed by SaaS companies and in open source. For example, Paragon's ActionKit MCP can be easily self-hosted to provide hundreds of different integration tools for multi-tenant SaaS applications. Using these pre-built MCP Servers takes away much of the upfront effort in implementing multi-tenant agent applications.

Wrapping Up

Agent Skills is solving the universal context bloat problem with a simple and effective solution. Agent Skills can be used by any LLM model and integrated into any LLM harness.

Likewise, Paragon is an integrations infrastructure platform that can work with any LLM or agent framework. Our customers use Paragon to integrate their agents with Slack, Google Drive, and Jira, just to name a few. Paragon's platform offers:

• ActionKit to instantly provide an agent with 700+ integration tools like SEND_SLACK_MESSAGE and UPDATE_SALESFORCE_CONTACT

• Managed Sync for production-level RAG ingestion & permissions on knowledge bases like Google Drive, Confluence, Salesforce, and ServiceNow.

If you're interested in building the best agents with integrations your users will love, try Paragon on a free trial or book a demo with our team.

Citations & Resources

[1] https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

[2] https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

[3] https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals