Skip to main content

How to Use Skills

In this guide, we will explore how to enable your agents to use skills. Skills provide a way to progressively disclose specialized instructions to agents, loading detailed guidance only when needed. This approach reduces token usage while maintaining the agent's ability to handle complex, specialized tasks.

Prerequisites​

Before you begin, make sure you have completed the Getting Started with the Agents SDK tutorial and the How to Configure Agents guide. You should also be familiar with How to Create Agents that Use Tools.

Understanding Skills​

Skills follow the Agent Skills protocol, which enables progressive disclosure of agent capabilities:

  1. Level 0 - Catalog: At startup, the agent only sees skill names and descriptions (~100 tokens per skill)
  2. Level 1 - Instructions: When the agent activates a skill, it receives the full instructions
  3. Level 2 - Resources: Additional files (examples, templates) can be loaded on-demand

This approach is more efficient than loading all instructions upfront, especially when an agent has access to many specialized capabilities.

Step 1: Get Example Skills​

Clone the official Anthropic skills repository to get started with pre-built skills:

git clone https://github.com/anthropics/skills.git
cp -r skills/skills agents/skills

This gives you a collection of ready-to-use skills. You can also create your own skills following the Agent Skills specification.

Step 2: Register SkillsProvider in Your Agent​

Update your agent code to accept a SkillsProvider dependency and load skills at runtime:

from typing import AsyncGenerator, List
from zav.agents_sdk import ChatAgentClassRegistry, ChatMessage, StreamableChatAgent
from zav.agents_sdk.adapters import SkillsProvider, ZAVChatCompletionClient

SYSTEM_PROMPT = """You are a helpful AI assistant with access to specialized skills.

SKILLS
- You have access to skills that provide detailed instructions for specialized tasks.
- When a task matches an available skill, use the `use_skill` tool to load it.
- Follow the skill instructions carefully once loaded.

GENERAL BEHAVIOR
- Be accurate, clear, and efficient.
- Prefer concrete, actionable answers over vague advice."""


@ChatAgentClassRegistry.register()
class ChatAgent(StreamableChatAgent):
    agent_name = "chat_agent"

    def __init__(
        self,
        client: ZAVChatCompletionClient,
        skills_provider: SkillsProvider,
    ):
        self.client = client
        self.skills_provider = skills_provider

    async def execute_streaming(
        self,
        conversation: List[ChatMessage],
    ) -> AsyncGenerator[ChatMessage, None]:
        # Register skill tools
        self.tools_registry.extend(await self.skills_provider.get_tools())

        response = await self.client.complete(
            bot_setup_description=SYSTEM_PROMPT,
            messages=conversation,
            tools=self.tools_registry,
            stream=True,
            execute_tools=True,
        )
        async for chat_client_response in response:
            if chat_client_response.error is not None:
                raise chat_client_response.error
            if chat_client_response.chat_completion is None:
                raise Exception("No response from chat completion client")

            yield ChatMessage.from_orm(chat_client_response.chat_completion)

Step 4: Configure Skills in agent_setups.json​

Add the skills configuration to your agent setup:

agent_setups.json
[
  {
    "agent_identifier": "chat_agent",
    "agent_name": "chat_agent",
    "llm_client_configuration": {
      "vendor": "openai",
      "vendor_configuration": {},
      "model_configuration": {
        "name": "gpt-5.2",
        "type": "chat",
        "temperature": 0.0
      }
    },
    "agent_configuration": {
      "skills_configuration": {
        "skills_directories": ["./agents/skills"],
        "injection_mode": "tools"
      }
    }
  }
]

How the agent loads other files in the skills directory​

Skills can include additional resource files (examples, templates, reference data) that the agent can load on-demand using the read_skill_resource tool.

agents/skills/analyze-document/
├── SKILL.md
└── examples/
    ├── financial-report.md
    └── technical-spec.md

When the agent activates this skill, it will see:

**Available Resources**: examples/financial-report.md, examples/technical-spec.md

Use `read_skill_resource` tool to load any of these files.

The agent can then call read_skill_resource(skill_name="analyze-document", resource_path="examples/financial-report.md") to load the example.

Security

Resource paths are validated against a whitelist created during skill discovery. Only files within the skill directory can be loaded - path traversal attacks (e.g., ../../etc/passwd) are blocked.

Schema of skills_configuration

Below is the JSON schema for the skills_configuration block in agent_setups.json.

{
  "skills_directories": [string, ...],
  "prompt_format": "xml" | "text",
  "include_location_in_prompt": boolean,
  "injection_mode": "prompt" | "tools" | "both"
}

Fields​

  • skills_directories: List of directories to scan for skills. Each subdirectory containing a SKILL.md file is treated as a skill.
  • prompt_format ("xml" or "text", default: "text"): Format for the skill catalog in the system prompt.
    • "text": Uses markdown formatting
    • "xml": Uses XML tags (recommended for Claude/Anthropic models)
  • include_location_in_prompt (default: false): If true, includes file paths in the skill catalog. Useful for agents with filesystem access.
  • injection_mode ("prompt", "tools", or "both", default: "both"): Where to inject skill information.
    • "prompt": Skills listed in system prompt only, no tools registered
    • "tools": Skills available via use_skill tool only, not in system prompt
    • "both": Skills appear in both system prompt AND as tools

Prompt Format Examples​

Text format (default):

Available Skills:

- **summarize-slack**: Summarize Slack messages over a time period.
- **analyze-document**: Analyze documents and extract key information.

To use a skill, call the `use_skill` tool with the skill name.

XML format:

<available_skills>
<skill>
<name>summarize-slack</name>
<description>Summarize Slack messages over a time period.</description>
</skill>
<skill>
<name>analyze-document</name>
<description>Analyze documents and extract key information.</description>
</skill>
</available_skills>
info

For more details on the Agent Skills protocol, visit agentskills.io.