Customizing GitLab Duo Agent Platform: Chat rules, prompts, and workflows

Welcome to Part 8 of our eight-part guide, Getting started with GitLab Duo Agent Platform, where you'll master building and deploying AI agents and workflows within your development lifecycle. Follow tutorials that take you from your first interaction to production-ready automation workflows with full customization.

In this article:

• Introduction to customization
• Custom rules
• AGENTS.md
• Custom review instructions
• Agent Skills
• MCP configuration
• Custom agents and flows

🎯 Try GitLab Duo Agent Platform today!

Introduction to customization

GitLab Duo Agent Platform delivers powerful capabilities right away, and you can unlock even greater value by tailoring it to your team's specific needs. GitLab offers several customization methods across user, workspace, and project levels. For the full matrix of methods and where they apply (Chat, agents, flows, Code Review), see the Customize GitLab Duo Agent Platform overview.

Custom rules

Custom rules let you set personal preferences and team standards that guide how GitLab Duo Chat, agents, flows, and the GitLab Duo CLI behave — for example, coding style, documentation conventions, or how tests should be written.

Custom rules are available on all supported platforms. For the exact list of supported features (Chat, agents, flows, CLI) and version requirements, see the Custom rules documentation.

User-level custom rules

User-level rules apply to all your projects. They apply in your local environment (editor extensions and GitLab Duo CLI). For details on where they are honored and all supported locations (including environment variables), refer to Create user-level custom rules.

For detailed instructions on creating user-level custom rules, see the GitLab documentation.

Create the file ~/.gitlab/duo/chat-rules.md in your home directory.

Example rules:

      - Always use TypeScript for new code, never JavaScript
- Include JSDoc comments for all functions
- Use single quotes for strings
- Follow the existing code style in the repository
- Write concise explanations, avoid lengthy descriptions
- Suggest tests for any code changes
- Use async/await instead of promises

    

Project-level custom rules

Project rules apply only to a specific project. They override user-level rules for that project. Project rules are defined in .gitlab/duo/chat-rules.md in your project and are consumed by GitLab Duo Chat, agents, and flows for that project — in IDE extensions, the Duo CLI, and the GitLab platform (GitLab 18.11 and later). For the complete behavior, see Create workspace-level custom rules.

Create the file .gitlab/duo/chat-rules.md in your project root.

Example rules for a Vue.js project:

      - Use Vue 3 Composition API with `<script setup>`
- Always include TypeScript types for props
- Use scoped styles with SCSS
- Follow the Slippers UI design system
- Keep components under 300 lines
- Use kebab-case for component names
- Include accessibility attributes (aria-*, role)

    

Best practices for custom rules

• Be specific: "Use single quotes" is better than "follow style guide."
• Prioritize: List most important rules first.
• Team-focused: Rules should reflect your team's standards, not personal preferences.
• Actionable: Rules should be clear enough for an AI agent to follow.
• Maintainable: Update rules when your standards change.
• Avoid conflicts: Don't contradict your codebase's actual style.

Tip: Use Code Owners to manage who approves changes to .gitlab/duo/chat-rules.md.

For a detailed use case tutorial for custom rules, see the Custom rules in GitLab Duo Agentic Chat for greater developer efficiency deep-dive blog post.

Note: Custom rules only apply to new conversations or flows. Existing conversations do not retroactively pick up new or updated rules; see the Custom rules documentation for details.

AGENTS.md for customizing agent behavior

AGENTS.md provides project-specific context — repository structure, architecture documentation, build and test instructions, and directory-specific conventions — that agents use when working in your codebase. Because it follows an industry standard, it also works with non-GitLab AI tools that support the spec, for example, Claude Code as an external agent.

Use AGENTS.md when you need to give agents deeper understanding of your project structure, or when you want the same context to apply across multiple AI tools. Use custom rules when you want to enforce team standards and preferences within GitLab Duo specifically.

User-level (applies to all your projects and workspaces):

• macOS/Linux: ~/.gitlab/duo/AGENTS.md
• Windows: %APPDATA%\GitLab\duo\AGENTS.md

Workspace-level (applies to a specific project):

• Create AGENTS.md in your project root.

Subdirectory-level (applies to specific directories in monorepos):

• Create AGENTS.md in subdirectories for context-specific instructions.

For how AGENTS.md files are combined and discovered across user, project, and repository subdirectory levels, see How GitLab Duo uses AGENTS.md files.

What AGENTS.md controls

• Agent personality and tone
• Project-specific instructions
• Coding standards and conventions
• Tool usage preferences
• Output formatting requirements
• Repository structure and organization

Example AGENTS.md

      # Agent Customization for Our Project
## General Guidelines
- Always prioritize code quality over speed
- Follow our project's architecture patterns
- Reference existing code examples when suggesting changes
- Ask for clarification if requirements are ambiguous
## Code Style
- Use TypeScript for all new code
- Follow ESLint configuration in the project
- Include unit tests for all new functions
- Use descriptive variable names (no single letters except loops)
## Documentation
- Add JSDoc comments to all public functions
- Update README.md if adding new features
- Include examples in code comments
## Security
- Never suggest hardcoding secrets or API keys
- Always validate user input
- Use parameterized queries for database operations
- Flag potential security issues immediately

    

Best practices for AGENTS.md

• Be specific: Include concrete examples from your project.
• Keep it concise: Focus on what's unique to your project.
• Version control: Commit to your repository and track changes.
• Team alignment: Discuss with your team before finalizing.
• Update regularly: Refine as your project evolves.
• Document repository structure: Help agents understand your codebase organization.

Requirements

• GitLab 18.8 or later
• For VS Code: GitLab Workflow extension 6.60 or later
• For JetBrains: GitLab plugin 3.26.0 or later
• For GitLab Duo CLI: version 8.47.0 or later
• For flows: Update your flow configuration to access the user_rule context passed from the executor. See the example in Use AGENTS.md with GitLab Duo.

Learn more about AGENTS.md.

Custom review instructions

Custom review instructions provide specific guidelines for GitLab's AI-powered code review. The instructions ensure consistent code review standards, and can be tailored to specific file types in your project.

Availability depends on how you use it:

• Code Review Flow (Agent Platform) — available on Free, Premium, and Ultimate tiers on GitLab.com, GitLab Self-Managed, and GitLab Dedicated. No Duo add-on required; uses GitLab Credits.
• GitLab Duo Code Review — requires the GitLab Duo Enterprise add-on on Premium and Ultimate tiers.

Create the file .gitlab/duo/mr-review-instructions.yaml in your project root.

Example review instructions:

      instructions:
  - name: Ruby Style Guide
    fileFilters:
      - "*.rb"           # Ruby files in the root directory
      - "lib/**/*.rb"    # Ruby files in lib and its subdirectories
      - "!spec/**/*.rb"  # Exclude test files
    instructions: |
      1. Ensure all methods have proper documentation
      2. Follow Ruby style guide conventions
      3. Prefer symbols over strings for hash keys

  - name: TypeScript Source Files
    fileFilters:
      - "**/*.ts"        # TypeScript files in any directory
      - "!**/*.test.ts"  # Exclude test files
    instructions: |
      1. Ensure proper TypeScript types (avoid 'any')
      2. Follow naming conventions
      3. Document complex functions

    

Best practices for custom review instructions:

• Be specific and actionable: Clear, numbered instructions work best.
• Use glob patterns: Target specific file types with fileFilters.
• Focus on important standards: Prioritize the most critical review points.
• Explain the "why": Help reviewers understand the reasoning.
• Test patterns: Ensure glob patterns match the intended files.

Tip: Use Code Owners to protect changes to .gitlab/duo/mr-review-instructions.yaml.

For the full YAML schema, language-specific examples, and how custom instructions are combined with GitLab Duo's built-in review criteria, see the Custom Review Instructions documentation.

Agent Skills

Agent Skills provide specialized knowledge and workflows for specific agentic tasks, based on the Agent Skills specification. Refer to the documentation for availability and prerequisites.

Skills work at two levels:

• Workspace-level — works with GitLab Duo Chat, foundational and custom flows (excluding Code Review), VS Code, and GitLab Duo CLI. Create SKILL.md files under skills/<skill-name>/ in your repository.
• User-level (experimental) — available exclusively with GitLab Duo CLI (8.83.0 or later). Create SKILL.md files under ~/.gitlab/duo/skills/<skill-name>/ (Linux/macOS) or %APPDATA%\GitLab\duo\skills\<skill-name>\ (Windows). Requires the --enable-global-skills flag or the GITLAB_ENABLE_GLOBAL_SKILLS environment variable.

For the exact file layout, required frontmatter, supported surfaces, and how to wire skills into flows via the workspace_agent_skills context, see the Agent Skills documentation.

MCP configuration

Model Context Protocol (MCP) enables agents to access external systems like Jira, Slack, AWS, and more. This section covers MCP configuration for extending agent capabilities.

🎯 Try it now: Interactive demo of MCP - Explore how to use Model Context Protocol.

MCP configuration for external integrations

Model Context Protocol (MCP) enables agents to access external systems like Jira, Slack, AWS, and more.

Scope: User-level (applies to all workspaces) or Workspace-level (project-specific, overrides user config)

Create user configuration:

• macOS/Linux: ~/.gitlab/duo/mcp.json
• Windows: C:\Users\<username>\AppData\Roaming\GitLab\duo\mcp.json
• VS Code: Run command GitLab MCP: Open User Settings (JSON)

Create workspace configuration:

• Create file: .gitlab/duo/mcp.json in your project root

Best practices:

• Security first: Use MCP servers that require OAuth and not plain-text password tokens.
• Minimal scope: Only enable MCP servers you actually use and trust.
• Test locally: Verify MCP connections and authorization work before sharing across teams.
• Document integrations: Explain what each MCP server provides.
• Version control: Store configuration in .gitlab/duo/mcp.json with Code Owners' approval.

For detailed setup instructions and configuration examples, see Part 7: Model Context Protocol (MCP) Integration.

Custom agents and flows

Custom agents and flows allow you to automate your team's specific workflows. Before diving into customization, it's helpful to understand what they are and how they work. Here are parts of the Getting started with GitLab Duo Agent Platform guide that can help.

• Part 3: Understanding agents — Learn about foundational, custom, and external agents, and when to use each type.
• Part 4: Understanding flows — Discover how flows orchestrate multiple agents to solve complex problems.
• Part 5: AI Catalog — Learn how to discover, create, and share agents and flows across your organization.

Once you understand the basics, this section provides an overview of customization options with links to detailed guides.

System prompts for custom agents

System prompts define an agent's personality, expertise, and behavior. A well-crafted prompt makes agents more effective and aligned with your team's needs.

What are system prompts? System prompts are instructions that tell an agent how to behave, what expertise it has, and how to respond to requests. They're the foundation of custom agent behavior.

Key elements of a strong system prompt:

• Role definition: What the agent is and what it does
• Expertise areas: Specific domains or technologies
• Behavior guidelines: How it should interact and respond
• Output format: Structure of responses
• Constraints: What it should avoid

Best practices:

• Be detailed: More specific prompts produce better results.
• Use examples: Show the agent what good output looks like.
• Define scope: Clearly state what the agent should and shouldn't do.
• Test iteratively: Refine prompts based on agent behavior.
• Version control: Track prompt changes in your repository.

For detailed guidance on crafting system prompts and creating custom agents, see Part 3: Understanding agents.

Quick reference: When to use customizations

For a complete comparison of when to use each method, see the Customize GitLab Duo Agent Platform overview.

What's next?

Congratulations! You've completed the entire GitLab Duo Agent Platform series. You now understand:

• How to use agents and flows across the entire SDLC, tailored to your use cases
• How to discover and share solutions in the AI Catalog
• How to monitor and manage your AI workflows
• How to extend capabilities with MCP integrations
• How to customize every aspect of GitLab Duo Agent Platform for your team

Return to complete series overview to review all parts and explore specific topics in depth.

Resources

• Custom Rules documentation
• AGENTS.md documentation
• Custom Review Instructions documentation
• Custom Agents documentation
• Custom Flows documentation
• MCP Clients documentation

Previous: Part 7: Model Context Protocol integration

Back to start: Complete series overview