AI Agent Skills

What is it

A skill is an atomic, reusable capability that an AI agent can invoke to perform a concrete action. It acts as a bridge between the language model and external systems: APIs, databases, code execution, files, or any other digital resource. Each skill has a name, a semantic description, and an implementation that the agent runs when it determines the tool is the right fit for the task.

The model does not execute the skill directly. The agent identifies which skill matches the user's intent, gathers the required parameters, and hands control to the implementation. The result flows back to the model so it can continue the conversation.

Mental model

Think of a skill as a well-documented function the agent can "call" when needed.

User ⟶ Agent ⟶ selects skill ⟶ runs implementation ⟶ result ⟶ agent ⟶ response

Each skill is described with a short name and a text that explains what it does and when to use it. That description is the only signal the model sees to make a decision. The quality of that description determines whether the agent picks the right skill.

An agent may have anywhere from one skill to dozens. The more skills it has, the more critical it becomes that names and descriptions are precise and do not overlap. When two skills compete for the same use case, the agent may choose the wrong one.

How it's used

A skill is defined with three parts:

1. Name: short identifier, in snake_case or camelCase.
2. Description: natural language text explaining the purpose and when to use it.
3. Implementation: the function that executes the action (call an API, query a database, run code, etc.).

In practice, skills are declared as an array or dictionary passed to the agent at initialization. For example, in a framework like LangChain or Vercel AI SDK:

skills = [
    {
        "name": "search_flights",
        "description": "Searches available flights between two cities on a given date. Useful when the user requests flight options.",
        "parameters": {
            "origin": "string",
            "destination": "string",
            "date": "string"
        },
        "implementation": search_flights_api
    }
]

The agent receives these definitions at runtime. When the user makes a request, the model decides whether any skill is relevant. If so, it returns a structured object with the skill name and parameters. The agent runtime executes the function and feeds the result back to the model.

When to use it / when not to

Use skills when the agent needs to do something the model alone cannot: read live data, write to a system, calculate with precision, or access private information. Every time the agent must step outside its purely textual context, you need a skill.

Do not use skills for actions the model can handle from its internal knowledge (answering conceptual questions, summarizing text, translating). Also avoid overly granular skills: if a skill only applies in a marginal scenario, the noise it adds may cause the agent to make more mistakes.

A common mistake is defining skills with vague or overlapping descriptions. When two skills describe similar use cases, the model will hesitate between them. Clarity in the description matters just as much as the implementation itself.