Write effective prompts

Write clear, specific prompts to get better results from the Mintlify agent, with examples of effective instructions and tips for common patterns.

Think of the agent as a helpful assistant that needs your guidance to complete tasks. Give it clear instructions and context. More focused tasks are easier to complete, so break down complex projects into smaller steps.

Make prompts specific and outcome-focused

Generic prompts like @mintlify Improve the onboarding page apply general best practices, but may not improve content in the specific way that you were picturing.

Try prompts based on outcomes you want your users to achieve or problems that they encounter.

• @mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI
• @mintlify Developers keep getting 401 errors when following our authentication guide. Review the auth docs and add clearer examples showing how to properly format the API key

Use broad prompts for maintenance tasks

Use broad prompts for general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs.

• @mintlify Find and fix all typos in the docs
• @mintlify change all unordered lists to use * instead of -

Reference files and folders with @ mentions

When you prompt the agent from the dashboard agent panel, type @ to open an autocomplete menu of files and folders from your documentation. Selecting an item attaches it to your message as context, so the agent knows exactly which content you want it to use or update.

Use @ mentions to:

• Point the agent at a specific page when a description would be ambiguous.
• Scope a broad task to a single folder, such as a product area or section.
• Combine multiple files in one prompt without describing each path in prose.

To attach a file or folder:

1. In the agent panel composer, type @ followed by the name of the file or folder you want to reference.
2. Use the arrow keys to highlight an item in the autocomplete list.
3. Press Enter or Tab to attach it. Press Esc to dismiss the menu.

The attached file or folder appears as a chip above the composer. You can attach multiple items in the same message and remove any chip before sending.

Attached items are passed to the agent as labeled context with their paths, so you can reference them naturally in your prompt:

• Update @quickstart with the new collaborator invite flow
• Review every page in @api-reference for outdated response examples
• Move @authentication into the new @security folder and update internal links

@ mentions are available in the agent panel composer in the dashboard. In Slack, attach context by replying in a thread, sharing pull request links, or uploading files directly to your message.

Specify a domain name for multi-site organizations

If you have multiple documentation sites, include the subdomain parameter in your message to specify which documentation set the agent should work on.

To find your domain name, look at your dashboard URL for the documentation set you want to update. The domain name is the last part after your organization name. For example, if your dashboard URL is https://dashboard.mintlify.com/org-name/domain-name, your domain name is domain-name.

Use the format @mintlify subdomain=<your-domain-name> <your-prompt> to prompt the agent to work on a specific documentation set.

• @mintlify subdomain=public-docs Add a new section to the quickstart about inviting collaborators based on this PR: Prompts the agent to update the quickstart only on the public-docs site.
• @mintlify subdomain=customer-docs Update the auth docs for the new authentication method: Prompts the agent to update the auth docs only on the customer-docs site.