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-camoufox-browser
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-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-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; the skill requires the browser_use_run tool and 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> (36 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