Skills

Skill source roots, seeded skills, and lifecycle.

Skills are markdown-defined task workflows (<skill dir>/SKILL.md) discovered from workspace, managed, and bundled roots.

Skill sources

workspace: <workspace>/skills (default /app/workspace/skills)
managed: <state dir>/skills — the state dir resolves from CLAPILOTAICORE_STATE_DIR / CLAPILOT_STATE_DIR / CLAPILOT_HOME, with OPENCLAW_HOME retained as a legacy fallback
bundled: CLAPILOT_BUNDLED_SKILLS_DIR (legacy OPENCLAW_BUNDLED_SKILLS_DIR), defaulting to /app/workspace-seed/skills
discovery logic: src/lib/skill-store/local-skills.ts

When the same skill key exists in several roots, the effective entry is the one with the highest source priority (workspace > managed > bundled).

SKILL.md frontmatter

Optional frontmatter fields supported by the local skill store:

origin: agent marks procedures written by the native agent or Skill Curator; absent/other values remain human or bundled skills.
status: active (default), draft, or archived. Draft and archived skills remain on disk but are excluded from agent catalog search.
pinned: protects an agent-authored skill from all automatic curator updates and archives.
requirements: JSON array of setup requirements. Supported kinds are app_setting and env.
install_recipe: JSON object for a one-click setup action. Current supported type: open_settings.
disabled: boolean flag to surface a skill as disabled in the UI without removing it from disk; disabled_reason adds an optional explanation.
required_tool_names / required_auth_resource_keys: tool and auth dependencies for the skill. For several first-party skills these default from the built-in DEFAULT_SKILL_DEPENDENCIES map in local-skills.ts when the frontmatter omits them.

Workspace-seeded Clapilot skills

Seed location: workspace-seed/skills

Seeded skills auto-refresh from workspace-seed/skills into /app/workspace/skills on normal container starts (entrypoint.sh re-copies any seeded non-profile file whose content differs). Local edits to seeded skill directories are therefore treated as ephemeral and will be replaced by the shipped version on restart; create a separate non-seeded workspace skill for instance-specific customizations you want to keep.

clapilot
clapilot-x
clapilot-browser-use
clapilot-document-extraction
clapilot-excel
clapilot-module-creator
clapilot-module-dev
clapilot-pet-creator
clapilot-agent-orchestrator
clapilot-client-website-manager
clapilot-bundled-module-builder
clapilot-bundled-module-starter
clapilot-tax-manager
clapilot-video-styleguide
clapilot-canvas-design
clapilot-grocery
clapilot-cli plus the generated clapilot-cli-<family> skills (see below)

clapilot-pet-creator is also attached to the bundled @pet-creator specialist. It provides the Ilumagine-style voxel pet prompt recipes, the default laptop-working chat activity animation recipe, and the profile_pets_register handoff used to make generated pets appear under Settings -> Profile -> Pet. The register handoff also creates the app-facing transparent looping laptop-working GIF when the specialist only has a still preview image.

clapilot-grocery covers the Einkauf (Grocery) module: the shared open list, purchase-frequency planning, order recording and imports, and preparing a shop order in a signed-in browser profile up to the cart (the user places the order). Shop-specific know-how lives in agent-maintained, pinned shop skills named grocery-shop-<shop_key>: the Grocery module installs the grocery-shop-rewe template into /app/workspace/skills/ once (never overwriting it), and the agent creates skills for other shops with skills_create and extends them with skills_update after each run, so they survive reseeds; see Einkauf (Grocery).

clapilot-tax-manager operates the Finanzen (tax-manager) generation workflow end-to-end through the four current tax_manager_* agent tools; see Finanzen / Steuer-Manager.

clapilot-video-styleguide converts public/clapilot-styleguide.html into a HyperFrames-ready design.md, video styleguide composition, and reusable PNG backgrounds/overlays. The companion HTML reference is public/clapilot-video-styleguide.html. The skill also documents the Chrome DevTools capture workflow for recording real Clapilot web app demo flows before rendering titles, captions, camera motion, and intro/outro assembly.

clapilot-canvas-design gives the agent layout standards for Canvas HTML documents. Its SKILL.md is a router that loads the global rules (semantic HTML, the 4 px spacing scale, the mandatory canvas_get_style_settings brand-token mapping, and the Clapilot house style) plus a per-document-type reference under references/: presentation.md (16:9 decks), letter-din5008.md (DIN 5008 German business letters), sheet-tax.md (data/financial/tax tables for print), and frontend.md (dashboards, reports, basic pages). The Canvas page-capability instructs the agent to read this skill before generating any non-trivial layout.

clapilot-browser-use routes complex browser automation through the optional Browser Use Cloud V4 integration. Admins configure the encrypted bu_ key under Settings -> App connections -> App integrations; users can then create dedicated persistent profiles under App connections, explicitly consent, sign in once through the remote browser canvas, and reuse that identity with browser_use_run.profile_id. Profiles are personal-first and audited; raw browser state remains with the provider. The skill requires the browser_profiles_list and browser_use_run tools plus the browser_use_api auth resource, and generated workspace files are copied into /app/workspace/browser-use/<run-id>/.

The `clapilot-cli` skill family

The agent runtime ships a clapilot-cli binary on PATH that exposes every Clapilot tool as a shell subcommand. The clapilot-cli index skill lists one generated family skill per tool family — clapilot-cli-<family> (39 families at the time of writing, from clapilot-cli-accounting to clapilot-cli-word) — each documenting that family's actions, common flags, and example invocations. These skills are generated by scripts/generate-cli-skills.mjs; edit the generator, not the generated SKILL.md files.

Skill store lifecycle

list local/effective skills via /api/skill-store/local
fetch catalog via /api/skill-store/catalog
publish local skill archives to hub (admin) via /api/skill-store/publish
install selected hub versions as local instance skills (admin) via /api/skill-store/install
delete local non-bundled skills again via /api/skill-store/delete (admin)
evaluate per-skill setup state (ready, needs_setup, disabled) and show one-click setup links in the UI

Agent-authored skills & Skill Curator

The native skills_create, skills_update, and skills_archive tools let the agent persist concise reusable procedures under <workspace>/skills. New tool-authored skills carry origin: agent, start as status: active, record creation/update timestamps and creator context, and are immediately discoverable after the short catalog cache refresh. The agent can update or archive only origin: agent entries; it cannot shadow an existing directory from any installed root, mutate human/bundled skills, or delete skill files.

The preinstalled Skill Curator automation runs nightly at 03:40 Europe/Berlin. It reviews all workspace agent skills plus trimmed summaries from recent successful non-system runs with tool activity. One schema-constrained maintenance-model call may propose at most six guarded actions: create a draft, refine an existing skill, merge near-duplicates while archiving the superseded entry, or archive a stale procedure. Code-side guards reject invalid directories, human/bundled targets, pinned skills, over-limit actions, and every delete action. Each run records its status, stats, proposed/applied actions, and errors in agent_skill_curator_runs; an unavailable maintenance model produces a clean audited skip.

Curator-created procedures always start as status: draft. Drafts and archived skills are invisible to agent catalog search and appear in dedicated Skill Store review sections. Admins can activate, archive, restore, pin, or unpin agent-authored skills. Pinning freezes the skill against automatic curator changes; archiving never removes its directory.

UI implementation: store tab at /modules?tab=skills (the /skills route redirects there), rendered by src/components/skill-store-content.tsx as App Store-style sections with status filter chips, search, install pills, and a skill detail dialog for setup requirements, publish, and delete.

Security model

publish/install/delete and agent-skill lifecycle review require admin role
non-admin views redact sensitive filesystem details
hub archives use shared-secret signing
bundled and agent-authored skills remain protected from deletion; agent-authored skills are archived instead

Skills + API usage map

For the current agent/tool API surface:

Agent Tool Contracts

Chat suggestion placement

Skill, mention, and reference suggestions appear above the chat input. Web suggestion menus scroll within a bounded height so the composer stays in place; this also applies to Agent Orchestrator file suggestions.

Selecting skills in Chat and Team Chat

Chat and Team Chat support / skill autocomplete on web (including floating chat), iOS and macOS. Type / at the start of a message or after whitespace, search installed skills by name or description, and select a result. Repeat to select multiple skills. Each selection inserts a visible /skill:<directory-name> token; remove the token to remove that selection. Web supports arrow keys and Enter/Tab as well as clicking; Apple clients reuse the native suggestion buttons.

GET /api/chat/skills?search=<query> requires an authenticated session (or the existing modules:api:read service scope). It returns { skills: [{ id, name, description }] }, up to seven alphabetically sorted active, enabled installed skills, using workspace → managed → bundled precedence. Filesystem paths and skill bodies are not exposed by this endpoint. Loading, empty and error states are localized in German, English and Italian.

The message contract remains text-based: explicit /skill:<directory-name> selections travel with the request and its saved draft/transcript. ClapilotAICore resolves and deduplicates selections from the current user input, loads every selected SKILL.md before provider execution, and includes the full content, source path and an instruction to apply all selected skills in the turn instructions. Existing skill discovery and resource-reading tools remain available. Selections apply to that request; they do not change global or specialist skill configuration. A missing, inactive, disabled, empty or unreadable selected skill fails the turn visibly. Skill instructions preserve system safety, tool permissions and approval requirements. Selecting a skill does not change Team Chat recipient/agent routing.