Practical Steps for Vibe Authoring with AI Positron

1 Nov 2025

Read time: 19 minute(s)

We initially started work on the AI Positron add-on for Oxygen XML Editor more than 2 years ago by creating useful AI actions to improve readability of content, correct grammar, translate, proofread, and so on. Gradually, we realized that even when invoking our carefully made prompts wrapped as such AI actions, you need flexibility to discuss with the AI further about results. So we added support to create custom AI actions specific to your needs. Such AI actions, based on prompts tuned by our or your experts, continue to be useful for precise use cases and for people who are just starting to use AI tools.

In time, we also started to explore and expand the capabilities of using chat to converse with the AI, attach all sorts of file types (PDF, Word, Markdown, images) to create documentation drafts, explore, and make changes in the current project.

The chat view in any AI Assistant application like AI Positron is the new console; you use it to direct the AI, affect changes, preview them, and refine until you have a working draft. You remain in control of a powerful and imperfect tool. As before, in the past, computers have moved writing and coding to a higher level of abstraction.

Vibe Authoring

I would define the Vibe Authoring support in the AI Positron add-on as a feature that allows you to:

Define a project context prompt which gives the AI models general information about your project, important style guide, terminology, and structure rules.
Chat with the AI to explore the current project's contents or to affect changes in the project. All changes made by the AI can be viewed and reverted if necessary.
Connect Model Context Protocol servers to provide tools that integrate AI Positron with other data sources in your company (for example, ticketing system, issues list, etc.).

Novice to Expert

If one were to attempt to divide people into novices and experts, they would soon figure out that each of us is a novice in certain fields and an expert in others.

As novices, we use out-of-the-box tools and frameworks with a minimum of customization to obtain poor results. We cannot explain either when the tool does not work or when it does. When we do not obtain quality content as novices, we blame the tools.

In time, by reading, writing, and making mistakes, we evolve to understand the tools and frameworks we use. Taking some time to understand these tools and to customize them gives us better and more consistent results.

This article is an attempt to give you a better understanding of how the Oxygen XML Editor AI Positron add-on works and how it can be customized to maximize the quality of your vibe authoring interactions.

I am not of the opinion that we must consider using AI tools for all our daily work; our brains need the effort and work we put into writing in order to better understand the task at hand. There are still many activities that can be accomplished more quickly and with sufficient quality (generating drafts, improving content quality) by using AI tools in a controlled manner.

Use a Version Control System

You need to view and revert changes made by the AI, to keep a history of past changes in your project. You also need to collaboratively work with other people or with AI agents, create separate branches for working on features, keep your content secure, and eventually publish it.

So a version control system for your project, like Git or a commercial CCMS, is a must.

Oxygen XML Editor's free Git client add-on is a great tool which gives technical documentation writers just about every feature needed to work with Git projects: support to pull, make changes, preview them, push, a useful History side view, switch branches, and stash changes.

Using Git For Technical Writing

Set up Your Project Context Prompt

LLM Models have a limited context window and start out not knowing anything about the intricacies of your current documentation project. They can use tools to explore your project's structure, but it's more efficient to create a project context prompt which becomes part of each invoked AI action and chat conversation.

Customizing AI Positron for Your DITA XML Project.

The project context prompt contains an overview of your project's intention, structure, rules, and style guide. It must be kept as short and informative as possible. In the AI Positron Preferences page, one can specify the entire project context prompt either directly or referenced as a separate file which may reside in your project.

The most recent AI Positron release added a new AI action named Generate agent instructions which can help you create the initial project context prompt content.

Examples of project context prompt files for AI Positron in Markdown format:

Choose your LLM Model

You need a quality LLM model to make quality changes. An LLM model which is both efficient, cost-effective, and has a high context window. From our extensive testing and experience, we generally recommend OpenAI GPT 4.1, Claude Sonet 4, Haiku 4.5, or Gemini 2.5 Flash.

Context is the key here. The LLM receives a project context prompt, but it also needs to explore the project, read content, and make changes. So your LLM implementation and the platform through which you access it also need to allow tool calling. Most quality LLM models like the ones above also have vision support to read images and create, for example, documentation drafts based on screenshots or to generate alternate text for screenshots in the user's guide.

Choose the Chat Mode

AI Positron comes with three chat modes predefined:

DITA Agent - Agentic mode which makes changes in a DITA XML project, comes with a predefined system prompt which instructs the LLM about the base requirements of working in a DITA XML project and a minimal style guide of rules. It has access to general tools to explore the project and make changes, but also to DITA XML specific tools to obtain the structure of the DITA Map opened in the DITA Maps Manager view, resolve a content reference to the referenced content, or to find key definitions which match a specific product name. For example, you can run prompts like this in the chat view:
```
Replace in the current file all product names with 
defined key references
```
or:
```
Use the attached documents to create a DITA XML topic, 
add related links in the topic to similar ones, find 
a good place and insert it in the DITA Map
```
Figure 1. Example: Create a new DITA XML topic from a PDF document

or:
```
Add related links in the current topic to similar topics 
from the project
```
Figure 2. Example: Add related links to topic
Agent - Generic agent useful for exploring and making changes to a variety of projects.
Ask - Read-only agent useful to explore and make plans without making actual changes until you switch to one of the other agents.

Each defined agent has a system prompt and references a set of tools which can be used by the LLM. You can define your own agents and have them appear in the Chat view. A general overview of the tools available to these agentic chat modes is available below.

General Overview of Available Tools

AI Positron comes bundled with a variety of tools which are offered to the LLM in order to explore and make changes to content. Here are some of the categories of available tools along with prompts you can test for yourself in the AI Positron chat view:

Tools to explore the overall project. The chat modes have access to:
- Tool which can perform keyword search in the project. For example, you can ask it:
```
Find topics about Git Push in the project 
and give me an overview of the most suitable ones.
```
  Note:
  This tool relies on the indexing capabilities of Oxygen XML Editor. If you are working with DITA Maps opened from remote storage systems like CMSs, in the Preferences->Open/Find Resource page you should check the Enable indexing for remote resources checkbox.
- Grep and perform exact string matches in the project, even by matching inside specific XML elements. For example:
```
Find places where the Save action is mentioned 
in DITA <uicontrol> elements.
```
  Note:
  This tool is available only when working with local disk resources. In such a case, you should create a project in the Oxygen XML Editor Project view for your specific project folders.
- Explore the project folder structure. For example:
```
Where should I save DITA maps in this project?
```
  Note:
  This tool is available only when working with local disk resources.
Tools to read content from the current or a different file. Example:
```
Give me suggestions about how to shorten the current document
contents.
```
Tools to make large or small changes to the current or to other documents. Examples:
```
Shorten the title of the current document
```
or:
```
Find and fix logical inconsistencies in the current document
```
Tools to provide validation and terminology problems reported for certain documents. If you have many style guide rules, it is advisable to implement them as Schematron rules or rules for the Oxygen XML Editor Terminology Checker add-on. Once you implement the checks, you can simply ask the AI:
```
Fix validation and terminology problems in the generated content before saving it to disk.
```
Tools to make XML-aware changes in documents:
- Apply existing XML refactoring operations on documents. Example:
```
Invoke XML refactor operation to add unique IDs on all pargraphs
```
- Apply XML refactoring using XSLT scripts created by the AI. Example:
```
Invoke XML refactor with custom XSLT to 
replace all <b> elements with <uicontrol>
```
  Figure 3. Example: Use Custom XSLT to Refactor

Tools to call existing AI actions on documents. Example:

Invoke the Proofread AI action on the current 
document content, then save the proposed changes 
to the document

or:

Invoke the improve readability AI action on the current 
document content, then save the proposed changes 
to the document

Add Extra Tools with Model Context Protocol

The Model Context Protocol Preferences page in AI Positron allows you to connect to various MCP servers and allow the LLM to call tools implemented on remote or local servers.

Sample configurations can be found in the Oxygen XML Editor user's manual.

Model Context Protocol gives AI Positron the ability to provide for the LLM close integrations with the issue tracking system or the version control system, for example, to allow the LLM to extract the summary and comments made on a GitHub issue and create a draft documentation topic from it. Example prompt:

Obtain description and comments from the DITA OT GitHub issue number 2021 and create a draft documentation 
topic using them

Figure 4. Example: Using MCP to access Atlassian JIRA

Figure 5. Example: Using MCP to access GitHub issues

The entire set of tools provided by AI Positron can also be provided to external AI Assistants by starting the entire Oxygen XML Editor application as a local MCP server.

Figure 6. Oxygen XML Editor as local MCP server

Conclusion

Obtaining quality output and advice from the LLM, making accurate changes using it, is all about the application giving the LLM enough context and allowing it to find extra context if the need arises.

Starting with the use of quality LLMs, combined with a well-created and distilled project context prompt, then continuing with tools that give the LLM access to explore the project and make consistent changes, your short prompts and commands end up being properly interpreted and acted upon.