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
• Customize agent behavior
• Extend capabilities with MCP
• Create 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 flexible customization options across multiple levels:

• User-level: Personal preferences that apply across all projects (custom rules, AGENTS.md, MCP config)
• Workspace-level: Project-specific configurations (custom rules, AGENTS.md, MCP config)
• Project-level: Custom agents and flows you create and manage within a specific project

Part 1: Customize agent behavior

Custom rules

Custom rules provide instructions for agents and flows, ensuring consistent behavior across your team without requiring repetition. For example, in development style guides or how to execute tests.

Navigate to IDE workspace or user configuration directory.

User-level custom rules

User-level rules apply to all your projects and workspaces.

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:

      - 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

    

Workspace-level custom rules

Workspace rules apply only to a specific project. They override user-level rules for that project.

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.

AGENTS.md for customizing agent behavior

AGENTS.md is an industry-standard file for customizing agent behavior. It allows you to define how agents should behave in your chat conversations, foundational flows, and custom flows without modifying the agents themselves.

Difference to custom rules: AGENTS.md are consumed by all agents and flows (foundational and custom). It also follows an industry standard that other AI tools can use, for example, Claude Code as external agent. Use AGENTS.md when you want your instructions to apply across multiple contexts.

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.

How it works:

• User-level AGENTS.md applies globally across all projects.
• Workspace-level AGENTS.md applies to a specific project.
• Subdirectory-level AGENTS.md files provide context for specific parts of your codebase.
• Agents and flows combines instructions from all applicable levels.
• Newly added or updated AGENTS.md instructions require triggering new flows, or starting a new chat with a (custom) agent.

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 flows: Update flow configuration to access the user_rule context

Learn more about AGENTS.md.

Custom review instructions

Custom review instructions provide specific guidelines for the Code Review foundational flow. The instructions ensure consistent code review standards, and can be tailored to specific file types in your project.

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 detailed setup instructions and examples, see the Custom Review Instructions documentation.

Part 2: Extend capabilities with MCP

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.

Part 3: Create 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.

Custom agents and flows

There is a lot to learn, and for easier reading, the tutorials are split:

Custom agents:

• Learn how to create agents with custom system prompts, configure tools, and manage permissions.
• See Part 3: Understanding agents - Custom agents section.

Custom flows:

• Learn how to create multi-step workflows, configure components, and set up event-driven automation.
• See Part 4: Understanding flows — Custom flows section.

Agent tools:

• Tools determine what actions agents can perform. Configure tools based on your agent's purpose and security requirements.
• See Part 3: Understanding agents for tool configuration details.

Quick reference: When to use customizations

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