File formats

Markdown file formats read by Toolang 0.4.0. Caps and chores use YAML frontmatter followed by a Markdown body. Names come from filenames or skill directories; a supplied cap name field must match that path.

Cap files

Root cap directories supply shared definitions; agent-home directories supply agent-specific definitions. Home definitions take precedence over matching root definitions. Inline or referenced caps belong to their .too module.

Markdown and inline declarations

These formats are not interchangeable. Keep YAML --- delimiters and YAML lists inside Markdown files; see Grammar for .too declarations. A malformed definition produces a validation error, not an unavailable row in too caps --all.

Psyche files

Prefer direct answers and concrete examples.
State uncertainty when the available evidence is incomplete.

Frontmatter is optional. Other psyche metadata has no format-specific schema; name, when supplied, still has to match the filename.

Skill files

---
description: Review code changes for defects and missing regression coverage.
---
 
Read the changed code and its callers. Report actionable findings with locations.

The body must be nonblank. Other frontmatter fields are rejected. A skill may keep supporting files in its directory, for example references/ and scripts/.

Service files

---
description: Search the project's external knowledge service.
transport: http
target: https://example.com/mcp
---
 
Use the service to find project documentation.

The body is optional. Other fields are rejected. In 0.4.0 the built-in service connector does not forward this headers metadata or expand environment references inside it. A value such as Bearer $SEARCH_API_KEY does not configure authentication. Use the service connector's authentication flow when required.

A stdio service describes one command, with shell-style quoting for arguments:

---
description: Retrieve material from a local knowledge service.
transport: stdio
target: uvx example-mcp-server
env:
  - API_TOKEN
---

env lists variable names, not assignments. Those variables must exist in the selected agent environment. The connector supplies their values to service operations; a missing name fails when the connection is prepared. The stdio target is split into arguments with shell-style quoting; shell operators and $VARIABLE expansion are not evaluated by Toolang.

Prompt files

Summarize {{_}} for {{audience}}.

Frontmatter is optional. The body is the template. {{_}} refers to primary input; other root placeholder names declare named text arguments. Invoke an available prompt at the beginning of a content line:

$summarize audience=developers -- Explain the proposed change.

A bare {{input}} is a named argument called input; it is not the special primary-input placeholder. Other prompt metadata has no format-specific schema; a supplied name must match the filename stem.

All free named placeholders are required text arguments. Use name=value assignments with shell-style quoting; unknown or duplicate arguments fail. -- TEXT supplies same-line primary input, - captures the remaining content, and --- captures content through a closing line containing exactly ---. The fenced form is available to prompt calls only. A Markdown code fence keeps $PROMPT and @file lines literal.

Validation examples

Chore files

Chores are current definitions in the agent home's chores/ directory. The filename stem is the case-sensitive chore name, addressed as chore/NAME. Inline .too declarations use the same title, schedule, and work text; see Grammar.

Markdown format

A chore without a schedule runs once for each body revision:

---
title: Review API changes
---
 
Review the API changes and summarize actionable findings.

Add an explicit RRULE for recurring work:

---
title: Check stale pull requests
schedule: FREQ=HOURLY;INTERVAL=6
---
 
Check stale pull requests and report actionable changes.

Frontmatter

Only title and schedule are interpreted from chore frontmatter. Other metadata is preserved but does not configure execution. Names cannot contain path separators or surrounding whitespace. Markdown names are case-sensitive and allow more characters than inline .too declaration names.

The body supplies the work instruction. The name and agent determine the runtime ID; it is not an authored frontmatter field. Editing the title, body, schedule, or location preserves identity when the name stays the same. Renaming the chore changes its identity.

A plain RRULE uses a UTC anchor when the scheduler first observes the definition. Its first scheduled occurrence is strictly after that observation. Changing the schedule resets the anchor; editing only a recurring chore's body does not. For a daily 09:00 UTC schedule, use FREQ=DAILY;BYHOUR=9;BYMINUTE=0;BYSECOND=0. A cron expression is not an RRULE.

Execution status and checkpoints are stored separately. There are no task files, draft/ready/archive directories, or authored state/stage transitions. The Chore driver must be enabled for dispatch. Removing a definition stops future dispatch while preserving history; it does not cancel an active run. Use too alice chore run NAME to request another occurrence and too alice chore cancel NAME to cancel pending or active work. Canceling an occurrence leaves a recurring definition's future schedule in place; remove the definition to stop later scheduled dispatches.

The body is parsed as authored run input. It can start with /model, /allow, /limit, /workdir, or a runnable selection such as /flow:review. File includes resolve relative to the chore definition's directory. Editing only a title does not create another one-off occurrence; body revisions ignore CRLF versus LF and surrounding whitespace.