Skip to main content

​
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

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)

​
Examples

​
Add Skill from Directory

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

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

​
Add Skill from Dictionary

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

# 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

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