Skip to content

Building Skills & Tools

Skills are how your application exposes custom tools and business logic to the LLM.

All skills placed in the directory pointed to by [app] skills in chakra.toml (e.g. myapp.skills) are automatically discovered and loaded when the engine boots.


Skill Architecture

A skill is a Python package containing a subclass of BaseSkill and exposing methods decorated with @function_tool.

myapp/
└── skills/
    └── weather/
        ├── __init__.py
        └── tool.py          # Implements BaseSkill

Writing a Skill

Here is a complete example of a skill that fetches localized agricultural weather data:

# myapp/skills/weather/tool.py
from typing import Annotated
from chakra_convai import BaseSkill, function_tool, tool_description, logger, get_db_pool

class WeatherSkill(BaseSkill):
    def __init__(self):
        super().__init__()
        self.logger = logger.getChild("skills.weather")

    @function_tool(description=tool_description("get_weather"))
    async def get_weather(
        self,
        district: Annotated[str, "The Sri Lankan administrative district (e.g., Kandy, Anuradhapura)"],
    ) -> str:
        """Fetches the 24-hour agricultural weather forecast for a given district."""
        self.logger.info("Fetching forecast for district: %s", district)

        # Access the application's PostgreSQL connection pool
        pool = get_db_pool()
        if pool:
            async with pool.acquire() as conn:
                record = await conn.fetchrow(
                    "SELECT forecast, rainfall_mm FROM weather_cache WHERE district = $1",
                    district
                )
                if record:
                    return f"Forecast for {district}: {record['forecast']} with {record['rainfall_mm']}mm expected rain."

        return f"Normal seasonal conditions reported across {district}."

Key APIs for Skills

@function_tool

The standard LiveKit tool decorator. Decorates async or sync methods to expose them to the model.

tool_description(tool_name: str)

Extracts the tool description directly from config/instructions.json using the active session language. This ensures the model receives tool descriptions in the caller's target language without hardcoding prompts in Python.

get_db_pool()

Retrieves the active asyncpg PostgreSQL connection pool initialized by the engine. You can use this pool to query your own application-specific database tables.

Logging

Use logger from chakra_convai to write formatted, tracing-aware log messages.