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.
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.