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.

Instruction groups between # >>> generated: and # <<< end generated: comments are generated. The gitlab-ai-principles-distiller copies their content from the matching distilled principle, so the automated review applies the same standards as the authoring and editing files. A daily scheduled job regenerates these groups after a distilled principle changes on the default branch, so do not edit them by hand. Groups outside those comments are maintained by hand. For more information, see AI instruction files review.

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.

Before you request a review, check the content to resolve common quality issues in 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 in the gitlab project only. The gitlab-ai-principles-distiller is not configured for any other project that publishes documentation to docs.gitlab.com.

The generated groups in .gitlab/duo/mr-review-instructions.yaml are regenerated from the same distilled files, so a style guide change reaches the automated review without a separate edit. Do not update those groups 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 AI instruction file like AGENTS.md, conversations must be restarted for changes to take effect. Existing conversations do not pick up changes automatically.