Conventions: one metadata contract for everything.
Every GoTo-managed object — workspace, agent, skill, activity, task, reference doc — is a markdown file with YAML frontmatter, and the frontmatter follows one metadata contract. Learn it once and every object in the system reads the same way.
The four fields
name: web-research
display_name: Web Research
tagline: Look things up and cite sources.
description: Use when a question needs current or external information
the agent doesn't already have.| Field | For | Rules |
|---|---|---|
name | Machines: filenames, URLs, references, routing, inheritance, API calls. | Stable identity. Kebab-case: ^[a-z0-9]+(-[a-z0-9]+)*$ |
display_name | Humans: UI labels. | Spaces, punctuation, branding welcome. |
tagline | Humans: lists, cards, pickers — answers "what do I do?" | One short line. |
description | Agents: when/why to use, invoke, or delegate to this object. | Write it for the model deciding whether to engage. |
The subtle one is description: it's agent-facing semantic
text, not documentation. Across skills, reference docs, tasks, and
exposures, the description is what triggers progressive disclosure — the
system's behavior is only as good as these one-liners.
Markdown + frontmatter, via one parser
All object files are parsed and serialized through
core/file_parser.py — never hand-rolled string manipulation.
That single path is what keeps the format stable enough to be a public
contract: your files, other tools' files, and generated defaults all round-trip
identically. Unknown frontmatter keys pass through untouched, which is how
application-specific metadata (tags, flags) works without schema machinery.
Ecosystem alignment
- Skills: the Agent Skills standard field set, with GTA extras under
metadata:. - Project instructions:
GOTOAGENTS.md, mirroring the AGENTS.md convention. - Memory:
MEMORY.md, the convention models are trained to maintain.
Where it lives
core/file_parser.py— the parse/serialize path.help/object-metadata.mdin the repo — the full design contract, including migration guidance.