Skip to main content
Agent skills is a simple, open format for giving agents new capabilities and expertise. Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently Acontext provides pre-built skill tools that allow LLMs to access reusable knowledge bundles (skills) through function calling. Skills contain files, scripts, and instructions that help agents perform specialized tasks.

​
Available Tools

The SDK includes three skill operation tools:
  • list_skills - List all available skills in the current context
  • get_skill - Get skill metadata including file index
  • get_skill_file - Read a specific file from a skill
Skills are preloaded by UUID when creating the context, then accessed by human-readable name. This allows LLMs to work with meaningful skill names instead of UUIDs.

​
Building an Agent with Skills

You can build an agentic loop where the LLM autonomously accesses skills to retrieve knowledge and instructions. Here’s a complete example: 
import json
import os
from acontext import AcontextClient
from acontext.agent.skill import SKILL_TOOLS
from openai import OpenAI

# Initialize clients
acontext_client = AcontextClient(
    api_key=os.getenv("ACONTEXT_API_KEY"),
)

# If you're using self-hosted Acontext:
# acontext_client = AcontextClient(
#     base_url="http://localhost:8029/api/v1",
#     api_key="sk-ac-your-root-api-bearer-token",
# )
openai_client = OpenAI()

# Preload skills by UUID and create tool context
# The context maps skill names to skill objects for easy lookup
skill_ids = ["uuid-of-skill-1", "uuid-of-skill-2"]
ctx = SKILL_TOOLS.format_context(acontext_client, skill_ids)

# Get tool schemas for OpenAI
tools = SKILL_TOOLS.to_openai_tool_schema()

# Simple agentic loop
messages = [
    {
        "role": "user",
        "content": "List the available skills, then read the SKILL.md from the data-extraction skill",
    }
]

while True:
    response = openai_client.chat.completions.create(
        model="gpt-4.1",
        messages=messages,
        tools=tools,
    )

    message = response.choices[0].message
    messages.append(message)

    # Break if no tool calls
    if not message.tool_calls:
        print(f"🤖 Assistant: {message.content}")
        break

    # Execute each tool call
    for tool_call in message.tool_calls:
        print(f"⚙️ Called {tool_call.function.name}")
        result = SKILL_TOOLS.execute_tool(
            ctx, tool_call.function.name, json.loads(tool_call.function.arguments)
        )
        print(f"🔍 Result: {result}")
        messages.append(
            {"role": "tool", "tool_call_id": tool_call.id, "content": result}
        )
The agent will automatically call the appropriate tools (list_skills, get_skill, get_skill_file) to explore and retrieve knowledge from skills.

​
How It Works

1

Initialize clients and preload skills

Set up both the Acontext client and your LLM client (OpenAI or Anthropic). Preload skills by their UUIDs to create the context.
import os
from acontext import AcontextClient
from acontext.agent.skill import SKILL_TOOLS

client = AcontextClient(
    api_key=os.getenv("ACONTEXT_API_KEY"),
)

# If you're using self-hosted Acontext:
# client = AcontextClient(
#     base_url="http://localhost:8029/api/v1",
#     api_key="sk-ac-your-root-api-bearer-token",
# )

# Preload skills by UUID - they'll be accessible by name
skill_ids = ["uuid-of-skill-1", "uuid-of-skill-2"]
ctx = SKILL_TOOLS.format_context(client, skill_ids)
The context preloads skill metadata and creates a name-to-skill mapping. This allows LLMs to reference skills by their human-readable names instead of UUIDs.
2

Get tool schemas for your LLM

Convert the skill tools to the schema format your LLM provider expects.
# For OpenAI
tools = SKILL_TOOLS.to_openai_tool_schema()

# For Anthropic
tools = SKILL_TOOLS.to_anthropic_tool_schema()
3

Implement the agentic loop

Create a loop that executes tool calls and feeds results back until the task is complete.Executing Tools After LLM Response:When the LLM responds with tool calls, iterate through each one and execute them using SKILL_TOOLS.execute_tool() (Python) or SKILL_TOOLS.executeTool() (TypeScript):
# Execute each tool call from the LLM response
for tool_call in message.tool_calls:
    result = SKILL_TOOLS.execute_tool(
        ctx,                                      # Tool context with preloaded skills
        tool_call.function.name,                  # Tool name (e.g., "get_skill")
        json.loads(tool_call.function.arguments)  # Parse arguments
    )
    # Add tool result back to message history
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": result
    })
The loop continues until the LLM returns a message without tool calls, indicating the task is complete.

​
Tool Reference

​
list_skills

List all available skills in the current context with their names and descriptions. Parameters: None Returns: List of skill names and descriptions Example Output: 
Available skills (2):
- data-extraction: Extract structured data from documents
- code-review: Review code for best practices and security issues

​
get_skill

Get detailed information about a skill by its name. Parameters:
  • skill_name (required) - The name of the skill
Returns: Skill metadata including ID, description, and file index with MIME types Example Output: 
Skill: data-extraction (ID: abc123-...)
Description: Extract structured data from documents
Files: 3 file(s)
  - SKILL.md (text/markdown)
  - scripts/extract.py (text/x-python)
  - templates/output.json (application/json)

​
get_skill_file

Read the contents of a specific file from a skill. Parameters:
  • skill_name (required) - The name of the skill
  • file_path (required) - Relative path to the file within the skill (e.g., "SKILL.md" or "scripts/extract.py")
  • expire (optional) - URL expiration time in seconds for non-parseable files (defaults to 900)
Returns: File content for text files, or a presigned download URL for binary files
Start by reading SKILL.md - this file contains an overview of the skill’s purpose, capabilities, and usage instructions.

​
Skill Context Architecture

The skill tools use a preloading pattern that differs from disk tools:
1

Preload by UUID

When creating the context, you provide a list of skill UUIDs. The SDK fetches each skill’s metadata from the API.
2

Map by Name

Skills are stored in a name-to-skill mapping. This allows LLMs to reference skills using meaningful names like "data-extraction" instead of UUIDs.
3

Access by Name

All tool calls use skill_name parameter. The context automatically resolves names to the full skill objects.
Each skill must have a unique name within the context. If you preload two skills with the same name, a ValueError (Python) or Error (TypeScript) will be thrown.
Read-Only Access: These skill tools can only load and read skill content (text-based file like markdown, code…). They cannot execute code scripts or run any executable files contained within a skill.