Docs: Add AGENTS.md documentation and unified custom instructions overview for GitLab Duo

Summary

AGENTS.md support was implemented in gitlab-lsp (MR !2597 (merged), December 2025) and works with IDEs and Duo CLI, but no user-facing documentation exists for this feature. Additionally, GitLab Duo's custom instructions capabilities are documented in silos, causing user confusion about which configuration file to use.

Note: Documentation MR !214888 exists in draft state and is approved by Technical Writing, but is blocked by merge conflicts and missing IDE extension version numbers. This issue tracks the broader documentation gap and can serve as a parent for that work.

Problem Statement

User Impact

  1. AGENTS.md is undiscoverable: Users cannot find or use this shipped feature because it's only documented in the LSP repository
  2. Fragmented documentation: Users must navigate multiple pages to understand customization options:
    • .gitlab/duo/chat-rules.md - IDE Chat behavior (documented)
    • .gitlab/duo/mr-review-instructions.yaml - Code Review (documented)
    • AGENTS.md - Project-level agent instructions (NOT documented)
  3. Unclear relationships: No docs explain how AGENTS.md differs from chat-rules.md or precedence rules
  4. Missing multi-level support docs: Users don't know about global (~/.gitlab/duo/AGENTS.md) or nested subdirectory support for monorepos

Current Implementation Details

Supported AGENTS.md Locations

Level Location Behavior
Global/User ~/.gitlab/duo/AGENTS.md or $GLAB_CONFIG_DIR/AGENTS.md Always loaded, applies to all projects
Workspace Root <repo-root>/AGENTS.md Loaded for IDE workspace folders
Nested/Subdirectory <any-dir>/AGENTS.md CLI searches upward from cwd; monorepo support

Precedence Rules

  1. User-level chat rules (~/.gitlab/duo/chat-rules.md)
  2. AGENTS.md files (global → workspace → discovered)
  3. Workspace-level chat rules (.gitlab/duo/chat-rules.md)

Supported Environments

  • ✅ VS Code (GitLab Workflow extension v6.60+)
  • ✅ JetBrains IDEs (GitLab plugin)
  • ✅ Visual Studio (GitLab extension)
  • ✅ Duo CLI
  • ⏳ Remote flows (Fix Pipeline, Duo Developer) - In progress

Proposed Documentation

1. AGENTS.md Documentation Page (P1)

Create documentation covering:

  • File locations (global, workspace, nested)
  • File format and syntax (following agents.md specification)
  • Multi-level resolution and precedence rules
  • Supported environments with version requirements
  • Example configurations
  • Relationship to and differences from chat-rules.md

2. Unified "Customizing GitLab Duo" Overview Page (P1)

Create a landing page with:

  • Overview of all customization options
  • Decision matrix for which file to use when
  • Links to detailed docs for each option
  • Comparison table (AGENTS.md vs chat-rules.md vs mr-review-instructions.yaml)

3. Duo CLI Documentation Update (P2)

Update CLI docs to reference AGENTS.md support and global file location.

Acceptance Criteria

  • New documentation page for AGENTS.md file format and usage
  • Document all three AGENTS.md levels (global, workspace, nested)
  • New "Customizing GitLab Duo" overview page linking all customization options
  • Clear explanation of differences between AGENTS.md and chat-rules.md
  • Documentation of precedence rules when multiple config files exist
  • Practical example configurations for AGENTS.md
  • Duo CLI documentation updated to mention AGENTS.md support
  • Cross-links added between related documentation pages
  • IDE extension version requirements documented

References

Implementation

Reference URL Status
gitlab-lsp MR !2597 (merged) gitlab-org/editor-extensions/gitlab-lsp!2597 (merged) ✅ Merged (Dec 1, 2025)
gitlab-lsp Issue #1730 (closed) gitlab-org/editor-extensions/gitlab-lsp#1730 (closed) ✅ Closed
Documentation MR !214888 !214888 ⏳ Draft (approved by TW, blocked)

Related Issues

Issue Title Relevance
#581211 Docs: Agent Platform GA Parent documentation effort
#583458 Best practices for organizing GitLab-maintained agents and flows Related guidance
ai-assist#1509 Implement usage of Agents.md in Flows Remote flows support (in progress)

Existing Documentation

Documentation Preview

Edited by 🤖 GitLab Bot 🤖