Custom Instructions

Custom instructions let you inject free-text guidance into every agent’s system prompt, right before the diff. Use them to tell MergeWatch about your stack, coding conventions, and the areas you care about most.

What custom instructions are

When an agent reviews a pull request, its system prompt is assembled in this order:

Built-in agent prompt

The default prompt for the agent (e.g., security, logic, style).

Custom instructions

Your free-text instructions are appended to the system prompt, giving the agent project-specific context.

Diff payload

The pull request diff is provided as the final input for the agent to analyze.

Custom instructions do not replace the built-in prompt — they extend it. This means agents retain their core capabilities while gaining awareness of your project’s specific needs.

Two levels, one priority

Custom instructions can be set at two levels:

Level	Where to set it	Scope
Installation-level	Dashboard > Settings > Custom Instructions	Applies to all repositories in the installation
Repo-level	`.mergewatch.yml` under `customAgents[].prompt`	Applies to a specific custom agent in a specific repo

Installation-level custom instructions are appended to all built-in agent prompts across all repos. Repo-level prompts are only available on custom agents defined in customAgents. Built-in agent prompts cannot be overridden via .mergewatch.yml — use custom agents to add domain-specific review logic.

How it works in practice:

Installation-level custom instructions are appended to every built-in agent’s system prompt as a shared prefix.
Custom agents defined in customAgents use their own prompt field and do not receive the installation-level instructions.
To add domain-specific review logic for a repo, define a customAgents entry with a targeted prompt.

Examples for common stacks

version: 1
customAgents:
  - name: react-security
    prompt: "Flag any use of dangerouslySetInnerHTML. Check for XSS in user-facing components."
    severityDefault: critical
  - name: react-style
    prompt: "Flag 'any' type usage — prefer explicit types. Require explicit return types on exported functions. Use 'const' over 'let' where possible."
    severityDefault: warning
  - name: react-logic
    prompt: "Watch for missing null checks on optional chaining results used in array methods."
    severityDefault: warning

version: 1
customAgents:
  - name: django-security
    prompt: "Flag SQL injection via raw() querysets. Check for CSRF exemptions, unvalidated redirects, and missing input sanitization."
    severityDefault: critical
  - name: django-style
    prompt: "Enforce PEP 8. Flag any use of print() — use logging module instead. Require docstrings on public functions."
    severityDefault: warning
  - name: django-logic
    prompt: "Check for N+1 queries in views. Flag missing select_related/prefetch_related on QuerySet iterations."
    severityDefault: warning

version: 1
customAgents:
  - name: service-boundaries
    prompt: "Flag cross-service-boundary imports. Services in services/* must not import from other services directly — use the shared/ directory."
    severityDefault: warning
  - name: service-auth
    prompt: "Each service has its own auth middleware. Flag any request handler missing auth decoration."
    severityDefault: critical
  - name: service-style
    prompt: "Each service owns its own DB models. Flag any model import that crosses service boundaries."
    severityDefault: warning

Character limits

Custom instructions have the following character limits:

Level	Limit
Installation-level	1000 characters
Repo-level (`customAgents[].prompt`)	1000 characters per agent

Installation-level instructions serve as a shared prefix appended to every built-in agent prompt. Keep them concise to leave room for the diff payload in the model’s context window.

What makes a good custom instruction

Be specific, not generic

Good: “Flag any use of eval() or Function() constructor in client-side code.”Bad: “Find security issues.” (The agent already does this by default.)

Name your stack explicitly

Good: “This is a Next.js 14 app using App Router. Flag any use of getServerSideProps — we use Server Components instead.”Bad: “Follow framework best practices.” (Which framework?)

Use negative examples

Good: “Do NOT flag missing semicolons — our Prettier config handles that. DO flag unused imports.”Bad: “Check code style.” (Too broad, overlaps with linters.)

Keep it short

Instructions under 200 characters tend to produce the most focused results. Longer instructions risk diluting the agent’s attention across too many concerns.

Start with one or two custom agents and observe the results in your first few reviews. Add more specificity only where the built-in agents are missing issues or producing false positives.

Overview

Self-Hosting

LLM Providers

Platform Guides

Configuration

GitHub App

Deployment

Dashboard

Managed SaaS

Reference

What custom instructions are

Two levels, one priority

Examples for common stacks

Character limits

What makes a good custom instruction

Next steps

.mergewatch.yml Reference

Skip Rules

​What custom instructions are

​Two levels, one priority

​Examples for common stacks

​Character limits

​What makes a good custom instruction

​Next steps

.mergewatch.yml Reference

Skip Rules

What custom instructions are

Two levels, one priority

Examples for common stacks

Character limits

What makes a good custom instruction

Next steps