DocsSkillsSkills Overview

Skills Overview

Skills are drop-in tool extensions for Ryvos. Write a script in Lua or Rhai, describe it in a TOML manifest, and drop it in ~/.ryvos/skills/. Ryvos discovers and loads skills automatically on startup.

How Skills Work

  1. Ryvos scans ~/.ryvos/skills/ for subdirectories containing skill.toml
  2. Each manifest declares the tool name, description, language, input schema, and security tier
  3. Prerequisites are checked (env vars, OS)
  4. Valid skills are registered in the ToolRegistry alongside built-in tools
  5. The LLM can call skills like any other tool

Directory Structure

~/.ryvos/skills/
├── weather_lookup/
│   ├── skill.toml          # Manifest
│   └── weather.lua         # Implementation (Lua)
├── screenshot/
│   ├── skill.toml
│   └── capture.rhai        # Implementation (Rhai)
└── translate/
    ├── skill.toml
    └── translate.lua

Skill Manifest

name = "weather_lookup"
description = "Look up current weather for a city"
language = "lua"
entrypoint = "weather.lua"
timeout_secs = 15
tier = "t1"
 
input_schema_json = '''
{
  "type": "object",
  "properties": {
    "city": { "type": "string", "description": "City name" }
  },
  "required": ["city"]
}
'''
 
[prerequisites]
required_env = ["WEATHER_API_KEY"]

Execution Model

Skills run inside an embedded scripting runtime (Lua via mlua, or Rhai) within the Ryvos process. There is no subprocess spawning — scripts execute in a sandboxed interpreter with access only to the input data and a curated set of host functions.

When the LLM calls a skill:

  1. Ryvos deserializes the JSON input into a script-accessible table/map
  2. The embedded runtime executes the entrypoint function
  3. The return value is serialized back to JSON as the tool result
  4. Errors are caught and reported to the agent for retry

Security

Skills are classified by their declared tier:

  • They pass through the same SecurityGate as built-in tools
  • The embedded runtime is sandboxed — no arbitrary filesystem or network access
  • Approval flow works normally based on tier

Discovery

Ryvos logs skill discovery on startup:

[INFO] Loaded 3 skills: weather_lookup (lua), screenshot (rhai), translate (lua)
[WARN] Skipping skill "broken_tool": missing env var: API_KEY

Next Steps

See Creating Skills for a step-by-step guide.

SSE TransportCreating Skills