SKILL.md Reference

SKILL.md is the skill file format used by Lobu. It combines optional YAML frontmatter with markdown instructions.

Use it for:

Skill metadata such as name and description
Capability declarations such as MCP servers, packages, and network domains
Instruction text that is injected into the agent’s system prompt when the skill is active

Tool policy does not live in SKILL.md. Configure that in lobu.toml under [agents.<id>.tools]; see Tool Policy.

Where Skills Live

Lobu discovers local skills from:

skills/<name>/SKILL.md for shared project-level skills
agents/<agent>/skills/<name>/SKILL.md for agent-specific skills

If the file exists, Lobu loads it automatically at startup.

Minimal example

---
name: PDF Processing
description: Extract text and metadata from PDF files
---

# PDF Processing

When asked to work with PDFs, use `pdftotext` first.

Full example

---
name: My Skill
description: What this skill does

mcpServers:
  my-mcp:
    url: https://my-mcp.example.com
    type: sse

nixPackages:
  - jq
  - ripgrep
  - pandoc

network:
  allow:
    - api.example.com
---

# My Skill

Instructions and behavioral rules for the agent go here as Markdown.
The body acts as a system prompt extension.

Frontmatter Reference

Field	Type	Description
`name`	string	Display name shown in settings and search results
`description`	string	Short summary for the skill registry
`mcpServers`	object	MCP server connections keyed by server ID
`mcpServers.<id>.url`	string	Server endpoint URL
`mcpServers.<id>.type`	`sse` \| `stdio`	Transport type
`mcpServers.<id>.command`	string	Command for stdio MCP servers
`mcpServers.<id>.args`	string[]	Arguments for stdio MCP servers
`nixPackages`	string[]	System packages to install in the worker
`network.allow`	string[]	Domains the worker sandbox can reach
`network.deny`	string[]	Domains to block

Markdown Body

The markdown body after the frontmatter is appended to the agent’s prompt when the skill is active. Use it for workflows, rules, conventions, and domain-specific instructions.

Notes

SKILL.md frontmatter does not configure tool approval or pre_approved MCP tools.
For MCP servers that should live directly on the agent rather than inside a skill, configure them in lobu.toml.