Cap files

Reference for local cap file formats.

Caps are reusable agent primitives. Toolang currently supports four cap kinds: psyche, skill, service, and prompt.

Locations

Shared local caps live under the Toolang root:

${TOOLANG_ROOT}/
  psyches/<name>.md
  skills/<name>/SKILL.md
  services/<name>.md
  prompts/<name>.md

Private local caps live under one agent home:

${TOOLANG_ROOT}/agents/<agent>/
  psyches/<name>.md
  skills/<name>/SKILL.md
  services/<name>.md
  prompts/<name>.md

The cap name comes from the file or directory name, not from frontmatter.

Local Refs

Local refs identify the selected cap:

Remote refs use canonical GitHub refs such as github://owner/repo/path/name.md@rev. GitHub cap refs must include @rev after shorthand resolution.

Precedence

One activation builds an effective cap set by (kind, name).

Runtime scope precedence is:

1. here: inline caps and use refs from the current .too source
2. home: agent-local files or wired refs
3. root: root-level files or wired refs

The winning cap is what runs see. Source details such as file path, line, form, origin, and ref are still exposed by cap list APIs.

Psyche Files

Psyches are Markdown files with optional frontmatter. The body defines stable behavior preferences for the agent.

Describe the agent's stable behavior preferences here. Keep this focused on
tone, judgment, and defaults that should apply across many runs.

Psyche frontmatter is not validated by a strict field list.

Skill Files

Skills are directories containing SKILL.md.

skills/
  code-review/
    SKILL.md
    references/
    scripts/
    assets/

SKILL.md must contain frontmatter with exactly one field:

The body is required and contains the loaded workflow instructions.

---
description: Trigger this skill for requests that need code review.
---
 
# Code Review
 
When to use:
- ...
 
Workflow:
1. ...
2. ...

Additional files can live beside SKILL.md; Toolang treats the skill as a directory-shaped cap and materializes the directory when needed.

Service Files

Services are Markdown files that describe external MCP servers. Toolang uses frontmatter to connect the service at runtime.

Only these frontmatter fields are accepted for services.

---
description: Trigger this service when the agent needs GitHub operations.
transport: http
target: https://mcp.github.com/mcp
headers:
  Authorization: Bearer $GITHUB_TOKEN
---
 
Use this service for GitHub repository, issue, and pull request work.

For stdio services, target is an argv command line and env lists required environment variables:

---
description: Trigger this service when the agent should launch the local MCP server.
transport: stdio
target: uvx example-mcp-server
env: API_TOKEN, ANOTHER_ENV_VAR
---
 
Document the server capabilities and auth expectations here.

Header values such as $API_TOKEN declare host environment variables that must be present when the service is used.

Prompt Files

Prompts are Markdown files with optional frontmatter. The body is reusable prompt text.

Write the reusable prompt text here.
 
Use `{{input}}` for the caller input.

Prompt frontmatter is not validated by a strict field list.

Wired Remote Caps

config.toml can wire remote caps by kind. Root config wires shared caps; agent config wires private caps.

[skills]
reviewer = { ref = "github://acme/agents/skills/reviewer@main" }
 
[services]
github = { ref = "github://acme/agents/services/github.md@main" }

Wired caps have form: wired. Inline .too declarations have form: inline. use declarations have form: ref. Local cap files have form: file.

Prepared Artifacts

Prepared caps are materialized under .caps roots:

${TOOLANG_ROOT}/.caps/
${TOOLANG_ROOT}/agents/<agent>/.caps/

Within a prepared root, Toolang separates source forms:

Prepared artifacts are generated runtime input. Edit the durable source files or config entries instead.