Skip to content

Global Skills

Global Skills are managed by administrators and tenant managers to centralize common functionality across multiple assistants. They live independently at the tenant level with configurable visibility (private, shared, or public), allowing you to write once and reuse across assistants while maintaining consistency and simplifying updates.

Creating Global Skills

Using the Forra CLI

The Forra CLI is the recommended way to manage global skills from your development environment.

1. Initialize Your Skill Project

# Initialize a new skill project with scaffolding
forracli functions init -d my_skill
cd my_skill

This creates a project structure with a sample function and skills.json configuration file.

2. Define Your Skills

Edit the skills.json file to define your global skills:

{
  "skills": [
    {
      "id": "crm_integration",
      "name": "Company CRM Integration",
      "description": "Functions for interacting with our CRM system",
      "avatar_path": "avatar.png",
      "package_info": {
        "package_path": "functions",
        "package_file_name": "crm_functions.zip"
      }
    }
  ]
}

Optional Fields: - avatar_path: Path to an image file (relative to skills.json) to use as the skill's avatar. The avatar will be displayed in the UI when viewing or selecting skills.

3. Build Your Skill

Write your functions using the Forra SDK decorators. See the Functions Getting Started guide for details on creating functions.

4. Deploy Your Skills

# Synchronize skills from a configuration file
forracli skills synchronize -f skills.json

This will create or update your global skills in Forra.

Adding Global Skills to Assistants

Once a Global Skill is created, it can be added to any assistant (if the user has permission to view the skill).

Using the UI

  1. Navigate to the assistant's settings
  2. Go to the Skills section
  3. Click Add Global Skill
  4. Select the global skill from the list
  5. Click Add

The assistant will now have access to all functions defined in that global skill.

Managing Global Skills

Listing Global Skills

Use the Forra CLI to list available skills:

forracli skills list

Updating a Global Skill

Update a skill by modifying your skills.json and re-synchronizing:

forracli skills synchronize -f skills.json

Note: When you update a global skill, all assistants using that skill will automatically use the new version.

Variables and Secrets

Global Skills can have their own variables and secrets, which are made available to functions at runtime. This allows you to configure API endpoints, credentials, and other settings without hardcoding them.

Defining Variables and Secrets

Add variables and secrets (or secrets_path) to your skills.json:

{
  "skills": [
    {
      "id": "crm_integration",
      "name": "Company CRM Integration",
      "description": "Functions for interacting with our CRM system",
      "avatar_path": "avatar.png",
      "package_info": {
        "package_path": "functions",
        "package_file_name": "crm_functions.zip"
      },
      "variables": {
        "CRM_API_ENDPOINT": "https://api.crm.example.com",
        "CRM_API_VERSION": "v2"
      },
      "secrets_path": ".secrets.json"
    }
  ]
}

Create a .secrets.json file (add to .gitignore):

{
  "CRM_API_KEY": "your-api-key-here",
  "CRM_WEBHOOK_SECRET": "your-webhook-secret"
}

Alternatively, you can define secrets inline (not recommended for version control):

{
  "skills": [
    {
      "id": "crm_integration",
      "name": "Company CRM Integration",
      "description": "Functions for interacting with our CRM system",
      "avatar_path": "avatar.png",
      "package_info": {
        "package_path": "functions",
        "package_file_name": "crm_functions.zip"
      },
      "variables": {
        "CRM_API_ENDPOINT": "https://api.crm.example.com"
      },
      "secrets": {
        "CRM_API_KEY": "your-api-key-here"
      }
    }
  ]
}

Variable Precedence

When a global skill is used within an assistant, variables are merged with the following precedence (highest wins):

  1. System variables - FORRA_API_URL, etc.
  2. Assistant variables - Variables defined on the assistant
  3. Skill variables - Variables defined on the global skill

This means assistant variables can override skill variables, allowing customization per assistant while maintaining sensible defaults in the skill.

Accessing Variables in Functions

Variables and secrets are available in your functions via the Forra context:

from forrasdk import forra

@forra.function
def get_crm_contacts():
    api_endpoint = forra.context.get("CRM_API_ENDPOINT")
    api_key = forra.context.get("CRM_API_KEY")
    # Use these values in your function

Next Steps