lobu-builder

---
name: lobu-builder
description: Use when working inside a Lobu project generated by @lobu/cli or any repository centered on lobu.config.ts, AGENTS.md, agent prompt files, local skills, and evals. This skill helps a coding agent inspect the right files, make Lobu-native changes, keep the stack runnable, and validate semantics with chat tests and evals.
---

# Lobu Builder

## Overview

Use this skill when the repository is a Lobu project and the task is to build or change the agent itself: prompt files, `lobu.config.ts`, local skills, MCP configuration, connections, network settings, or evals.

If you are inside the Lobu monorepo rather than a generated Lobu project, follow that repository's own instructions first.

## First Pass

1. Read `AGENTS.md` first. If it redirects to another file such as `@TESTING.md`, open that too.
2. Read `lobu.config.ts`. It is TypeScript: `defineConfig` from `@lobu/cli/config` is the default export.
3. Enumerate agent directories under `agents/` and inspect the target agent's `IDENTITY.md`, `SOUL.md`, and `USER.md`.
4. Check whether the repo has shared `skills/` or agent-local `agents/<id>/skills/`.
5. Look for evals under `agents/<id>/evals/promptfooconfig.yaml` (the project may also have legacy YAML files — those don't run).

Do not assume there is only one agent or one platform connection.

## What To Edit

- `IDENTITY.md`: who the agent is
- `SOUL.md`: rules, workflows, guardrails
- `USER.md`: user or tenant context
- `lobu.config.ts`: providers, connections, enabled skills, MCP servers, network allowlist (authored with `define*` from `@lobu/cli/config`)
- `skills/.../SKILL.md`: shared reusable capabilities
- `agents/<id>/skills/.../SKILL.md`: agent-specific capabilities
- `agents/<id>/evals/promptfooconfig.yaml`: promptfoo eval suite (runs via `bunx promptfoo eval` with `@lobu/promptfoo-provider`)

Prefer editing these files directly instead of burying semantics in ad hoc code.

## Workflow

1. Keep the project runnable. Start or reuse the stack with `npx @lobu/cli@latest run -d`.
2. Make the smallest prompt, config, skill, or eval change that solves the task.
3. Run `npx @lobu/cli@latest validate` after changing `lobu.config.ts` or skill definitions.
4. Test semantics with `npx @lobu/cli@latest chat "..."` or the project's testing instructions.
5. Run `LOBU_TOKEN=$(npx @lobu/cli@latest token --raw) bunx promptfoo eval -c agents/<id>/evals/promptfooconfig.yaml` when the expected result should be captured as a regression test.

If the repository already provides project-specific test scripts, use those.

## Skills And MCP

- Prefer Lobu skills for reusable capabilities.
- For external data, prefer a small MCP surface over custom glue code.
- For MVP work, start with one MCP server and one skill.
- If per-user access matters, prefer MCP OAuth device authorization and let the gateway proxy handle authentication.
- Keep network access narrow; only add the domains the agent actually needs.

## Useful Suggestions

- Add or reorder providers on `defineAgent({ providers })` in `lobu.config.ts`
- Enable built-in skills with `npx @lobu/cli@latest skills list`, `search`, or `add`
- Add a custom MCP server via `defineAgent({ mcpServers })`
- Add a shared skill under `skills/` for repeated workflows
- Add evals for risky automations and policy constraints
- Wire observability only when needed; Lobu supports Grafana/Tempo traces

## References

- Getting started: https://lobu.ai/getting-started/
- Skills: https://lobu.ai/getting-started/skills/
- Skills authoring: https://lobu.ai/guides/skills-authoring/
- MCP proxy and device auth: https://lobu.ai/guides/mcp-proxy/
- Testing: https://lobu.ai/guides/testing/
- Evals: https://lobu.ai/guides/evals/
- Observability: https://lobu.ai/guides/observability/
- Repository: https://github.com/lobu-ai/lobu

Before requesting connector app credentials, discover `connections.setupOptions` with `search_sdk` and call it in the selected workspace. It returns verified managed OAuth, hosted cloud chat, and local setup choices. Follow the returned URL and instructions; an unavailable cloud lookup is not proof that no managed offer exists. On account-scoped MCP, select an authorized home workspace before calling `connections.connectManaged` against cloud; the provider org is its `managed_by_org` argument. Managed OAuth can support local execution. Hosted Slack chat targets a cloud agent and does not connect an independent embedded runtime.

• SKILL.md 4 KB
• agents/openai.yaml 1 KB