SkillDefinition

A loadable skill pack that adds capabilities to an agent.

Usage

SkillDefinition(
    name,
    display_name,
    category,
    description,
    instructions="",
    constraints=list(),
    tools=list(),
    tags=list(),
    metadata=dict()
)

A skill bundles instructions, constraints, tools, and context that can be attached to any Agent or ChatBot to grant it domain-specific capabilities without modifying the agent’s persona.

Parameters

name: str: Machine-readable identifier (e.g., "sql_analysis").
display_name: str: Human-readable name (e.g., "SQL Analysis").
category: str: Grouping category (e.g., "data", "engineering", "writing").
description: str: One-line description of what this skill enables.
instructions: str = "": Detailed instructions appended to the system prompt when the skill is active. This is the core of the skill — it tells the agent how to perform the capability.
constraints: list[str] = list(): Constraints the agent must follow when this skill is active.
tools: list[str] = list(): Tool names the skill requires or recommends.
tags: list[str] = list(): Free-form tags for filtering and discovery.
metadata: dict[str, Any] = dict(): Arbitrary metadata (e.g., version, author).

Examples

Create a skill programmatically:

import talk_box as tb

skill = tb.create_skill(
    "code_review",
    description="Review code for quality and security issues",
    instructions="Analyze code for bugs, security issues, and style. "
                 "Prioritize: security > correctness > performance > style.",
    constraints=["Always explain the 'why' behind suggestions"],
    tools=["file_reader"],
)
skill.name  # "code_review"

tb.register_skill(skill)
tb.get_skill("code_review")  # same skill
tb.list_skills()             # ["code_review"]