add_skill

Add skills to OpenViking for agent capabilities

Overview

Add skills to OpenViking to extend agent capabilities. Skills can be provided as directories, files, strings, or structured data.

Skills are different from resources. Skills define agent capabilities (tools, actions, workflows), while resources contain knowledge (documents, code, media).

Method Signature

Python SDK

client.add_skill(
    data: Any,
    wait: bool = False,
    timeout: Optional[float] = None
) -> Dict[str, Any]

Parameters

data · any · required

Skill data in one of the following formats:

• Directory path: Path to a directory containing skill definition
• File path: Path to a skill file (Python, JSON, YAML)
• String: Skill definition as a string
• Dictionary: Structured skill data

wait · boolean · default: "false"

Wait for vectorization and processing to complete before returning

timeout · float

Timeout in seconds when wait=True

Response

status · string · required

Either “success” or “error”

skill_uri · string

Viking URI where the skill was stored (e.g., viking://skills/my-skill/)

errors · array

List of errors encountered during processing (if any)

queue_status · object

Queue processing status (only present when wait=True)

Show queue_status properties

processed · integer

Number of items processed

error_count · integer

Number of errors encountered

errors · array

List of error messages

Examples

Add Skill from Directory

Python SDK

import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

result = client.add_skill(
    "./skills/web-search",
    wait=True
)
print(f"Skill added: {result['skill_uri']}")

Add Skill from File

Python SDK

result = client.add_skill(
    "./skills/calculator.py",
    wait=True
)

Add Skill from Dictionary

Python SDK

skill_definition = {
    "name": "code_analyzer",
    "description": "Analyze code quality and complexity",
    "functions": [
        {
            "name": "analyze_complexity",
            "description": "Calculate cyclomatic complexity",
            "parameters": {
                "code": {"type": "string", "description": "Source code to analyze"}
            }
        }
    ]
}

result = client.add_skill(skill_definition, wait=True)

Add Multiple Skills

Python SDK

# Add multiple skills without waiting
skills = [
    "./skills/web-search",
    "./skills/calculator",
    "./skills/file-ops"
]

for skill in skills:
    client.add_skill(skill, wait=False)

# Wait for all to complete
status = client.wait_processed()
print(f"All skills processed: {status}")

Response Example

Success Response

{
  "status": "ok",
  "result": {
    "status": "success",
    "skill_uri": "viking://skills/web-search/",
    "errors": [],
    "queue_status": {
      "semantic_queue": {
        "processed": 5,
        "error_count": 0,
        "errors": []
      },
      "vector_queue": {
        "processed": 5,
        "error_count": 0,
        "errors": []
      }
    }
  },
  "time": 0.3
}

Skill Structure

A typical skill directory structure:

skills/web-search/
├── skill.yaml          # Skill metadata and configuration
├── functions.py        # Skill implementation
├── requirements.txt    # Dependencies
└── README.md          # Documentation

skill.yaml Example

name: web_search
description: Search the web for information
version: 1.0.0

functions:
  - name: search
    description: Perform a web search
    parameters:
      query:
        type: string
        description: Search query
        required: true
      max_results:
        type: integer
        description: Maximum number of results
        default: 10

Processing

When you add a skill:

1. Validation: Skill structure and syntax are validated
2. Storage: Skill is stored in viking://skills/ scope
3. Indexing: Skill documentation is indexed for semantic search
4. Registration: Skill becomes available to agents

Use wait=True to ensure the skill is fully processed before agents try to use it.

Related Methods

• wait_processed - Wait for async processing
• add_resource - Add resources instead of skills
• ls - List added skills at viking://skills/