Skills

Skills are on-demand knowledge documents 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. Skills are markdown files with TOML frontmatter, managed via the distri skills push CLI command.

---

Execution Modes

Every skill runs in one of two execution modes, configured via the context field:

Inline (Default)

The skill's markdown content is injected directly into the agent's conversation context. The agent reads the instructions and acts on them using its existing tools. This is the most common mode — lightweight and immediate.

Agent conversation
  │
  ├── [user message]
  ├── [assistant calls load_skill("web_search")]
  ├── [skill content injected into conversation]  ← inline
  └── [assistant follows instructions using its tools]

Fork

The skill spawns an isolated child agent to handle the task. The child agent runs with its own conversation context, executes the skill instructions independently, and returns results to the parent agent. Use fork mode for complex, multi-step skills that benefit from isolation.

Parent agent conversation
  │
  ├── [user message]
  ├── [assistant calls load_skill("complex_pipeline")]
  ├── [child agent spawned]  ← fork
  │     ├── [skill content as child's system prompt]
  │     ├── [child executes independently]
  │     └── [results returned to parent]
  └── [parent continues with results]

---

How Skills Work

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 — In inline mode, the skill content is injected into the conversation and the agent follows the instructions. In fork mode, a child agent is spawned to execute the skill in isolation.

Post-Compaction Re-injection

Skills survive conversation compaction. The ActiveSkillTracker monitors which skills are currently loaded and preserves them as first-class SkillContext entries. When a long conversation is compacted to save context space, loaded skill content is automatically re-injected so the agent never loses access to active skill instructions.

---

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, the load_skill tool is automatically added to the agent, allowing it to load any available skill's content by ID.

---

Built-in Skills

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

Skill	Documents
web_search	search tool — web search via Browsr API
web_scrape	browsr_scrape and browsr_crawl tools
browser	browsr_browser and browser_step tools
execute_code	start_shell / execute_shell / stop_shell workflow
data_analysis	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

Skills are markdown files with TOML frontmatter. Create a .md file, then push it with the CLI.

Skill File Format

---
name = "my_skill"
description = "What this skill does"
tags = ["tag1", "tag2"]
is_public = false
model = "gpt-5.4"       # optional model override
context = "inline"       # "inline" (default) or "fork"
---

# Skill Content

Your markdown instructions here. This is what gets injected into the
agent's conversation when the skill is loaded.

## Steps

1. First do X using the `search` tool
2. Then process results with `execute_shell`
3. Return structured output to the user

Frontmatter Fields

Field	Type	Required	Default	Description
name	string	Yes	—	Unique skill identifier
description	string	Yes	—	Short description shown in skill discovery
tags	string[]	No	[]	Categorization tags
is_public	bool	No	false	Whether the skill is visible to other workspaces
model	string	No	—	Model override for fork mode
context	string	No	"inline"	Execution mode: "inline" or "fork"

Pushing Skills

Use the distri CLI to push skill files to Distri Cloud:

Push a Skill

distri skills push my_skill.md

List Skills

distri skills list

---

Skills API

List Skills

GET /v1/skills
GET /v1/skills?include_public=true

Returns skills visible to the current workspace. By default returns workspace-only skills. Pass include_public=true to also include public skills from other workspaces.

Get Skill

GET /v1/skills/{skill_id}

Returns the full skill record including content.

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
}

---

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

• Use inline mode by default — Fork mode adds overhead. Only use it for complex, multi-step skills that benefit from an isolated context.
• Keep skill content focused — Each skill should teach the agent one coherent capability. Split large workflows into multiple skills.
• Write actionable instructions — Skills should tell the agent exactly what tools to call and in what order, not just describe concepts.
• Use system skills as templates — Look at the built-in skills for patterns to follow.
• Tag skills for discoverability — Use meaningful tags so agents and humans can find skills quickly.
• Prefer workspace-private skills — Only set is_public = true for skills intended to be shared across workspaces.

---

References

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