Skip to content
Nx IDEDocs

Customization4 min read

Custom Agents

Per-file agent definitions in .nexgile/agents with live reload

Custom agents are custom modes defined as one Markdown file per persona instead of entries in a single YAML file. A .nexgilemodes file works well for a couple of modes, but it scales awkwardly: every persona shares one file, so reviewing a change to one agent’s prompt means digging through everyone else’s, and you can’t version or share an agent independently. Agent files fix that — drop payments-engineer.md into .nexgile/agents/, and a Payments Engineer mode appears in the dropdown.

Where agent files live

Section titled “Where agent files live”
Scope Location Applies to
Project <project>/.nexgile/agents/*.md This workspace; commit them with the repo
Global ~/.nexgile/agents/*.md Every workspace on your machine

Each .md file in these directories defines exactly one agent.

Anatomy of an agent file

Section titled “Anatomy of an agent file”

YAML frontmatter carries the mode’s schema fields; the body below the frontmatter becomes the agent’s custom instructions — effectively its standing system prompt. Here’s a complete, working example, .nexgile/agents/payments-engineer.md:

---
name: 💳 Payments Engineer
description: Implements and modifies payment flows safely.
whenToUse: Use for any change touching billing, invoices, or the Stripe integration.
roleDefinition: >-
  You are a payments engineer who treats money-moving code as
  safety-critical. You favor idempotent operations, explicit
  currency handling, and exhaustive failure-path tests.
groups:
  - read
  - - edit
    - fileRegex: ^src/(payments|billing)/
      description: Payment and billing modules only
  - command
---


Ground rules for every payments task:


1. All amounts are integer minor units (cents). Never introduce floats.
2. Every external call to Stripe goes through src/payments/gateway.ts —
   never import the stripe SDK anywhere else.
3. Webhook handlers must be idempotent; check the event ledger first.
4. Any schema change to invoices or charges requires a reversible
   migration and a note in docs/payments/CHANGES.md.
5. Before completing, run: pnpm test src/payments

Save the file and “💳 Payments Engineer” is in the mode dropdown, restricted to editing src/payments/ and src/billing/.

Frontmatter reference

Section titled “Frontmatter reference”

The same schema as .nexgilemodes entries (see Custom Modes), with file-specific conveniences:

Field Required Notes
slug No Defaults to the filename — payments-engineer.md → payments-engineer. Letters, numbers, dashes only.
name Yes Display name in the dropdown.
roleDefinition No Falls back to name (then to the slug) if omitted — but write one; it’s the persona.
description No One-liner for the modes UI.
whenToUse No Delegation guidance for the Orchestrator.
groups No Tool permissions; defaults to [] (no read/edit/command/mcp tools). Supports the [group, { fileRegex, description }] restriction form.
customInstructions No Only used if the body is empty — the body is the preferred place.
source No Normally inferred: project or global by directory.

Within one directory, files are processed alphabetically, and if two files declare the same slug the first wins — the duplicate is skipped and reported. Keep one slug per file.

Precedence

Section titled “Precedence”

When the same slug exists in multiple places:

  1. Project beats global — a project agent overrides a global agent.
  2. Within the project tier, .nexgilemodes wins — the single-file workflow stays authoritative, so a team’s .nexgilemodes entry overrides a same-slug project agent file.
  3. Within the global tier, agent files beat the global custom_modes.yaml.
  4. Any of these override a built-in mode with the same slug.

Live reload and error reporting

Section titled “Live reload and error reporting”

The agents directories are watched: add, edit, or delete a file and the mode list rebuilds within a fraction of a second (rapid save bursts are coalesced). No reload, no restart.

If a file fails to parse — broken frontmatter, invalid slug, schema violation — that agent is skipped without hiding your other agents, and Nexgile Code tells you: a warning toast appears once per file per session, and every error is logged with a timestamp to the Output → “Nexgile Agents” channel. If an agent you expected is missing from the dropdown, check that channel first.

Agent file or .nexgilemodes entry?

Section titled “Agent file or .nexgilemodes entry?”

Both create the same thing — a custom mode. Choose by workflow:

Prefer an agent file when… Prefer .nexgilemodes when…
You want a reviewable diff per persona in PRs You have one or two small project modes
Personas are owned by different people/teams One person maintains all modes together
You share personas by copying single files You use the Modes view UI to create/edit (it writes .nexgilemodes for project modes)
You keep a personal stable in ~/.nexgile/agents/ You need the tier-winning definition (it overrides same-slug project agents)

Mode-scoped extras work identically for both: .nexgilerules-payments-engineer, .nexgile/rules-payments-engineer/, and .nexgile/skills-payments-engineer/ all key off the slug.

Section titled “Related”