Skip to content

Document Agents.md customization feature #2159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethanpalm merged 2 commits into from
Dec 10, 2025
Merged

Document Agents.md customization feature #2159

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
804f3ba
Update ai/agent.mdx
mintlify[bot] Dec 9, 2025
c74d89d
copyedit
ethanpalm Dec 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions ai/agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@

## Use the agent in the dashboard

Access the agent in a from your dashboard using the keyboard shortcut <kbd>⌘</kbd>+<kbd>I</kbd> (macOS) or <kbd>Ctrl</kbd>+<kbd>I</kbd> (Windows/Linux), or by clicking the **Ask agent** button. The agent panel is resizable on desktop. On mobile devices, the agent opens in full-screen.

Check warning on line 22 in ai/agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/agent.mdx#L22 

Did you really mean 'resizable'?

The agent panel has three views.

Expand All @@ -32,7 +32,7 @@
Use the agent in Slack to collaborate with your team on documentation updates.

<Note>
If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify app before you connect it.

Check warning on line 35 in ai/agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/agent.mdx#L35 

Use 'administrator' instead of 'admin'.
</Note>

1. Open the agent panel in your dashboard.
Expand All @@ -52,11 +52,29 @@

The agent can only access repositories that you connect through the Mintlify GitHub App. Configure which repositories the agent can access in the agent panel **Settings** or in the [GitHub App settings](https://github.com/apps/mintlify/installations/new).

## Customize agent behavior

Add an `AGENTS.md` file in your repository to customize the agent's behavior. The agent reads this file and follows any instructions you provide.

Create the `AGENTS.md` file at the root of your repository. If your project is a monorepo, create the file in the root of the documentation directory.

Add any instructions that you want the agent to follow. The agent appends these instructions to its system prompt, so they influence all of its responses and actions.

```markdown Examples of custom instructions
Always use TypeScript for code examples. Never use JavaScript.

When documenting API endpoints, include rate limiting information.

Use ISO 8601 (YYYY-MM-DD) format for dates.
```

The agent applies these instructions to all tasks, whether you're using it in the dashboard, Slack, or via the API.

## Embed the agent via API

Use the agent endpoints to [create jobs](/api-reference/agent/create-agent-job), [get a specific job](/api-reference/agent/get-agent-job), and [get all jobs](/api-reference/agent/get-all-jobs).

When creating jobs via the API, you can control whether pull requests are created in draft mode using the `asDraft` parameter (defaults to `true`). Set `asDraft: false` to create non-draft pull requests ready for immediate review and merging in automated workflows.

Check warning on line 77 in ai/agent.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/agent.mdx#L77 

In general, use active voice instead of passive voice ('are created').

## Write effective prompts

Expand Down