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

Tool access, MCP servers, network policy, approvals, connectors, 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 | nixPackages in SKILL.md or agent config | | 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, watchers, 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 only when an agent references it. There is no folder auto-discovery.

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
nixPackages:
  - jq
---

# 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, description, and nixPackages 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

Skills may request packages and provide instructions, but 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 weaken agent-wide input or output guardrails.
Destructive MCP tools still use the normal approval flow unless the operator explicitly pre-approves them.

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 behavior. skillFromFile(...) is what includes the file in the agent definition.