🎯 Agent Skills & Capabilities

While a tool is a discrete interface to the outside world (like a single API call or function: search_db(query)), a skill is a higher-level, composed capability that enables an agent to perform complex multi-step workflows.

Understanding how to design, package, and orchestrate agent skills is crucial for building production-ready systems.

⚖️ Tools vs. Skills vs. Agents

It helps to think of these components on a spectrum of abstraction and autonomy:

📂 Common Agent Skill Categories

To perform useful tasks, modern agents generally require a mix of the following skill categories:

1. 📖 Information Retrieval & Synthesis

• Web Search & Summarization: Finding relevant information across search engines and consolidating it.
• RAG & Vector Lookups: Querying internal document stores and databases.
• Knowledge Graph Traversal: Querying relational or graph schemas to find entity connections.

2. 💻 Code & Execution Capabilities

• Code Generation: Generating scripts dynamically (e.g., Python, SQL).
• Execution Sandboxing: Running generated code safely to check output or process data.
• Error Diagnostics: Reading error logs and auto-correcting syntax or execution errors.

3. 🗂️ Workflow & Productivity Actions

• API Orchestration: Calling external services like Jira, Linear, Slack, or Stripe.
• Calendar & Scheduling: Negotiating times and booking meetings.
• File System Operations: Creating, parsing (PDFs/spreadsheets), and managing files.

🛠️ How to Design Skills for Your Agent

When building agentic skills, follow these three core development principles:

1. Define Explicit Skill Scopes

The reasoning engine (LLM) relies on the docstrings and descriptions to decide when and how to invoke a skill. Keep them specific and avoid generic functions.

# ✅ Good: Explicit purpose and clear types
def search_and_summarize_web(query: str, max_results: int = 5) -> str:
    """
    Searches the live web for a query and summarizes the top search results.
    Use this when the user asks about recent news, current events, or real-time data.
    """
    raw_results = web_search_api(query, limit=max_results)
    return summarize_content(raw_results)
 
# ❌ Bad: Vague purpose, prone to LLM invocation errors
def do_stuff(input_data: str) -> str:
    """Processes the input data and does stuff."""
    ...

2. Craft High-Quality Tool & Parameter Descriptions

When registering tools with frameworks (e.g., OpenAI Tool Calling, Anthropic Tools), specify parameters clearly:

{
    "name": "get_weather",
    "description": "Retrieve the current weather and forecast for a given city. Use this ONLY when the user asks about current conditions or forecasts.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "The city name, e.g., 'San Francisco' or 'New York'."
            },
            "days": {
                "type": "integer",
                "description": "Number of days for forecast. Must be between 1 and 5."
            }
        },
        "required": ["city"]
    }
}

3. Implement Skill Chaining

A skill often requires running a sequence of steps. Encapsulating this sequence in a single function reduces LLM reasoning overhead and makes execution much faster and more reliable.

User: "Find the developer advocate for project X and draft a cold email"

Agent plan (Chained Skill):
1. [Search Skill] → Queries directory for "developer advocate project X"
2. [Extraction Skill] → Parses profile to find contact info
3. [Email Draft Skill] → Writes copy personalized to their projects

🛡️ Skill Reliability Patterns

Production agents fail when tools fail. Implement these patterns to guarantee reliability: