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

Capability Model

This page defines capability kinds, forms, scopes, refs, and sync materialization.

Capability kinds

Toolang currently manages four capability kinds:

  • skill
  • service
  • prompt
  • psyche

Capability forms

Toolang uses three authored capability forms:

  • ref declared with use ...
  • inline declared directly in {AGENT}.too
  • local human-edited files or directories kept in local cap roots

Rules:

  • inline is agent-scoped only
  • local does not appear in .too
  • ref, inline, and local may coexist for the same kind

Capability scopes

Toolang uses three capability scopes:

  • agent
  • shared
  • global

Runtime precedence is:

  1. agent
  2. shared
  3. global

Important rule:

  • same-name capabilities in different scopes stay separate through sync
  • the effective override is chosen at runtime, not flattened during sync

Runtime scope visibility

invoke, run, and start always load agent-scoped capabilities.

Two switches control whether wider scopes are enabled:

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

Default visibility depends on agent kind:

  • resident shared on, global on
  • roaming shared on, global off
  • visiting shared off, global off

These switches affect runtime visibility only. Sync still materializes each scope in its own root.

Capability references

cap_ref is kind-neutral. Resolution depends on the selected capability kind.

Examples:

  • toolang skill add by3gus/pdf-processing
  • toolang service add by3gus/github
  • toolang prompt add by3gus/rewrite
  • toolang psyche add by3gus/reviewer
  • use skill by3gus/pdf-processing

The same ref syntax is used in .too declarations, shared source files, and capability-management commands.

GitHub resolution

The first supported registry is GitHub. Bare refs use:

user-or-org/cap-name

Probe rules:

  • service
    • repos: agent-services, services
    • paths: services/<cap-name>.md, <cap-name>.md
  • prompt
    • repos: agent-prompts, prompts
    • paths: prompts/<cap-name>.md, <cap-name>.md
  • psyche
    • repos: agent-psyches, psyches
    • paths: psyches/<cap-name>.md, <cap-name>.md
  • skill
    • repos: agent-skills, skills
    • paths: skills/<cap-name>/SKILL.md, <cap-name>/SKILL.md

Sync outputs

toolang sync materializes three scope roots plus one per-agent state file.

Materialized roots:

  • global ${TOOLANG_ROOT}/sync/
  • shared ${AGENT_HOME}/.toolang/sync/
  • agent ${AGENT_HOME}/.toolang/agents/{AGENT}/sync/

Per-agent state:

  • ${AGENT_HOME}/.toolang/sync/<agent>.state.json

The state file stores freshness metadata, the compiled synced program, and the exact resolved refs by scope.

Sync contract

High-level sync flow:

  1. parse top-level .too files
  2. analyze declarations, refs, and inline capabilities
  3. parse shared and global agents.too
  4. read local cap roots
  5. resolve refs to exact immutable targets
  6. materialize global, shared, and agent sync roots
  7. rewrite one state file per top-level .too

The reason for this design is simple: unchanged agents should not need a fresh parse just to recover inline capabilities, and runtime precedence should remain inspectable.

Read next

  • Read Layout and Storage for the filesystem roots behind each scope.
  • Read Plugin Model for the broader integration boundary around capabilities and plugins.
© 2026 Toolang