Skills Guide

Skills in Clara encapsulate cognitive domains and automated agent capabilities. Each skill packages intent recognition, prompt engineering templates, safety policies, and tool execution routines.

Skill Directory Structure

Every Clara skill is organized within its own subpackage under clara/skills/:

clara/skills/email_assistant/
├── __init__.py         # Public exports (Workflows and helpers)
├── skill.yaml          # Declarative metadata, trigger keywords, and tool schemas
├── prompt.md           # System prompt templates, persona, and cognitive rules
└── workflows.py        # Python workflow coordinator and intent dispatcher

1. Skill Manifest (skill.yaml)

The skill.yaml file declaratively defines how Clara discovers, activates, and provisions tools for a skill:

name: email_assistant
version: "0.1.0"
display_name: "Email Assistant"
description: "AI-powered email management assistant for Gmail."
category: "Productivity"

# Keyword triggers used for fast intent routing
triggers:
  - "email"
  - "gmail"
  - "inbox"
  - "send email"
  - "draft email"

# External connections required by this skill
connections:
  - service: google
    name: gmail
    required_scopes:
      - "https://www.googleapis.com/auth/gmail.readonly"
      - "https://www.googleapis.com/auth/gmail.send"
      - "https://www.googleapis.com/auth/gmail.modify"

# Callable tools exposed by the skill to LLM function calling
tools:
  - name: send_email
    description: "Send an email to one or more recipients."
    parameters:
      to:
        type: string
        required: true
      subject:
        type: string
        required: true
      body:
        type: string
        required: true

2. Prompt Template (prompt.md)

prompt.md provides domain-specific instructions to guide LLM reasoning:

  • Persona: Defines Clara’s role and tone (e.g. executive assistant).

  • The Cognitive CRUD Loop: Directs the model to parse intents, extract parameters, check ambiguity, execute tools, and format output.

  • Safety Guardrails: Enforces rules like mandatory confirmation for destructive operations or batch actions.

3. Workflow Implementation (workflows.py)

Workflows coordinate between incoming prompts and connection tools.

from typing import Dict, Any, Optional
from clara.connections.registry import registry

class CustomSkillWorkflow:
    """Example custom workflow implementation."""

    def __init__(self, access_token: Optional[str] = None):
        self.access_token = access_token

    def execute(self, user_prompt: str, context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
        # 1. Parse intent and arguments
        # 2. Check safety guardrails
        # 3. Invoke connection tools
        # 4. Return structured response
        return {
            "status": "success",
            "action": "custom_action",
            "reply": f"Completed task: {user_prompt}",
            "data": {}
        }

Creating a New Skill: Step-by-Step

  1. Create a directory clara/skills/my_skill/.

  2. Define skill.yaml with your skill’s triggers and tools.

  3. Write prompt.md containing prompt definitions.

  4. Implement workflows.py inheriting your business logic.

  5. Export your workflow in clara/skills/__init__.py.