AI agent instruction files for documentation

Two separate systems apply instruction files to documentation, at different stages of the workflow:

• Authoring and editing files are read by an AI agent running locally, such as in your IDE, to write or edit documentation in the gitlab/doc directory.
• Automated review files are read by GitLab Duo Code Review, which runs on the GitLab platform after you push a merge request.

The documentation style guide is the single source of truth for documentation standards. The authoring and editing files either point to the style guide or are generated from it. To change the standards, update the style guide rather than the files themselves.

Authoring and editing files

The following files apply when an agent writes or edits documentation locally:

.ai/code-review.md and .ai/merge-requests.md are general files used for all changes, not just documentation. Only the sections and checklists noted in the above table apply to a documentation merge request.

For more information about how all instruction files are organized and loaded, see the .ai/README.md.

Automated review file

.gitlab/duo/mr-review-instructions.yaml configures GitLab Duo Code Review. After you push a merge request, the review checks the changed files against these instructions.

The instructions that apply to documentation check for:

• Documentation style: American English, active voice, sentence case, no marketing language, screenshot sizing and naming, and similar style rules.
• API documentation: REST-specific requirements such as cURL examples and attribute tables.
• General standards that apply to all files, such as inclusive language.

Unlike the authoring and editing files, this file is manually maintained. It does not read the distilled principles file. It links to the style guide and the word list for the authoritative standards.

Create documentation with an agent

The authoring and editing files are applied automatically when you start a new conversation with a local AI agent, such as GitLab Duo Chat or Claude Code. You do not need to reference them in your prompt. To get the best results:

• Start a new conversation before you begin a documentation task.
• Make changes locally only. Do not commit or push AI-generated content before you have reviewed and iterated on the output.

Review AI-generated content

Before you request a review, check for the following known issues with AI-generated content:

• Repetition: Content that restates what has already been said on the page or in a linked topic.
• Vague or unverifiable claims: Descriptions of how a feature works that are not grounded in the codebase or existing documentation. If you are unsure, Technical Writers can help identify a location in the documentation.
• Style guide adherence: Terms, grammar, and formatting that do not align with the style guide.

For more information, see AI-generated content.

Update the review files

The style guide is the single source of truth. To change the documentation standards that agents follow, update the documentation style guide instead of the authoring and editing files. The gitlab-ai-principles-distiller automatically regenerates the following distilled documentation files from the style guide and the related documentation development pages they’re distilled from:

• documentation.md,
• documentation-topics.md
• documentation-api.md
• documentation-feature-lifecycle.md

These files are used gitlab project only. The gitlab-ai-principles-distiller is not configured for any other project that publishes documentation to docs.gitlab.com.

The automated review file .gitlab/duo/mr-review-instructions.yaml is not regenerated from the style guide. If a standard in the style guide also belongs in automated review, update the Documentation or API documentation group in that file by hand.

If you notice a recurring pattern in AI-generated content that the style guide does not address, open a merge request to add guidance. When you add guidance, follow these principles:

• Keep instructions specific and actionable. Avoid vague guidance like Write concisely.
• Use examples when an instruction requires judgment. Instead of Avoid marketing language, provide an example: Avoid marketing language. For example, do not use "powerful" or "seamless".
• Test your changes. Start a new conversation and ensure the instruction is applied.
• If you update an entry point such as AGENTS.md, conversations must be restarted for changes to take effect. Existing conversations do not pick up changes automatically.