Skills

A skill teaches an agent how to perform a reusable kind of work. In the current local SKILL.md authoring API, a skill can contain:

markdown instructions
a name
a description

Tool access, MCP servers, network policy, approvals, connectors, native packages, and guardrails are operator-controlled configuration. Do not hide those authority changes in a skill.

Choose the right layer

Need	Put it in
Role, tone, standing rules	`IDENTITY.md` or `SOUL.md`
Reusable procedure or domain playbook	`SKILL.md`
Native packages the procedure needs	Agent `nixPackages` in `lobu.config.ts`
Data ingestion or external source actions	A connector
Tool visibility or approval bypass	Tool policy in `lobu.config.ts`
Input, output, or tool-call policy	Guardrails
Shared facts and current state	Memory

Install the Lobu starter skill

The bundled Lobu skill teaches a coding agent the project layout, config API, agent files, connectors, memory, automations, and evals.

npx skills add lobu-ai/lobu --skill lobu

The skills CLI detects Claude Code, Cursor, Codex, OpenCode, and OpenClaw. Use -a <agent> to target one host.

For a Lobu runtime agent, enable bundled skills in the agent settings UI or declare local skills in lobu.config.ts.

Starter Skills

Lobu ships one starter skill. Lobu also discovers local skills from skills/<name>/SKILL.md or agents/<agent-id>/skills/<name>/SKILL.md.

Product	Install	What it adds
Lobu	`Enable from the agent settings UI`	The Lobu starter skill in skills/lobu/ (includes memory guidance)
Local skill	`skills/<name>/SKILL.md` or `agents/<agent-id>/skills/<name>/SKILL.md`	A project-owned custom skill discovered automatically

Declare skills explicitly

A skill is loaded when an agent references it in lobu.config.ts.

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

const support = defineAgent({
  id: "support",
  dir: "./agents/support",
  skills: [
    defineSkill({
      name: "greet",
      description: "Greet a customer.",
      content: "Generate a warm, personalized greeting.",
    }),
    skillFromFile("./agents/support/skills/internal-api"),
  ],
});

Reference the same skill from several agents to share it. Skills are deduplicated by name.

Minimal `SKILL.md`

---
name: Internal API playbook
description: How to answer support questions using the internal API
---

# Internal API playbook

Use the support connector for account lookups and ticket status checks.
When data is missing, ask for clarification instead of guessing.

Only name and description are parsed from local SKILL.md frontmatter. The body becomes the agent-facing instruction content. For instruction-only skills, omit the frontmatter and keep the markdown body.

Skills, tools, and guardrails

A skill is instruction text only, and the operator remains in control:

A skill cannot set tools.preApproved.
A skill cannot expose hidden tools.
A skill cannot declare network policy.
A skill cannot declare native packages — those live on the agent’s nixPackages.
A skill cannot add or weaken guardrails.

This split keeps reusable procedure bundles portable while making permission changes visible in configuration and code review.

Where files live

A conventional layout is:

agents/support/
├── IDENTITY.md
├── SOUL.md
├── USER.md
└── skills/
    └── internal-api/
        └── SKILL.md

The path itself has no effect. skillFromFile(...) is what includes the file in the agent definition.