Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Capabilities

Capabilities are the reusable building blocks that a Toolang agent can load and overlay at runtime.

Four capability kinds

Toolang manages four kinds:

  • skill
  • service
  • prompt
  • psyche

Each kind uses the same ref model and the same scope model. The difference is the role it plays for the agent.

Three ways to include a capability

Toolang supports three authored forms:

  • ref declared with use ... in .too or agents.too
  • inline declared directly inside one .too file
  • local an editable file or directory stored in a local cap root

The practical rule is:

  • use ref when the capability should stay reusable
  • use inline when it only belongs to one agent
  • use local when you want an editable on-disk copy

Scope and precedence

The same capability name can exist at three scopes:

  • agent only this agent sees it
  • shared agents in the same home can share it
  • global every eligible agent on the machine can see it

Runtime precedence is:

  1. agent
  2. shared
  3. global

That means a narrower scope can override a wider one without deleting it.

Refs use one neutral shape

Capability refs are kind-neutral:

user-or-org/cap-name

The same ref syntax is used in:

  • .too use declarations
  • shared agents.too source
  • CLI commands such as toolang skill add ...

sync keeps scopes separate

toolang sync does not flatten scope overrides into one merged directory. It materializes global, shared, and agent-scoped sync outputs separately.

That preserves two important properties:

  • runtime precedence stays explicit
  • exact resolved refs can be inspected later

Runtime visibility stays configurable

Toolang always loads agent-scoped capabilities. Wider scopes can be enabled or disabled at runtime:

  • --shared or --no-shared
  • --global or --no-global

That matters when you want an agent to run with only its local inputs, or when you want a resident agent to inherit machine-wide capabilities.

Common capability commands

All four kinds share the same command shape:

toolang skill add <cap_ref> --scope=agent
toolang skill remove <name> --scope=shared
toolang skill local new <name> --scope=global
toolang skill local new <name> --from <cap_ref> --scope=shared
toolang skill local path <name> --scope=shared
toolang skill local delete <name> --scope=global

The same structure applies to service, prompt, and psyche.

Read next

© 2026 Toolang