What Are AI Agent Skills? The Universal Capability Pattern

Every useful AI agent does something specific. A customer support agent answers product questions. A coding agent writes and debugs code. A scheduling agent manages calendar events. These specific things an agent can do are its skills.

For the first wave of AI agents, skills were implicit — baked into prompts and code, undocumented, and invisible to other systems. But as agents need to work together (a research agent handing off to a writing agent, a planning agent delegating to specialist agents), skills need to be explicit, discoverable, and standardised. If agent A can't tell agent B what it's capable of, collaboration is impossible.

That's the transition happening now. Across every major AI platform — from Google's A2A protocol to Anthropic's Claude Code to OpenAI's Codex — a common pattern is emerging: agents advertise their skills in structured formats, other agents discover those skills, and orchestration systems route tasks to the agent with the right skill for the job.

Despite different implementations, every major platform has converged on the same fundamental concept: an agent has a list of things it can do, each described with a name, a description, and some form of invocation mechanism. The vocabulary differs — "skills", "tools", "commands", "capabilities" — but the pattern is identical.

Google A2A: Skills in the AgentCard

In Google's Agent-to-Agent (A2A) protocol, skills are first-class citizens. Every agent publishes an AgentCard at /.well-known/agent.json that includes a skills array. Each skill has:

{
  "skills": [
    {
      "id": "generate-report",
      "name": "Generate Financial Report",
      "description": "Creates a quarterly financial report from accounting data. Accepts a date range and outputs a formatted PDF with charts, tables, and executive summary.",
      "tags": ["finance", "reporting", "pdf"],
      "examples": [
        "Generate a Q1 2026 financial report",
        "Create a profit and loss report for January to March 2026"
      ]
    },
    {
      "id": "answer-questions",
      "name": "Answer Product Questions",
      "description": "Answers questions about our product features, pricing, and capabilities using our knowledge base.",
      "tags": ["support", "product", "knowledge-base"],
      "examples": [
        "What integrations do you support?",
        "How does your pricing work for teams over 50 people?"
      ]
    }
  ]
}

Other agents discover these skills by fetching the AgentCard. An orchestrator agent tasked with "create a quarterly report" can scan available agents, find one with a "generate-report" skill, and delegate the task via A2A's JSON-RPC protocol.

Claude Code: Slash Commands as Skills

Claude Code implements skills as slash commands stored in the .claude/commands/ directory. Each command is a Markdown file that defines what the skill does:

# .claude/commands/review-pr.md

Review the pull request at $ARGUMENTS.

Check for:
1. Code quality and style consistency
2. Potential bugs or edge cases
3. Missing tests
4. Security concerns
5. Performance implications

Provide a structured review with severity levels (critical, warning, note)
for each finding.

Users invoke this skill with /review-pr 123. The skill pattern is the same: a named capability with a description, expected inputs, and defined behaviour. Claude Code supports both project-level commands (in .claude/commands/) and user-level commands (in ~/.claude/commands/).

OpenAI Codex: Task Definitions

OpenAI Codex structures agent capabilities as task definitions, documented in AGENTS.md. While less formally structured than A2A skills, they follow the same pattern: named capabilities with clear descriptions of what the agent can do, what inputs it needs, and what output to expect.

MCP: Tools as the Machine-Callable Layer

The Model Context Protocol (MCP) takes the concept of skills and makes them directly callable. MCP tools are the machine-executable version of skills:

// MCP tool definition
{
  "name": "search_products",
  "description": "Search the product catalogue by keyword, category, or price range",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search keywords" },
      "category": { "type": "string", "description": "Product category filter" },
      "maxPrice": { "type": "number", "description": "Maximum price in GBP" }
    },
    "required": ["query"]
  }
}

Where A2A skills are described in natural language and invoked with natural language tasks, MCP tools are described with JSON schemas and invoked with structured parameters. Both are expressions of the same underlying concept: documented capabilities that agents can discover and use.

The Pattern Across Platforms

Platform	Term Used	Where Defined	Invocation	Discovery
Google A2A	Skills	agent.json skills array	Natural language via JSON-RPC	AgentCard fetch
MCP	Tools	mcp.json + server	Structured parameters	MCP manifest
Claude Code	Commands/Skills	.claude/commands/	Slash command + args	Local directory scan
OpenAI Codex	Tasks	AGENTS.md	Natural language	File read
GitHub Copilot	Extensions	Extension manifest	Chat commands	Extension registry

The terms "skills" and "tools" are often used interchangeably, but there's a meaningful distinction that matters for system design.

Aspect	Skills	Tools
Abstraction level	High — what can be accomplished	Low — what operations are available
Granularity	Coarse — "Generate a financial report"	Fine — "query_database", "format_csv"
Invocation	Natural language ("Create a report for Q1")	Structured parameters ({"query": "...", "format": "csv"})
Composition	One skill may use multiple tools	Tools are typically atomic operations
Documentation	Descriptions, examples, use cases	Input schemas, output types, error codes
Primary protocol	A2A, agent.json	MCP, function calling
Audience	Orchestrator agents, users	Direct agent consumers

A practical example: a customer support agent might have a skill called "Resolve billing inquiry". To execute that skill, it uses several tools: lookup_customer, get_invoices, apply_credit, send_email. The skill is what the agent advertises to the outside world; the tools are the internal mechanisms it uses.

The Skill-Tool Stack

Think of it as a layered architecture:

┌─────────────────────────────────────┐
│  User / Orchestrator Agent          │  "Generate Q1 report"
├─────────────────────────────────────┤
│  Skills Layer (A2A)                 │  generate-report skill
├─────────────────────────────────────┤
│  Agent Logic                        │  Decides which tools to call
├─────────────────────────────────────┤
│  Tools Layer (MCP / Function Calls) │  query_db, format_csv, generate_pdf
├─────────────────────────────────────┤
│  Infrastructure                     │  Database, file system, APIs
└─────────────────────────────────────┘

Users and orchestrator agents interact at the skills layer. The agent translates skill invocations into tool calls. Tools interact with infrastructure. Each layer abstracts the complexity below it.

Regardless of platform, a well-defined skill contains the same core elements:

1. Name

A clear, action-oriented name that describes the capability. Good names start with a verb: "Generate Report", "Search Products", "Schedule Meeting", "Review Code". The name should be unambiguous enough that another agent can decide whether this skill matches a task without reading the full description.

2. Description

A 1-3 sentence explanation of what the skill does, including scope and limitations. "Creates a quarterly financial report from accounting data. Accepts a date range and outputs a formatted PDF with charts, tables, and executive summary. Requires read access to the accounting database."

3. Inputs

What the skill needs to execute. For A2A skills, inputs are natural language (described in examples). For MCP tools, inputs are structured (JSON schema). For Claude Code commands, inputs come via the $ARGUMENTS placeholder.

4. Outputs

What the skill produces. A report skill outputs a PDF. A search skill outputs a list of results. A scheduling skill outputs a calendar event. Be specific about the format — "Returns a JSON array of product objects with id, name, price, and description fields."

5. Examples

2-3 example invocations that show how the skill is used in practice. Examples are especially important for A2A skills because agents invoke them with natural language — the examples teach other agents what kind of requests this skill handles.

6. Constraints

Limitations, prerequisites, and boundaries. "Maximum date range: 12 months. Requires accounting:read scope. Processing time: 10-30 seconds for quarterly data." Constraints help orchestrator agents make routing decisions — if a task exceeds a skill's constraints, it should be routed elsewhere.

SKILL.md is an emerging convention for documenting an agent's skills in a structured Markdown file. It sits alongside agents.md and llms.txt as part of the discovery layer. Where agents.md covers how to interact with your site broadly, SKILL.md focuses specifically on the discrete capabilities your agent offers.

Example SKILL.md

# Skills — TaskHub Agent

## generate-report

**Name:** Generate Project Report
**Description:** Creates a comprehensive project status report including task
completion rates, sprint velocity, burndown charts, and team workload
distribution. Output is a formatted Markdown document.

**Inputs:**
- `projectId` (required): The project to report on
- `dateRange` (required): Start and end dates (ISO 8601)
- `includeCharts` (optional, default: true): Whether to include visual charts
- `format` (optional, default: "markdown"): Output format — "markdown" or "pdf"

**Output:** Markdown document or PDF with project metrics, charts, and narrative summary.

**Examples:**
- "Generate a project report for TaskHub-Core from January to March 2026"
- "Create a sprint velocity report for project proj_456, last 6 months, PDF format"

**Constraints:**
- Maximum date range: 12 months
- Requires `projects:read` and `tasks:read` scopes
- Processing time: 5-15 seconds depending on project size
- PDF generation adds 3-5 seconds

---

## search-tasks

**Name:** Search Tasks
**Description:** Natural language search across all tasks in a project or
workspace. Returns ranked results with relevance scores.

**Inputs:**
- `query` (required): Natural language search query
- `projectId` (optional): Scope search to a specific project
- `status` (optional): Filter by task status — "open", "in_progress", "done"
- `limit` (optional, default: 20, max: 50): Number of results

**Output:** JSON array of matching tasks with id, title, status, assignee, and
relevance score.

**Examples:**
- "Find all tasks related to authentication bugs"
- "Search for open tasks assigned to Sarah in the mobile project"

**Constraints:**
- Maximum 50 results per query
- Requires `tasks:read` scope
- Response time: 1-3 seconds

---

## schedule-standup

**Name:** Schedule Team Standup
**Description:** Finds a time slot that works for all team members on a project
and creates a recurring calendar event. Checks availability via connected
calendar integrations.

**Inputs:**
- `projectId` (required): The project whose team to schedule
- `duration` (optional, default: 15): Meeting duration in minutes
- `preferredTime` (optional): Preferred time of day — "morning", "afternoon"
- `recurrence` (optional, default: "daily"): "daily", "weekdays", "mwf"

**Output:** Calendar event details with confirmed time, attendees, and meeting link.

**Examples:**
- "Schedule daily standups for the TaskHub-Core team, 15 minutes, morning preferred"
- "Set up Monday-Wednesday-Friday standups for project proj_789"

**Constraints:**
- Requires calendar integration to be connected for all team members
- Only schedules within business hours (9am-6pm in each member's timezone)
- Maximum team size: 20 members

Google's A2A protocol gives skills the most prominent role of any current framework. In A2A, skills are the primary way agents advertise their capabilities and the primary mechanism other agents use to decide whether to delegate a task.

The Skills Array in agent.json

Every A2A agent publishes an AgentCard at /.well-known/agent.json. The skills array within this card is the machine-readable catalogue of what the agent can do:

{
  "name": "TaskHub Assistant",
  "description": "AI assistant for project management and team productivity",
  "url": "https://taskhub.com/api/agent",
  "version": "2.1.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "authentication": {
    "schemes": ["bearer"]
  },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "skills": [
    {
      "id": "generate-report",
      "name": "Generate Project Report",
      "description": "Creates comprehensive project status reports with metrics, charts, and team analysis. Supports Markdown and PDF output.",
      "tags": ["reporting", "analytics", "project-management"],
      "examples": [
        "Generate a Q1 2026 report for the mobile app project",
        "Create a sprint velocity report for the last 3 months"
      ]
    },
    {
      "id": "search-tasks",
      "name": "Search Tasks",
      "description": "Natural language search across tasks. Finds tasks by keyword, assignee, status, or date range.",
      "tags": ["search", "tasks", "lookup"],
      "examples": [
        "Find open bugs assigned to the backend team",
        "Search for tasks mentioning authentication that were updated this week"
      ]
    },
    {
      "id": "manage-sprint",
      "name": "Manage Sprint",
      "description": "Create, update, and close sprints. Add or remove tasks from sprints. View sprint progress and burndown.",
      "tags": ["sprint", "agile", "planning"],
      "examples": [
        "Create a new 2-week sprint starting Monday for the API team",
        "Move task T-456 to the current sprint"
      ]
    }
  ]
}

How Other Agents Use Skills

When an orchestrator agent receives a complex task, it follows this process:

1. Fetch AgentCards — Retrieve agent.json from known agent URLs or from a registry
2. Match skills to task — Compare the task requirements against available skills using descriptions, tags, and examples
3. Select the best agent — If multiple agents have matching skills, choose based on specificity, reliability, or other criteria
4. Send the task — Use A2A's JSON-RPC protocol to send a tasks/send request with the task described in natural language
5. Receive the result — The agent processes the task using its internal tools and returns an artifact

Writing Effective A2A Skills

The quality of your skill descriptions directly affects whether other agents delegate tasks to your agent. Guidelines:

• Be specific in descriptions. "Generates financial reports" is vague. "Creates quarterly P&L reports from accounting data, including revenue breakdown, expense categories, and year-over-year comparisons" is specific enough for an orchestrator to match.
• Use relevant tags. Tags enable filtering. Include both broad categories ("reporting") and specific domains ("finance", "project-management").
• Provide diverse examples. Show different ways to invoke the skill. Include simple and complex examples. These teach other agents the range of requests your skill handles.
• Define boundaries. If your skill only works for certain data types, time ranges, or team sizes, say so. This prevents failed invocations.

A skill that exists but can't be found is useless. Discoverability is the bridge between building a capable agent and having that agent be useful to the broader ecosystem.

Discovery Channels

Agents discover skills through multiple channels, each serving a different context:

Channel	Format	Best For
A2A AgentCard (.well-known/agent.json)	JSON	Agent-to-agent discovery, registries
MCP manifest (mcp.json)	JSON	Tool-level discovery for MCP clients
agents.md	Markdown	Human-readable skill documentation
SKILL.md	Markdown	Focused skill catalogue
llms.txt	Plain text	Initial site overview mentioning capabilities
Agent registries	Various	Cross-platform agent discovery

Agent Registries

Agent registries are emerging as centralised directories where agents can list their capabilities. Examples include a2aregistry.org for A2A agents, Smithery and mcp.so for MCP servers, and PulseMCP for MCP tool discovery. These registries function like app stores for AI agents — they catalogue agents by category, skill, and protocol, making it easier for orchestrator agents to find the right specialist for a task.

The practical step: register your agent on relevant registries. For an A2A agent, submit your agent.json URL to a2aregistry.org. For MCP servers, submit to Smithery or mcp.so. Each registration makes your agent's skills discoverable to a wider audience.

The Layered Approach

The most discoverable agents use all channels:

1. llms.txt mentions the agent exists and what it can do (10 seconds to understand)
2. agents.md describes skills in detail with interaction guidance (2 minutes to understand)
3. agent.json provides the machine-readable skill catalogue (for other agents)
4. mcp.json provides the machine-readable tool catalogue (for MCP clients)
5. Registry listings make the agent findable outside your domain

Single skills handle single tasks. But most real-world requests require multiple skills working together. "Plan our product launch" might need market research, content creation, scheduling, and analytics — each performed by a different agent with specialised skills.

Sequential Composition

The simplest form: one skill's output becomes the next skill's input. An orchestrator agent breaks the task into ordered steps:

Task: "Generate and distribute the monthly team report"

Step 1: Agent A (generate-report skill)
  Input: "Generate monthly report for Project X, March 2026"
  Output: Formatted report document

Step 2: Agent B (send-email skill)
  Input: Report document + team distribution list
  Output: Confirmation that emails were sent

Step 3: Agent C (post-to-slack skill)
  Input: Report summary + Slack channel
  Output: Confirmation that message was posted

Parallel Composition

When sub-tasks are independent, they can run simultaneously. The orchestrator fans out to multiple agents and collects results:

Task: "Prepare the Q1 business review"

Fan out (parallel):
├── Agent A (financial-report skill): Q1 P&L report
├── Agent B (customer-analytics skill): Q1 customer metrics
├── Agent C (product-metrics skill): Q1 product usage data
└── Agent D (competitor-analysis skill): Q1 market changes

Fan in:
Orchestrator combines all four outputs into a unified Q1 review deck

Conditional Composition

The orchestrator routes to different skills based on intermediate results. "If the report shows declining revenue, invoke the root-cause-analysis skill. If revenue is growing, invoke the growth-forecast skill." This is where skill descriptions become critical — the orchestrator needs enough information to make routing decisions.

The Role of the Orchestrator

Skill composition depends on a capable orchestrator agent — one that can decompose complex tasks, match sub-tasks to available skills, manage execution order, handle failures, and assemble results. This is the core challenge of multi-agent systems: not building individual skills, but building the orchestration layer that combines them effectively.

As organisations deploy more AI agents internally, managing skills becomes a governance challenge. Which agents can do what? Who approved that skill? What data does it access? These questions drive the emerging discipline of enterprise skill management.

Governance Considerations

• Skill approval. Before an agent's skill goes live, it should be reviewed — especially skills that write data, send communications, or access sensitive systems. Treat skill deployment like code deployment: with review, testing, and staged rollout.
• Access control. Not every agent should be able to invoke every skill. Skills that access financial data should require authentication and authorisation. Skills that send emails on behalf of the company need strict controls.
• Versioning. Skills change over time. When a skill's behaviour changes, agents that depend on it need to know. Version your skills (in the A2A AgentCard, this is the card's version field) and document breaking changes.
• Audit logging. Every skill invocation should be logged — who invoked it, what inputs were provided, what output was returned, and when. This is essential for compliance, debugging, and cost tracking.
• Cost tracking. Some skills are expensive (they call external APIs, process large datasets, or use significant compute). Organisations need visibility into which skills are being used, how often, and at what cost.

The Internal Skill Registry

Large organisations are building internal skill registries — catalogues of approved agents and their skills, accessible to the company's orchestrator agents. Think of it as an internal version of a2aregistry.org. Each entry includes the agent URL, its skills, access requirements, the team that maintains it, and its SLA. This centralised catalogue prevents skill duplication and ensures agents discover internal capabilities before reaching for external ones.

Here's a step-by-step approach to adding discoverable skills to your agent.

Step 1: Define Your Core Skills (2-3 to Start)

Don't try to build 20 skills on day one. Identify the 2-3 capabilities that are most valuable and most feasible. For each, write the skill anatomy: name, description, inputs, outputs, examples, constraints. Validate these definitions by asking: "If an AI agent read only this description, could it correctly decide when to use this skill?"

Step 2: Implement the A2A AgentCard

Create .well-known/agent.json with your skills array:

// public/.well-known/agent.json
{
  "name": "Your Agent Name",
  "description": "What your agent does in one sentence",
  "url": "https://yourdomain.com/api/agent",
  "version": "1.0.0",
  "capabilities": { "streaming": false, "pushNotifications": false },
  "authentication": { "schemes": ["bearer"] },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "skills": [
    // Your skills here
  ]
}

Step 3: Build the Agent Endpoint

Create /api/agent that receives A2A task requests and routes them to the appropriate skill handler:

// Simplified A2A endpoint structure
export async function POST(req) {
  const { method, params } = await req.json();

  if (method === "tasks/send") {
    const taskText = params.message.parts[0].text;

    // Route to skill handler based on task content
    const result = await handleTask(taskText);

    return Response.json({
      jsonrpc: "2.0",
      id: params.id,
      result: {
        id: params.id,
        status: { state: "completed" },
        artifacts: [{
          parts: [{ type: "text", text: result }]
        }]
      }
    });
  }
}

Step 4: Add MCP Tools (Optional but Recommended)

If your skills involve discrete operations that benefit from structured invocation, expose them as MCP tools alongside the A2A skills. This makes your capabilities accessible to both A2A agents (natural language) and MCP clients (structured parameters).

Step 5: Document in agents.md and SKILL.md

Write human-readable documentation of your skills. Include everything an AI agent or human developer needs to understand and use your agent's capabilities. Place agents.md in your public directory and optionally create a separate SKILL.md for the focused skill catalogue.

Step 6: Register and Promote

Submit your agent to relevant registries (a2aregistry.org for A2A, Smithery for MCP). Mention your agent's skills in your llms.txt. The more discoverable your skills are, the more useful your agent becomes in the ecosystem.

The current landscape has skills scattered across incompatible formats. A2A skills are JSON in an AgentCard. Claude Code skills are Markdown files in a directory. MCP tools are JSON schemas on a server. Codex tasks are prose in AGENTS.md. Getting them all to work together is the central challenge of the multi-agent future.

What Convergence Looks Like

The direction is toward a world where:

• Any agent can discover any other agent's skills — regardless of platform. An MCP client should be able to find an A2A agent's capabilities, and vice versa.
• Skills are portable. A skill definition written for one platform should work on another with minimal adaptation. The underlying concept is the same; the serialisation format is a solvable problem.
• Skill marketplaces emerge. Just as mobile app stores made it easy to discover applications, skill marketplaces will make it easy to discover agent capabilities. Early versions of this already exist in agent registries.
• Trust and reputation matter. As agents delegate tasks to other agents, they need to evaluate trustworthiness. Did this agent's "generate-report" skill produce accurate results in the past? Reputation systems for agent skills are a natural evolution.
• Skills compose automatically. Advanced orchestrators will decompose complex tasks into skill-matched sub-tasks without human intervention, assembling pipelines of agent capabilities on the fly.

What This Means for Builders Today

The practical implication: define your agent's skills clearly, document them in multiple formats (agent.json, agents.md, mcp.json), and register them in emerging directories. The agents that are well-documented and discoverable today will be the ones that orchestrators route tasks to tomorrow. The agentic web rewards agents that make their capabilities explicit.