Skip to main content
Agent skill

Builtin Tool

Use for LobeHub builtin agent tools: manifests, executors, runtimes, inspectors, renders, streaming and intervention.

All install options
Quick install · Personal (~/.claude/skills)Project / Cursor / Desktop →
mkdir -p ~/.claude/skills/builtin-tool && curl -fsSL 'https://raw.githubusercontent.com/lobehub/lobehub/canary/.agents/skills/builtin-tool/SKILL.md' -o ~/.claude/skills/builtin-tool/SKILL.md

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Builtin Tool when an AI agent needs a reusable SKILL.md workflow for this job: Use for LobeHub builtin agent tools: manifests, executors, runtimes, inspectors, renders, streaming and intervention.

When not to use it

Skip Builtin Tool when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
One-line install (Claude Code)
mkdir -p ~/.claude/skills/builtin-tool && curl -fsSL 'https://raw.githubusercontent.com/lobehub/lobehub/canary/.agents/skills/builtin-tool/SKILL.md' -o ~/.claude/skills/builtin-tool/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/builtin-tool/SKILL.md. For a shared project, commit the folder at .claude/skills/builtin-tool/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Builtin Tool skill for this task: Creating a new packages/builtin-tool-<name>/ package. Confirm any required inputs or files before making changes.

What supports this recommendation?

81/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
87/100
Practical detail
92/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • chatgptinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Builtin Tool Authoring Guide

A builtin tool is a package the agent runtime can call. It ships **five faces**:

| Face | Lives in | Audience | | -------------------- | -------------------------------------------------------------------------------------- | ------------------------------------- | | **Manifest + types** | `src/{manifest,types,systemRole}.ts` | The LLM (tool spec + system prompt) | | **ExecutionRuntime** | `src/ExecutionRuntime/` | Server / desktop / any runtime caller | | **Executor** | `src/client/executor/` | Frontend (wraps stores/services) | | **Client UI** | `src/client/{Inspector,Render,…}/` | Chat UI | | **Registry wiring** | `packages/builtin-tools/src/*.ts` + `src/store/tool/slices/builtin/executors/index.ts` | Framework |

---

## Read These First

| Question | Doc | | ------------------------------------------------------------------------------------ | --------------------------------------------- | | Where do files live? What does each face do? Wiring? | [architecture.md](references/architecture.md) | | How do I name the tool, design APIs, write the manifest, executor, ExecutionRuntime? | [tool-design.md](references/tool-design.md) | | How do I build Inspector / Render / Placeholder / Streaming / Intervention / Portal? | [ui/](references/ui/README.md) |

---

## When to Use This Skill

- Creating a new `packages/builtin-tool-<name>/` package - Adding a new API method to an existing builtin tool - Building or restyling any of the 6 client surfaces for a tool - Wiring a tool into the central registries - Debugging "tool not found / API not found / render not showing / placeholder stuck" errors

---

## Top-Level Design Principles

1. **`lobe-<domain>` identifier is permanent.** It's stored in message history. Renames need legacy aliases kept alongside the new name (see the `// Legacy aliases` entries in `packages/builtin-tool-local-system/src/client/Inspector/index.ts`, kept after `listLocalFiles`/`searchLocalFiles` were renamed to `listFiles`/`searchFiles`). Get it right the first time. 2. **ApiName is an `as const` object**, not a TS enum. It doubles as the runtime list `BaseExecutor` iterates over. 3. **Three result fields, three audiences:** - `content: string` → the LLM reads it - `state: Record<…>` → the UI's `pluginState`; **result-domain only**, never echo all params back - `error: { type, message, body? }` → both LLM and UI; `type` is a stable code 4. **Split execution from frontend wiring.** - `src/ExecutionRuntime/` — pure runtime, no React, no Zustand, accepts services via constructor. **The default place for new logic.** - `src/client/executor/` — `BaseExecutor` subclass that calls `ExecutionRuntime` (or stores/services directly when frontend-only). 5. **UI defaults to "do nothing".** Inspector is required (the header strip). Render/Placeholder/Streaming/Intervention/Portal are added **only when there's something specific to show** — empty registries are fine. 6. **Style with `createStaticStyles + cssVar.*`** (zero-runtime). Fall back to `createStyles + token` only when you genuinely need runtime values. Use `@lobehub/ui` components, not raw antd. 7. **i18n keys live in `packages/locales/src/default/plugin.ts`.** Inspector titles must come from `t('builtins.<identifier>.apiName.<api>')` so something renders while args stream. 8. **A failed long-running call should be continuable, not just inspectable.** Example: when `callSubAgent` stops halfway, the user says "keep going". So the fix was an optional `subAgentId` on `callSubAgent` that appends a new instruction to the same sub-agent thread — not a new "look up that run" API the model has to remember to call before retrying from scratch. Add a new API only when a user would ask for it on its own.

---

## Package Layout (preferred, post-2026 convention)

``` packages/builtin-tool-<name>/ ├── package.json └── src/ ├── index.ts # exports manifest + types + systemRole + Identifier (no React, no stores) ├── manifest.ts # BuiltinToolManifest with JSON Schema for every API ├── types.ts # ApiName const + Params/State interfaces per API ├── systemRole.ts # System prompt teaching the model when/how to use the APIs ├── ExecutionRuntime/ # ✅ Default home for runtime logic (server- or anywhere-callable) │ └── index.ts └── client/ ├── index.ts # Re-exports for the registries ├── executor/ # ✅ Frontend executor — extends BaseExecutor, often delegates to ExecutionRuntime │ └── index.ts ├── Inspector/ # required — header chip per API ├── Render/ # optional — rich result card ├── Placeholder/ # optional — skeleton during streaming/execution ├── Streaming/ # optional — live output renderer (e.g. RunCommand, WriteFile) ├── Intervention/ # optional — approval / edit-before-run UI ├── Portal/ # optional — full-screen detail view └── components/ # shared subcomponents used by the surfaces above ```

**Older packages** (`builtin-tool-calculator`, etc.) still have `src/executor/` as a sibling of `src/client/`. That's grandfathered; **don't relocate without a deliberate refactor**. New packages and new APIs added to existing packages should follow the layout above.

`package.json` exports map:

```json "exports": { ".": "./src/index.ts", "./client": "./src/client/index.ts", "./executor": "./src/client/executor/index.ts", "./executionRuntime": "./src/ExecutionRuntime/index.ts" } ```

---

## Authoring Checklist

Before opening the PR:

- [ ] Identifier follows `lobe-<domain>` and is **stable** (lives in message history). - [ ] Every `<Name>ApiName` value has: a manifest `api[]` entry, an executor method, an Inspector, an i18n `apiName.*` key. - [ ] `Params` interfaces match the JSON Schema; `State` interfaces match what the executor returns and what the UI surfaces read. - [ ] System prompt disambiguates confusable APIs and points to batch variants. - [ ] Runtime logic lives in `ExecutionRuntime/`; the `client/executor/` only wires stores/services and delegates. - [ ] Executor returns `{ success, content, state, error? }` via a single `toResult()` funnel — `content` always non-empty (default to `error.message`). - [ ] Inspector handles `isArgumentsStreaming`, `isLoading`, `partialArgs`, missing `pluginState`. - [ ] Render returns `null` until it has data; only created for APIs with rich results. - [ ] Placeholder added if the API has a perceivable execution lag (search, list, crawl). - [ ] Streaming added for APIs that emit incremental output (run command, write file, code execution). - [ ] Intervention added if `humanIntervention` is set in the manifest. - [ ] All registry files updated (see [architecture.md → Registry wiring](references/architecture.md#registry-wiring)). - [ ] i18n keys in `packages/locales/src/default/plugin.ts` plus dev seeds in `en-US`/`zh-CN`. - [ ] `bunx vitest run --silent='passed-only' 'packages/builtin-tool-<name>'` passes. - [ ] `bun run type-check` passes.

---

## Reference Tools

Pick the closest neighbor and copy:

| If your tool is… | Read first | | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Pure-compute, no UI state | `packages/builtin-tool-calculator/` — `ExecutionRuntime` reuses executor (mathjs/nerdamer work everywhere) | | CRUD over a domain entity | `packages/builtin-tool-task/` — full Inspector + Render set, batch variants | | Heavy UI (Inspector/Render/Placeholder/Portal) | `packages/builtin-tool-web-browsing/` — search-style result UI, Portal for detail view | | Desktop / filesystem with all surfaces (incl. Streaming + Intervention) | `packages/builtin-tool-local-system/` — `ExecutionRuntime` injects an `ILocalSystemService`, executor calls it | | Server-side pure (no client executor) | `packages/builtin-tool-web-browsing/` — only `ExecutionRuntime` is exported; the chat client doesn't run it | | Needs human approval before running | `packages/builtin-tool-local-system/src/client/Intervention/` — per-API approval components |

Intended uses

  • Creating a new packages/builtin-tool-<name>/ package
  • Adding a new API method to an existing builtin tool
  • Building or restyling any of the 6 client surfaces for a tool
  • Wiring a tool into the central registries
  • Debugging "tool not found / API not found / render not showing / placeholder stuck" errors

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.