# description
An agent definition specifying model, tools, and behavioral configuration.

# $comment
An agent is a directory containing an `AGENT.md` file with YAML frontmatter and an optional
Markdown body providing system instructions. Agents are discovered from two locations:
workspace `.stencila/agents/` and user config `~/.config/stencila/agents/`.

# properties.type.$comment
This is a special property analogous to JSON-LD's `@type` keyword.

# properties.id.$comment
This is a special property analogous to JSON-LD's `@id` keyword.

# properties.identifiers.description
Any kind of identifier for any kind of Thing.

# properties.identifiers.$comment
Some identifiers have specific properties e.g the `issn` property for
the `Periodical` type. These should be used in preference to this
property which is intended for identifiers that do not yet have a
specific property. Identifiers can be represented as strings, but
using a `PropertyValue` will usually be better because it allows
for `propertyID` (i.e. the type of identifier).

# properties.name.$comment
Must be lowercase kebab-case: 1-64 characters, only lowercase alphanumeric
and hyphens, no leading/trailing/consecutive hyphens. By convention, names
follow a `thing-role` pattern describing the agent's domain and function,
e.g. `code-engineer`, `code-reviewer`, `data-analyst`, `site-designer`.

# properties.workType.description
The type of `CreativeWork` (e.g. article, book, software application).

# properties.doi.description
The work's Digital Object Identifier (https://doi.org/).

# properties.about.$comment
Consistent with https://schema.org/about, this property allows for
linking to one of more `Thing` nodes. This could for example include
a `Person` (e.g for a bibliography) or a `DefinedTerm` (e.g. for
subject areas the creative work relates to).

# properties.abstract.description
A short description that summarizes a `CreativeWork`.

# properties.provenance.description
A summary of the provenance of the content within the work.

# properties.contributors.description
A secondary contributor to the `CreativeWork`.

# properties.editors.$comment
Note that, consistent with schema.org, this property can only include
a `Person`, unlike `authors` and `maintainers` which can also include
`Organization`.

# properties.maintainers.$comment
A maintainer of a `Dataset`, `SoftwareApplication`, or other `CreativeWork`.
A maintainer is a `Person` or `Organization` that manages contributions to,
and/or publication of, some (typically complex) artifact. It is common for
distributions of software and data to be based on "upstream" sources.
When maintainer is applied to a specific version of something e.g. a particular
version or packaging of a Dataset, it is always possible that the upstream
source has a different maintainer. The `isBasedOn` property can be used to
indicate such relationships between datasets to make the different maintenance
roles clear. Similarly in the case of software, a package may have dedicated
maintainers working on integration into software distributions such as Ubuntu,
as well as upstream maintainers of the underlying work.

# properties.dateAccepted.$comment
This is not yet a schema.org property but the term is used
[in Dublin Core](http://purl.org/dc/terms/dateAccepted).

# properties.funders.description
People or organizations that funded the `CreativeWork`.

# properties.fundedBy.description
Grants that funded the `CreativeWork`; reverse of `fundedItems`.

# properties.fundedBy.$comment
This follows the proposal [here](https://github.com/schemaorg/schemaorg/issues/2258)
for a property that is the reverse of `fundedItems`.
It is an any because a `CreativeWork` may have been funded through more than
one `Grant`.

# properties.genre.description
Genre of the creative work, broadcast channel or group.

# properties.keywords.description
Keywords or tags used to describe this content. Multiple entries in a keywords list are typically delimited by commas.

# properties.isPartOf.description
An item or other CreativeWork that this CreativeWork is a part of.

# properties.licenses.description
License documents that applies to this content, typically indicated by URL, but may be a `CreativeWork` itself.

# properties.parts.description
Elements of the collection which can be a variety of different elements, such as Articles, Datatables, Tables and more.

# properties.bibliography.description
A bibliography of references which may be cited in the work.

# properties.bibliography.$comment
Unlike `references` which contains only the references that are actually
cited in the work, `bibliography` is a database of all available references
loaded from an external source file at compile time. It is ephemeral and
not persisted when the document is saved.

# properties.references.description
References to other creative works, such as another publication, web page, scholarly article, etc.

# properties.text.description
The textual content of this creative work.

# properties.repository.description
URL of the repository where the un-compiled, human readable source of the work is located.

# properties.path.description
The file system path of the source of the work.

# properties.path.$comment
Usually only used when the work is within a Git (or other version control) repository,
and then is usually relative to the repository root.

# properties.commit.description
The commit hash (or similar) of the source of the work.

# properties.commit.$comment
Only used when the work's source file is within a Git (or other version control) repository.

# properties.version.$comment
In this case `string` is listed as an alternative before `number` to
avoid semantic version numbers e.g. `1.0` being parsed, and subsequently
encoded, as `1` thereby resulting in loss of information.

# properties.whenToUse.description
Positive selection signals describing when this agent should be used.

# properties.whenNotToUse.description
Negative selection signals describing when this agent should not be used.

# properties.content.description
The content of the agent (the Markdown body providing system instructions).

# properties.content.$comment
The Markdown body after the frontmatter contains the agent's system instructions.
This is optional — an agent may be configuration-only with no instructions.

# properties.models.$comment
One or more models to use, e.g. "claude-sonnet-4-5", "gpt-5.2-codex". When not
specified, the default model for the provider is used. Accepts a single string
or an array of strings.

# properties.providers.$comment
One or more providers to use, e.g. "anthropic", "openai", "gemini". When not
specified, the first available provider is used. Accepts a single string or an
array of strings.

# properties.modelSize.$comment
Preferred model size tier, e.g. "small", "medium", "large". Used for model
selection when an exact model is not specified.

# properties.reasoningEffort.$comment
Valid values are "low", "medium", "high", or a custom provider-specific value.
When not specified, the provider's default is used.

# properties.historyThinkingReplay.description
Whether to replay assistant thinking and reasoning in conversation history.

# properties.historyThinkingReplay.$comment
Controls whether chain-of-thought content (both provider-specific thinking parts
and reasoning text) is included when replaying assistant turns in subsequent requests.
- "none" (default): strip all thinking and reasoning from history, saving context space.
- "full": replay thinking and reasoning content as-is.

# properties.truncationPreset.description
Named preset for tool output truncation limits.

# properties.truncationPreset.$comment
Controls how aggressively tool outputs are truncated before being included
in the conversation context.
- "strict": tighter limits, preserves more context budget for conversation.
- "balanced" (default): moderate limits suitable for most agents.
- "verbose": no additional truncation beyond spec defaults.

# properties.compactionTriggerPercent.description
Context usage percentage that triggers proactive history compaction.

# properties.compactionTriggerPercent.$comment
When estimated context usage exceeds this percentage of the model's context
window, the agent proactively compacts conversation history (stripping
thinking blocks, summarizing old tool results, dropping oldest turns).
Set to 0 to disable proactive compaction. Defaults to 70.

# properties.trustLevel.description
Trust level controlling how strictly the agent's operations are guarded.

# properties.trustLevel.$comment
Controls tool guard behavior across shell, file, and web tools.
- "low": default-deny for shell; strictest rules for file and web.
- "medium" (default): default-allow with destructive behavior blocking.
- "high": default-allow with relaxed blocking.
When not specified, defaults to "medium" at guard construction time.

# properties.allowedSkills.$comment
When unset, all discovered skills are available to the agent.
When set to a non-empty array, only the listed skills are available.
When set to an empty array, skills are disabled entirely (no discovery or registration).

# properties.allowedDomains.$comment
Supports exact hosts and `*.` wildcard subdomain entries.
If set, domains not in this list are denied.
If both allowedDomains and disallowedDomains are set, allowlist wins.

# properties.disallowedDomains.$comment
Supports exact hosts and `*.` wildcard subdomain entries.
If set without allowedDomains, matching domains are denied.
If both allowedDomains and disallowedDomains are set, allowlist wins.

# properties.enableMcpCodemode.description
Whether to enable MCP codemode orchestration.

# properties.allowedMcpServers.description
MCP server IDs this agent is allowed to use.

# properties.allowedMcpServers.$comment
When unset, all discovered and connected MCP servers are available.
When set, only the listed server IDs are used — other servers are
ignored even if connected. This supports the principle of least
privilege: agents should only have access to the MCP servers they
actually need.

# properties.maxTurns.description
Maximum conversation turns (0 = unlimited).

# properties.toolTimeout.description
Default timeout for tool execution in seconds.

# properties.maxToolRounds.description
Maximum tool-call rounds per user input.

# properties.compatibility.$comment
Max 500 characters. Indicates intended product, required system packages,
network access needs, etc. Most agents do not need this field.