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 CI/CD 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.

Troubleshooting

Error: Duo review instruction fences need attention

You might get an error in the ai-duo-review-instructions CI/CD job that lists a fence as Stale. This error occurs when the metadata in a generated group in .gitlab/duo/mr-review-instructions.yaml no longer matches its distilled principle file. The job fails on stale fences only in merge requests that change .gitlab/duo/mr-review-instructions.yaml, the gitlab-ai-principles-distiller gem, or scripts/lint-duo-review-instructions.sh.

Retrying the failed job does not resolve the error, because the job checks the same commit.

If your branch does not change the distilled principles, the fences are stale on the default branch. To resolve this error, reconcile the fences on the default branch:

1. Wait for the reconcile merge request from the docs-sync/principles-reconcile-fences branch to merge. The ai-principles-reconcile-fences job opens or updates this merge request after a distilled principle changes on the default branch.
2. If no reconcile merge request is open, run the manual ai-principles-reconcile-fences job in the latest default branch pipeline. To run the job, you must have merge permissions for the default branch. If you do not have these permissions, ask a maintainer to run it. If the job does not open a merge request, the fences on the default branch are up to date. In that case, the stale fence comes from your branch.
3. Rebase your branch on the default branch.

If the stale fence comes from changes on your branch, regenerate the fences on your branch:

1. From the repository root, run:

   shell

   bundle exec ruby gems/gitlab-ai-principles-distiller/bin/gitlab-ai-principles-distiller-sync reconcile-fences --workspace .

2. Check that the fences are up to date:

   shell

   scripts/lint-duo-review-instructions.sh

3. Commit and push the updated .gitlab/duo/mr-review-instructions.yaml file.

Do not pass --push to reconcile-fences. That option opens a separate reconcile merge request instead of updating your branch.