Defining Sub-Agents, Chat Modes, and AI Actions in Markdown
Instead of using an action JSON file and a separate prompt file, you can define a sub-agent, a chat mode, or an AI action in a single Markdown file.
Place the Markdown file in one of the AI action folders configured in the Installation and Configuration page. The file begins with a YAML front matter block that names the item and describes it, followed by the prompt that instructs the AI.
The output-action and visibility
keys of the front matter decide what the file defines:
| To define | output-action |
visibility |
Where it is available |
|---|---|---|---|
| A sub-agent | Not set (agentic) |
Not set (visible-only-for-tools) |
Only to AI agents that delegate work. |
| A chat mode | Not set (agentic) |
visible |
In the Chat modes drop-down menu, and to AI agents that delegate work. |
| An AI action | replace, insert, none, or
create-new-document |
visible |
In the Actions drop-down menu, and to AI agents that invoke actions. |
Example: A Sub-Agent
---
name: Style Reviewer
description: Reviews a topic against the documentation style guide and reports what should be changed. Use it before a topic is published.
tools: get_document_content, grep_project, search_project_resources
---
You are a documentation reviewer.
Read the topic you are given and check it against the style guide of the project. Report
what should be changed and why. Do not edit the document yourself.A sub-agent does not appear in the Chat
modes drop-down menu. Instead, it is available to AI agents that delegate
work, such as the Agent, DITA Agent,
Dev Agent, Planner, and
Personas chat modes. These agents discover the sub-agent through
its description and invoke it using the invoke_ai_agent
tool.
Example: A Chat Mode
visibility to visible
turns the same kind of file into a chat mode that you can select in the Chat
modes drop-down menu of the Chat
view:---
name: Release Notes Writer
description: Writes release notes from the change descriptions you provide, following the release notes conventions of the project.
visibility: visible
tools: get_document_content, search_project_resources, list_dir, edit_document
---
You are a technical writer who prepares release notes.
Find the release notes of the previous versions in the project and follow their structure
and tone. Group the changes into new features, improvements, and bug fixes. Describe each
change from the point of view of the user, in one or two sentences.The chat mode is placed in the same category as the built-in
chat modes. Like the built-in chat modes, it receives details about the application, the
project, and the opened documents: the ${applicationContext} editor
variable is appended to the prompt, unless the prompt already contains it. To show the
chat mode in the drop-down menu without also offering it to the agents that delegate work,
set visibility to visible-only-in-ui.
Example: An AI Action
output-action to a value other than
agentic defines an AI action that is applied to the selected content,
just like the actions defined in JSON
files:---
name: Shorten Sentences
description: Rewrites the selected content using shorter, simpler sentences.
output-action: replace
visibility: visible
tools:
---
Rewrite the content you receive so that no sentence is longer than 20 words. Split long
sentences rather than dropping information. Keep the XML markup unchanged and respond only
with the rewritten content.The action appears in the Actions
drop-down menu, in the Other category. The
output-action key takes the same values as the output-action property of an AI action defined in JSON. For
example, replace proposes to replace the selection with the response,
while none only shows the response in the Chat view.
tools key in the example is
intentional. Without it, the action would inherit the tools of the built-in
Agent chat mode, including those that edit documents. A simple
action that transforms the selection usually needs no tools.Front Matter Keys
- name
- (Required) The name of the sub-agent, chat mode, or action. It is presented in the
UI and to the AI agents that invoke it, and it is used to compute its ID: the name
in lowercase, with blanks replaced by dashes, after the
agent.prefix (for example,agent.style-reviewerfor the sub-agent in the first example). If two definitions produce the same ID, only the first is loaded, and the others are reported in the application log. - description
- (Required) Describes when to use the item. An AI agent reads this description when choosing from the available sub-agents and actions, so describe the purpose rather than how it works. For chat modes and actions, it is also shown in the UI.
- tools
-
(Optional) Specifies the tools that may be called. List the tools either on one line, separated by commas, or as a YAML list. If this key is missing, the item inherits the tools of the built-in Agent chat mode, except for tools that invoke agents. This prevents a sub-agent from delegating to itself. Declaring the key without specifying a tool gives no tools. An item that does not declare the key also gets the tools contributed by other plugins and add-ons, while one that declares it gets only the tools it lists.
- model
- (Optional) The ID of the model to run with. By default, a sub-agent runs with the model used by the conversation that invoked it.
- output-action
- (Optional) Takes the same values as the
output-actionproperty of an AI action. The default isagentic, which defines a sub-agent or a chat mode. Any other value defines an AI action. - visibility
- (Optional) Accepts the following values:The default value is
- visible
- Appears in the UI and is accessible for tools that invoke actions (e.g.
invoke_ai_agentorinvoke_ai_action). - visible-only-in-ui
- Appears in the UI but cannot be invoked by tools.
- visible-only-for-tools
- Does not appear in the UI but can be invoked by tools.
- hidden
- Does not appear in the UI and cannot be invoked by tools.
visible-only-for-tools, which defines a sub-agent. An unknown value is reported in the application log and the default is used instead. - profile
- (Optional) Restricts the item to certain applications. It accepts a
comma-separated list of application types, such as
xml_editor, xml_developer, with the same values as theprofileproperty of an AI action defined in JSON.
Other Markdown Files in the Actions Folders
A Markdown file in the AI action
folders is loaded as a sub-agent, chat mode, or action only if it contains a front matter
with both the name and the description keys. A file named
SKILL.md is a skill, and a file without front matter is an ordinary prompt referenced by an
action through its prompt_ref property.