Skip to main content
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:
1

Built-in agent prompt

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

Custom instructions

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

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:
LevelWhere to set itScope
Installation-levelDashboard > Settings > Custom InstructionsApplies to all repositories in the installation
Repo-level.mergewatch.yml under customAgents[].promptApplies 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

​
Character limits

Custom instructions have the following character limits:
LevelLimit
Installation-level1000 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

Good: “Flag any use of eval() or Function() constructor in client-side code.”Bad: “Find security issues.” (The agent already does this by default.)
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?)
Good: “Do NOT flag missing semicolons — our Prettier config handles that. DO flag unused imports.”Bad: “Check code style.” (Too broad, overlaps with linters.)
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.

​
Next steps

.mergewatch.yml Reference

Full reference for all configuration properties, defaults, and examples.

Skip Rules

Control which PRs are skipped and configure path-based and label-based rules.