Add specific examples and workflows to agent documentation

ai/agent.mdx

@@ -21,7 +21,7 @@
 ## Add the agent to your Slack workspace
 
 <Note>
   If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify app before you connect it.
 </Note>
 
 1. Navigate to the [agent](https://dashboard.mintlify.com/products/agent) page of your dashboard.
@@ -46,15 +46,46 @@
 
 Make your 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. For example:
+### Problem-focused prompts
+
+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`
+- `@mintlify Users are confused about rate limits. Add a clear explanation with examples to the API reference`
+
+### Content creation prompts
+
+Create new documentation sections or pages with specific requirements:
+
+- `@mintlify Create a new troubleshooting page for common database connection errors`
+- `@mintlify Add a section to the quickstart about environment variables with examples for development and production`
+- `@mintlify Write a guide on migrating from v1 to v2 of our API based on this PR: [PR link]`
+
+### Code example prompts
 
-Use broad prompts for general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs. For example:
+Generate or update code examples across your documentation:
+
+- `@mintlify Add Python and Node.js code examples to the authentication page`
+- `@mintlify Update all API examples to use the new base URL https://api.example.com`
+- `@mintlify Generate a complete code example showing how to handle pagination in our API`
+
+### Maintenance prompts
+
+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 -`
+- `@mintlify Change all unordered lists to use * instead of -`
+- `@mintlify Replace all instances of "API key" with "access token" throughout the docs`
+- `@mintlify Update all broken links in the deployment section`
+
+### Review and improvement prompts
+
+Ask the agent to review and improve existing content:
+
+- `@mintlify Review the API rate limiting section. We changed limits last month from 100 to 1000 requests per minute`
+- `@mintlify Make the installation guide more concise and easier to follow`
+- `@mintlify Check if all code examples in the SDK documentation are up to date with version 2.0`
 
 ## Specify a subdomain
 
@@ -75,46 +106,126 @@
 
 Prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates.
 
-For example: `@mintlify Our quickstart page needs a new section on inviting collaborators`. Then `@mintlify The new section should be called "Inviting collaborators"`. Followed by any other iterations.
+**Example workflow:**
+1. Initial prompt: `@mintlify Our quickstart page needs a new section on inviting collaborators`
+2. Refine: `@mintlify The new section should be called "Inviting collaborators" and placed after the installation section`
+3. Add details: `@mintlify Add a code example showing how to send an invitation via the API`
+4. Final touch: `@mintlify Add a note about permission requirements for inviting users`
 
 ### Start with the agent, finish manually
 
 Prompt the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task.
 
-For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method.
+**Example workflow:**
+1. Prompt: `@mintlify Update the quickstart page to include information about inviting collaborators`
+2. Review the PR the agent creates
+3. Check out the branch locally: `git checkout mintlify/update-quickstart-collaborators`
+4. Make additional changes, add screenshots, or refine the content
+5. Push your changes and merge the PR
 
 ### Update docs when merging feature changes
 
 When you merge a feature pull request, share the PR link with the agent to update relevant docs.
 
-For example: `@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`.
+**Example workflow:**
+1. Merge a feature PR that adds OAuth support
+2. In Slack: `@mintlify This PR adds OAuth authentication. Update the authentication docs to include the new OAuth flow with code examples: https://github.com/yourorg/yourrepo/pull/123`
+3. Review the documentation PR the agent creates
+4. Merge the documentation updates
+
+**Real-world example:**
+```
+@mintlify This PR adds webhook signature verification: 
+https://github.com/acme/api/pull/456
+
+Update the webhooks documentation to:
+- Explain how signature verification works
+- Add code examples in Python and Node.js
+- Include troubleshooting tips for common verification errors
+```
 
 ### Generate release notes from a pull request
 
 Prompt the agent with a specific pull request to generate release notes or changelog updates based on the commit history.
 
-For example: `@mintlify Generate release notes for this PR: [PR link]`.
+**Example workflow:**
+1. Complete a sprint with multiple merged PRs
+2. Prompt: `@mintlify Generate release notes for version 2.1.0 based on these PRs: [PR link 1], [PR link 2], [PR link 3]`
+3. Review and refine: `@mintlify Add a migration guide section for the breaking changes`
+4. Merge the changelog update
 
 ### Generate code examples
 
 Prompt the agent to generate code examples for features throughout your docs or on specific pages.
 
-For example: `@mintlify Generate a code example to make the authentication method easier to understand`.
+**Example workflow:**
+1. Prompt: `@mintlify Add code examples for the new batch API endpoint in Python, Node.js, and cURL`
+2. Review the examples
+3. Refine: `@mintlify Add error handling to the Python example`
+4. Merge the updates
+
+**Real-world example:**
+```
+@mintlify Our authentication page only has cURL examples. 
+Add examples in Python, Node.js, Ruby, and Go showing:
+- How to authenticate with an API key
+- How to refresh tokens
+- How to handle authentication errors
+```
 
 ### Review existing content
 
 Prompt the agent to review existing content for technical accuracy, style, grammar, or other issues.
 
-For example: `@mintlify Review the API rate limiting section. We changed limits last month`.
+**Example workflow:**
+1. After a major API update: `@mintlify Review all API documentation and update any references to the old v1 endpoints to use v2 endpoints`
+2. Review the changes: `@mintlify Also check for any outdated parameter names`
+3. Merge the updates
+
+**Real-world example:**
+```
+@mintlify We changed our rate limits from 100 to 1000 requests per minute last month. 
+Review all documentation and update:
+- Rate limit numbers
+- Code examples showing rate limit headers
+- Troubleshooting guides mentioning rate limits
+```
 
 ### Respond to user feedback
 
 Prompt the agent with feedback from your users to make focused updates to your docs.
 
-For example: `@mintlify Users are getting confused by step 3 in the setup guide. What might be making it unclear?`.
+**Example workflow:**
+1. Receive user feedback: "Step 3 in the setup guide is confusing"
+2. Prompt: `@mintlify Users are getting confused by step 3 in the setup guide about environment variables. Make it clearer by adding examples and explaining what each variable does`
+3. Review and merge the improvements
+
+**Real-world example:**
+```
+@mintlify Multiple users reported that our WebSocket documentation doesn't explain 
+how to handle reconnections. Add a section covering:
+- Automatic reconnection strategies
+- Exponential backoff examples
+- How to detect connection state
+```
+
+### Sync documentation with Slack threads
+
+Reference Slack threads to provide the agent with full context from team discussions.
+
+**Example workflow:**
+1. Have a detailed discussion in Slack about a new feature
+2. Prompt: `@mintlify Based on this thread, create documentation for the new caching feature: [Slack thread link]`
+3. The agent reads the entire thread and creates comprehensive documentation
+4. Review and merge
 
 ### Automate with the API
 
 Integrate the agent into your existing automation tools to automatically update documentation when code changes occur, trigger content reviews, or sync documentation updates across multiple repositories.
 
-Learn how in the [Auto-update documentation when code is merged](/guides/automate-agent) tutorial.
+**Example workflow:**
+1. Set up a GitHub Action that triggers when PRs are merged to main
+2. Use the agent API to automatically create documentation updates
+3. Review the automated PRs and merge
+
+Learn how in the [Auto-update documentation when code is merged](/guides/automate-agent) tutorial.