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
Instruction text that is injected into the agent’s system prompt when the skill is active

A skill is instruction text only. It cannot declare packages, network domains, MCP servers, tools, or guardrails — those are operator-controlled configuration in lobu.config.ts. See Skills for the rationale.

Where Skills Live

A SKILL.md is loaded when an agent references it from lobu.config.ts with skillFromFile:

import { defineAgent, skillFromFile } from "@lobu/cli/config";

defineAgent({
  id: "support",
  skills: [skillFromFile("./agents/support/skills/internal-api")],
});

The path is a folder holding a SKILL.md (or a .md file directly), resolved relative to lobu.config.ts. Reference each skill you want the agent to use. To declare a skill without a file, use defineSkill({ name, content, ... }) instead; see Skills.

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
---

# My Skill

Instructions and runtime 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

No other frontmatter is read. If a skill needs native tools, declare them on the agent’s nixPackages; if it needs network access or guardrails, the operator configures them on the agent — never from a skill file.

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, network access, packages, or preApproved grants. Authority stays in lobu.config.ts.
Install service integrations as connectors, not as skill-local MCP servers.