Use this page to choose the right Capabilities surface. Tools are callable actions, skills teach agents how to work, and plugins add runtime capabilities such as tools, providers, channels, hooks, and packaged skills.

This is an overview and routing page. For exhaustive tool policy, defaults, group membership, provider restrictions, and configuration fields, use Tools and custom providers.

Start here

For most agents, start with the built-in tool categories, then adjust policy only when the agent should see fewer tools or needs explicit host access.

If you need to... Use this first Then read
Let an agent act with existing capabilities Built-in tools Tool categories
Control what an agent can call Tool policy Tools and custom providers
Teach an agent a workflow Skills Skills, Creating skills, Skill Workshop, and Self-learning
Add a new integration or runtime surface Plugins Plugins and Build plugins
Run work later or in the background Automation Automation overview
Coordinate multiple agents or harnesses Sub-agents ACP agents and Agent send
Orchestrate concurrent agents from code Swarm Code Mode and Sub-agents
Search a large Apus tool catalog Tool Search Tool Search
Combine several tools in one compact program Code Mode Code Mode

Choose tools, skills, or plugins

Use a tool when the agent needs to act

A tool is a typed function the agent can call, such as `exec`, `browser`,
`web_search`, `message`, or `image_generate`. Use tools when the agent
needs to read data, change files, send messages, call a provider, or
operate another system. Visible tools are sent to the model as structured
function definitions.

The model only sees tools that survive the active profile, allow/deny
policy, provider restrictions, sandbox state, channel permissions, and
plugin availability.

Use a skill when the agent needs instructions

A skill is a `SKILL.md` instruction pack loaded into the agent prompt. Use
a skill when the agent already has the tools it needs, but needs a
repeatable workflow, review rubric, command sequence, or operating
constraint.

Skills can live in a workspace, shared skill directory, managed Apus
skill root, or plugin package.

[Skills](/tools/skills) | [Skill Workshop](/tools/skill-workshop) | [Self-learning](/tools/self-learning) | [Creating skills](/tools/creating-skills) | [Skills config](/tools/skills-config)

Use a plugin when Apus needs a new capability

A plugin can add tools, skills, channels, model providers, speech,
realtime voice, media generation, web search, web fetch, hooks, and other
runtime capabilities. Use a plugin when the capability has code,
credentials, lifecycle hooks, manifest metadata, or installable
packaging. Existing plugins can be installed from ClawHub, npm, git,
local directories, or archives.

[Install and configure plugins](/tools/plugin) | [Build plugins](/plugins/building-plugins) | [Plugin SDK](/plugins/sdk-overview)

Built-in tool categories

The table lists representative tools so you can recognize the surface. It is not the full policy reference. For exact groups, defaults, and allow/deny semantics, use Tools and custom providers.

Category Use when the agent needs to... Representative tools Read next
Runtime Run commands, manage processes, use shared operator terminals, or use provider-backed Python exec, process, terminal, code_execution Exec, Control UI terminal, Code execution
Files Read and change workspace files read, write, edit, apply_patch Apply patch
Human input Pause for a structured decision owned by the user, or obtain a credential without seeing it ask_user, secrets Ask user, Secrets
Web Search the web, search X posts, or fetch readable page content web_search, x_search, web_fetch Web tools, Web fetch
Browser Operate a browser session browser Browser
Operator UI Arrange Control UI panes and panels, or select and create appearance themes screen, theme Screen, Theme
Session progress Update the parent session's durable progress card; unavailable to sub-agents progress_card Progress card
Messaging and channels Send replies or channel actions message Agent send
Sessions and agents Inspect sessions, delegate work, orchestrate collectors, steer another run, or report status sessions_*, agents_wait, subagents, agents_list, session_status, get_goal, create_goal, update_goal Goal, Swarm, Sub-agents, Session tool
Automation Schedule work or respond to background events cron, heartbeat_respond Automation
Gateway and nodes Inspect Gateway state or paired target devices gateway, nodes Gateway configuration, Nodes
Plugin lifecycle Inspect, install, enable, disable, remove, or reload plugins plugins Agent plugin management
Media Analyze, generate, or speak media view_image, image_generate, music_generate, video_generate, tts Media overview
Large Apus catalogs Search, call, and combine many eligible tools without sending every schema to the model exec, wait, tool_search, tool_describe, tool_call Code Mode, Tool Search

Session tools and sessions_spawn accept user (the requester's verified requester_profile.id) and act with that person's authority. It is required when several people have steered the turn. See Session tools and Sub-agent tool reference.

On multi-user Gateways, personal_instructions reads and updates the authenticated requester’s personal USER.md through the Gateway, even when the chat uses a project worktree. It is included in the coding and messaging profiles; it does not widen general file-tool access. See User model.

The edit tool supports targeted formatting changes, including removing trailing spaces or replacing Unicode quotes, dashes, and spaces. These changes are applied even when the old and new text would compare equal after fuzzy normalization. Identical replacement requests and edits that produce unchanged content still report no changes.

Code Mode and Tool Search are experimental Apus agent surfaces. Codex harness runs use Codex-native code mode, native tool search, deferred dynamic tools, and nested tool calls instead of tools.codeMode or tools.toolSearch.

Plugin-provided tools

Plugins can register additional tools. Plugin authors wire tools through api.registerTool(...) and the manifest's contracts.tools; use Plugin SDK and Plugin manifest for contract details.

Common plugin-provided tools include:

Configure access and approvals

Tool policy is enforced before the model call. If policy removes a tool, the model does not receive that tool's schema for the turn. A run can lose tools because of global config, per-agent config, channel policy, provider restrictions, sandbox rules, channel/runtime policy, or plugin availability.

Apus exposes one semantic image inspection capability named view_image. When the active harness supplies its own loader, Apus suppresses its duplicate. Otherwise, the Apus-provided implementation accepts path for one local image path or permitted URL, or paths for several; maxImages limits the combined list and defaults to 20. Codex's native implementation accepts one local filesystem path. Callers must follow the active tool schema.

Existing policy entries named image must be migrated to view_image; run apus doctor --fix to update supported config policy surfaces and persisted automation toolsAllow lists.

Extend capabilities

Choose the extension path by the job you need Apus to do:

Troubleshoot missing tools

Configured tools.exec and tools.fs sections do not grant tool access. The profile migration warning suggests alsoAllow entries only when other active global, agent, and provider policies permit those tools.

If the model cannot see or call a tool, start with the effective policy for the current turn:

  1. Check the active profile, tools.allow, and tools.deny in Tools and custom providers.
  2. Check provider-specific restrictions in Tools and custom providers and confirm the selected model provider supports the tool shape.
  3. Check channel permissions, sandbox state, and elevated access with Sandbox vs tool policy vs elevated and Elevated exec.
  4. Check whether the owning plugin is installed and enabled in Plugins.
  5. For delegated runs, check per-agent restrictions in Per-agent sandbox and tool restrictions.
  6. For large Apus catalogs, confirm whether the run uses direct tool exposure, Code Mode, or Tool Search.

Related