Skills

Skills are on-demand knowledge documents and executable scripts that agents can discover and use at runtime. They extend agent capabilities without bloating the system prompt — agents load only the skills they need, when they need them.

---

Two Types of Skills

Information Skills

Pure markdown documents that teach the agent how to use tools and APIs. The agent calls load_skill to read the instructions, then follows them using its existing tools.

Examples: The built-in web_search, web_scrape, browser, execute_code, and data_analysis skills are all information skills — they document how to use the search, browsr_scrape, start_shell/execute_shell tools that agents already have access to.

Script Skills

Markdown instructions plus attached script files (.py, .js, .ts, .sh). When the agent calls run_skill_script, the script is transferred to a remote shell container and executed with the appropriate interpreter.

Examples: A custom data pipeline skill with a transform.py script, or a web scraper with specialized extract.js logic.

---

How Skills Work

┌─────────────────────────────────────────────────────────┐
│                    Agent Prompt                           │
│                                                           │
│  Available skills:                                        │
│  - web_search (id: abc-123): Search the web...           │
│  - execute_code (id: def-456): Execute code in sandbox...│
│  - my_pipeline (id: ghi-789): Custom data pipeline...    │
│                                                           │
│  Use load_skill to read skill details.                   │
│  Use run_skill_script to execute skill scripts.          │
└─────────────────────────────────────────────────────────┘
         │                              │
         ▼                              ▼
   load_skill(id)              run_skill_script(id, script, input)
         │                              │
         ▼                              ▼
   Returns markdown             Transfers script to shell
   instructions                 container and executes it

1. Discovery — Available skills are listed in the agent's prompt (name + description only)
2. Loading — Agent calls load_skill to get full instructions on demand
3. Execution — For information skills, the agent follows instructions using its tools. For script skills, the agent calls run_skill_script to execute scripts in a remote shell.

---

Enabling Skills on an Agent

Add available_skills to your agent's TOML frontmatter:

All Skills

---
name = "my_agent"
description = "Agent with access to all skills"

[tools]
builtin = ["final", "start_shell", "execute_shell", "stop_shell"]

[[available_skills]]
id = "*"
name = "*"
---

The wildcard * loads all skills from the skill store (system + workspace).

Specific Skills

---
name = "my_agent"
description = "Agent with specific skills"

[tools]
builtin = ["final", "search"]

[[available_skills]]
id = "web_search"
name = "Web Search"

[[available_skills]]
id = "execute_code"
name = "Code Execution"
---

When skills are enabled, two tools are automatically added to the agent:

• load_skill — Load a skill's full content by ID
• run_skill_script — Execute a script from a skill (for script skills)

---

Built-in Skills

Distri ships with 5 system skills that document the built-in tools:

Skill	Type	Documents
web_search	Information	search tool — web search via Browsr API
web_scrape	Information	browsr_scrape and browsr_crawl tools
browser	Information	browsr_browser and browser_step tools
execute_code	Information	start_shell / execute_shell / stop_shell workflow
data_analysis	Information	Composite workflow combining scrape + code execution

These are loaded on demand — they don't add to the system prompt unless the agent explicitly calls load_skill.

---

Creating Custom Skills

Information Skill (Markdown Only)

Create a skill through the API or UI with markdown content:

{
  "name": "my_workflow",
  "description": "Step-by-step guide for a specific workflow",
  "content": "# My Workflow\n\n## Steps\n1. First do X using `search`\n2. Then process with `execute_shell`\n...",
  "tags": ["workflow", "custom"],
  "is_public": false,
  "scripts": []
}

Script Skill (Markdown + Executable Files)

Attach scripts that get executed in a remote shell:

{
  "name": "data_pipeline",
  "description": "Custom data transformation pipeline",
  "content": "# Data Pipeline\n\nTransform and clean data using the attached scripts.\n\n## Scripts\n- **transform**: Clean and normalize input data\n- **analyze**: Run statistical analysis\n\n## Usage\nCall `run_skill_script` with script_name and input data.",
  "tags": ["data", "pipeline"],
  "is_public": false,
  "scripts": [
    {
      "name": "transform",
      "description": "Clean and normalize input data",
      "code": "import json\n\nwith open('/tmp/skill_input.json') as f:\n    data = json.load(f)\n\n# Transform logic here\nresult = [item.strip().lower() for item in data.get('items', [])]\nprint(json.dumps({'cleaned': result}))",
      "language": "python"
    },
    {
      "name": "analyze",
      "description": "Run statistical analysis",
      "code": "import json\nimport statistics\n\nwith open('/tmp/skill_input.json') as f:\n    data = json.load(f)\n\nvalues = data.get('values', [])\nprint(json.dumps({\n    'mean': statistics.mean(values),\n    'median': statistics.median(values),\n    'stdev': statistics.stdev(values) if len(values) > 1 else 0\n}))",
      "language": "python"
    }
  ]
}

---

Script Execution

When run_skill_script is called:

1. A browsr shell session is created
2. The script file is transferred to /workspace/skills/<skill_name>/
3. Input is written to /workspace/skills/<skill_name>/input.json
4. Environment variables are set (e.g., BROWSR_API_KEY)
5. The script runs with the appropriate interpreter
6. stdout/stderr are returned to the agent
7. The session is destroyed

Supported Languages

Language	Extension	Interpreter
Python	.py	python3
JavaScript	.js	node
TypeScript	.ts	npx tsx
Bash	.sh	bash
Ruby	.rb	ruby

Reading Input in Scripts

Scripts receive input as a JSON file at /tmp/skill_input.json:

Python

import json

with open('/tmp/skill_input.json') as f:
    input_data = json.load(f)

# Use input_data...
print(json.dumps({"result": "done"}))

JavaScript

const fs = require('fs');
const input = JSON.parse(fs.readFileSync('/tmp/skill_input.json', 'utf-8'));

// Use input...
console.log(JSON.stringify({ result: "done" }));

TypeScript

import * as fs from 'fs';

interface Input {
  query: string;
}

const input: Input = JSON.parse(fs.readFileSync('/tmp/skill_input.json', 'utf-8'));
console.log(JSON.stringify({ result: input.query.toUpperCase() }));

---

Skills API

List Skills

GET /v1/skills

Returns all skills visible to the current workspace (own + system + public).

Get Skill

GET /v1/skills/{skill_id}

Returns the full skill record including content and scripts.

Create Skill

POST /v1/skills
Content-Type: application/json

{
  "name": "my_skill",
  "description": "What this skill does",
  "content": "# Markdown content...",
  "tags": ["custom"],
  "is_public": false,
  "scripts": []
}

Run Script

POST /v1/skills/{skill_id}/scripts/{script_id}/run
Content-Type: application/json

{
  "input": { "key": "value" }
}

---

A2A Skills (Agent Discovery)

Skills also serve as A2A (Agent-to-Agent) protocol descriptors for agent discovery. Add [[skills]] to your agent's frontmatter to declare what capabilities your agent exposes:

[[skills]]
id = "web_search"
name = "Web Search"
description = "Search the web for current information on any topic"
tags = ["search", "research"]
examples = ["Find the latest news about AI regulations"]

These are exposed via the Agent Card endpoint (GET /agents/{id}/.well-known/agent.json) for other agents and systems to discover your agent's capabilities.

Property	Type	Required	Description
id	string	Yes	Unique identifier for the skill
name	string	Yes	Human-readable skill name
description	string	Yes	What the skill does
tags	string[]	No	Categorization tags
examples	string[]	No	Example prompts

---

Best Practices

• Information skills first — If the agent already has tools for the job, write an information skill documenting their usage instead of creating script wrappers
• Keep scripts focused — Each script should do one thing well. Use multiple scripts within a skill for multi-step workflows
• Read input from file — Always read from /tmp/skill_input.json, not stdin
• Print JSON output — Scripts should print JSON to stdout for structured results
• Handle errors — Print error details to stderr or as JSON with an error field
• Use system skills as templates — Look at the built-in skills for patterns to follow

---

References

• Agent Definition — Full agent configuration reference
• Managing Agents — Push and manage agents on Distri Cloud