Extend agents with caps

Learn how caps extend agents with reusable psyches, skills, services, and prompts.

This guide shows how caps work, where they live, and how to add them to an agent.

What are caps?

Caps are composable agent primitives.

Kinds

Toolang supports four kinds of caps:

Kind	Description
`Psyche`	Instructions that are always included in the agent context.
`Skill`	Instructions that teach an agent how to do something.
`Service`	A connection to an external tool or system.
`Prompt`	A reusable prompt that can be enabled as a slash command.

Forms

Caps fall into four categories based on how they are introduced to an agent:

Form	Description
`Wired`	Referenced from config.toml.
`File`	Stored as a local file.
`Ref`	Referenced from a .too file with the `use` keyword.
`Inline`	Written directly inside a .too file.

Scopes

Caps can come from different scopes:

Scope	Description
`Home`	Caps under one agent home, available to that agent.
`Root`	Caps under the Toolang root, shared by all agents under the same root.
`Here`	Caps declared in the current .too file, either inline or by reference.

Manage caps

You can manage caps from the command line.

Caps are ultimately text files or references stored in config files. You can edit those files directly with your favorite editor, but the CLI gives you a convenient way to add, remove, create, edit, and delete caps.

Manage remote caps

Remote caps are added by ref or URL. For example:

toolang alice skill add briceyan/review
toolang alice service add briceyan/github
toolang alice psyche add briceyan/senior-engineer
toolang alice prompt add briceyan/concise

A short ref such as briceyan/review is resolved to a remote cap source. For example, a skill ref may resolve to:

owner = briceyan
repo = agent-skills
path = review/SKILL.md

These commands add cap references to Alice’s config file at $TOOLANG_ROOT/agents/alice/config.toml.

Remove remote caps by kind and name:

toolang alice skill remove review
toolang alice service remove github
toolang alice psyche remove senior-engineer
toolang alice prompt remove concise

This removes the matching references from Alice’s config file.

Manage local caps

Local caps are stored as files.

Create local caps for an agent:

toolang alice skill new review
toolang alice service new github
toolang alice psyche new senior-engineer
toolang alice prompt new concise

These commands create cap files under Alice’s agent home. For example, a service named github may be created at $TOOLANG_ROOT/agents/alice/services/github.md.

Edit local caps:

toolang alice skill edit review
toolang alice service edit github
toolang alice psyche edit senior-engineer
toolang alice prompt edit concise

The edit command opens the cap file in your editor. You can modify and save the file, or quit without saving.

Delete local caps:

toolang alice skill delete review
toolang alice service delete github
toolang alice psyche delete senior-engineer
toolang alice prompt delete concise

This deletes the matching cap files from Alice’s agent home.

Manage root caps

The commands above specify the agent alice, so they manage caps in Alice’s home scope.

To manage caps in the root scope instead, omit the agent name:

toolang skill add briceyan/review
toolang service remove github
 
toolang skill new review
toolang skill edit review
toolang skill delete review

Root caps are shared by all agents under the same Toolang root. Remote root caps are referenced in $TOOLANG_ROOT/config.toml, while local root caps are stored under $TOOLANG_ROOT/{skills,services,psyches,prompts}/.

Reference remote caps

Remote caps can be referenced by short ref:

toolang alice skill add briceyan/review

They can also be referenced by URL:

toolang alice skill add https://caps.sh/briceyan/review

Use refs for common shared caps. Use URLs when you want to point to a specific source directly.

Choose runtime caps

By default, Toolang can use all caps available to an agent.

You can narrow that set before an agent runs. A common workflow is to list caps with toolang caps, test a selector list with --filter, then pass the same selector list to --caps.

List available caps

Use toolang caps to show caps in the root scope, or toolang alice caps to show caps available to one agent:

toolang caps
toolang alice caps

Use --filter with a cap selector list to narrow the result:

toolang caps --filter "skill/*"
toolang alice caps --filter "service/*[home]"
toolang alice caps --filter "*[scope:root,form:file]"

Specify runtime caps

Use --caps to limit which caps are available for a run, start, or thunk invocation.

The value passed to --caps is also a cap selector list:

toolang run alice --caps "skill/reviewer"
toolang start alice --caps "service/*[home]"
toolang helpers.too review --caps "*[scope:root,form:file]"

Cap selector lists

A cap selector list is a comma-separated list of selectors. Each selector has this shape:

pattern[filters]

The pattern matches cap identities. A cap identity is usually written as kind/name, and * can be used as a wildcard:

Pattern	Meaning
`skill/reviewer`	Match the `reviewer` skill.
`service/*`	Match all services.
`reviewer`	Match caps named `reviewer`, regardless of kind.
`*`	Match all caps.

Filters are optional. A filter has the shape key:value and narrows the match by metadata:

Filter key	Values
`scope`	`root`, `home`, `here`
`form`	`inline`, `ref`, `wired`, `file`
`origin`	`local`, `remote`

Several shorthand forms are supported:

Shorthand	Meaning
`[here]`	`[scope:here]`
`[wired]`	`[form:wired]`
`[remote]`	`[origin:remote]`
`[here,wired]`	`[scope:here,form:wired]`

Examples:

Selector list	Meaning
`skill/reviewer`	Match the `reviewer` skill.
`service/*[wired,home]`	Match wired services from the home scope.
`*[scope:root,form:file]`	Match file caps from the root scope.
`skill/reviewer,service/github[home]`	Match either the `reviewer` skill, or the `github` service from the home scope.