Agent Authoring

An agent is a reusable worker, not a one-off task ticket.

Use this page when you are creating or editing agents that will be bound to Triggers, Assignments, Automations, GitHub mentions, CLI workflows, or API started work.

Start with the contract

Before writing a long system prompt, define the agent contract:

If the contract is unclear, routing will be unclear too.

Good agent shapes

Good agents are narrow enough to evaluate:

• PR reviewer
• issue triage assistant
• CI failure investigator
• docs maintainer
• frontend implementation agent
• release checklist runner
• migration planner

Weak agents are broad and hard to route:

• "general engineer"
• "do everything"
• "repo expert"
• "AI assistant"

Broad agents are still useful for manual CLI work, but they make hosted routing harder to debug.

Slugs

Slugs are routing identifiers for targeted GitHub mentions.

@mogplex/triage
@mogplex/review
@mogplex/docs

Use slugs that are:

• short
• lowercase
• stable
• job-shaped
• unambiguous to a teammate reading a GitHub comment

Avoid encoding model names, temporary projects, or people in slugs. Those change more often than the agent's job.

Prompt structure

Use a compact structure:

You are the <job> agent for <scope>.

Primary goal:
- ...

Inputs you may receive:
- ...

How to work:
- ...

When to ask for help:
- ...

Output expectations:
- ...

Keep routing instructions out of the prompt when the route itself can own them. For example, an Automation should own graph steps and conditions. The agent prompt should own behavior inside its node.

Skills, rules, and context

Use Skills, Rules, and Context to avoid prompt bloat:

If you paste the same paragraph into multiple agents, it probably belongs in a rule, skill, or context entry.

Model choice

Set the model on the agent when the job has a durable model requirement.

Examples:

• use a stronger model for security review or difficult implementation
• use a lower-cost model for high-volume triage
• use a long-context model for large codebase reading

For one-off differences inside a workflow, prefer an Automation node override instead of creating another nearly identical agent.

Read Model Selection and Cost before changing a high-volume route.

Forking presets

Fork or customize a preset when:

• the built-in job is close but your repo needs different output
• an Assignment should own a durable copy of the behavior
• the model, prompt, slug, rules, or context need to become account-owned

Do not fork just to handle one temporary instruction. Put temporary detail in the prompt for that run, assignment, or automation node.

Routing fit

Review checklist

Before saving a durable agent:

• the name explains the job
• the slug matches the targeted mention you expect
• the description helps a teammate pick it from a list
• the model is deliberate
• the prompt says what to do and when to stop
• the output expectation is explicit
• shared rules are not duplicated in the prompt
• routing-specific behavior is owned by the route when possible
• one small test run succeeds before connecting a high-volume route

Read next