From 2b6dd4b1f829da6c3735aeb5928e5acdcef4d68c Mon Sep 17 00:00:00 2001 From: N43527 Date: Tue, 28 Jul 2026 11:04:20 -0700 Subject: [PATCH 1/3] docs: add AI setup agent prompt to quickstart --- quickstart.mdx | 9 +++++++++ snippets/setup-agent-prompt.mdx | 25 +++++++++++++++++++++++++ 2 files changed, 34 insertions(+) create mode 100644 snippets/setup-agent-prompt.mdx diff --git a/quickstart.mdx b/quickstart.mdx index 4fc7601ca7..68ebef7d09 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -5,10 +5,19 @@ keywords: ["quickstart", "deploy", "get started", "first steps", "tutorial", "se boost: 3 --- +import SetupAgentPrompt from "/snippets/setup-agent-prompt.mdx"; import SkillMcpPrompt from "/snippets/skill-mcp-prompt.mdx"; After you complete this guide, you'll have a live documentation site ready to customize and update. + + Using an AI agent? + + Copy the following prompt to have your agent complete this entire guide for you: create your account, deploy your site, and publish your content. The prompt tells your agent to hand off any steps that need you. + + + + ## Before you begin Mintlify uses a docs-as-code approach to manage your documentation. Every page on your site has a corresponding file stored in your documentation repository. diff --git a/snippets/setup-agent-prompt.mdx b/snippets/setup-agent-prompt.mdx new file mode 100644 index 0000000000..91bacc7585 --- /dev/null +++ b/snippets/setup-agent-prompt.mdx @@ -0,0 +1,25 @@ +{/* vale off */} + + +Get my docs live on a published Mintlify site. Done = you hand me the live URL and confirm it loads. Tell me clearly whenever a step needs me — do everything else yourself. If this prompt was pasted before (for example, after a restart), continue from where things left off instead of starting over. If you don't have terminal or command execution access, tell me to follow the manual steps at [mintlify.com/start](https://mintlify.com/start) instead — everything below requires running commands. + +1. Ask for my docs — a local folder or a repo. Verify the source before building: echo back exactly what you're reading and list its top-level contents so I can confirm it's right. If you can't access something I named (private repos return 404, same as nonexistent), stop and ask — never substitute a different source. +2. Check whether `mint` is installed with `mint --version`. If it's missing, install it with `npm i -g mint` (or `pnpm add -g mint`); requires Node.js v20.17.0+. If it's already installed, run `mint update` instead of reinstalling. +3. Run `mint status`. If it already shows an organization, skip to step 7. +4. If `mint status` shows I'm not logged in, ask me directly whether I already have a Mintlify account — that alone doesn't tell you whether I have one on a different machine or never signed up. Don't guess. + - If I have one: run `mint login`. Needs me for one browser step, approving access, then nothing else. + - If I don't: ask me for my first name, last name, company, and email if I haven't given them already — never invent these. Run `mint signup --firstName [firstName] --lastName [lastName] --company [company] --email [email]` as a background task, since it blocks until I click a verification link that can take several minutes. +5. Needs me: I'll check my email and click the verification link. That opens a browser tab that automatically finishes the rest — approve the CLI, then connect a GitHub repository or let Mintlify host one. Tell me clearly this step is mine, then wait for it before continuing. +6. Run `mint status` again to confirm an organization and subdomain now exist. Provisioning can lag a moment after onboarding finishes — if no subdomain appears yet, wait about 10 seconds and retry a few times before concluding something's wrong. +7. Needs me: ask for the URL of the repository connected to my Mintlify project — `mint status` doesn't expose it, so you can't look it up yourself. Clone it once I give it to you. +8. Check what's in that repo. If I connected my own existing docs repo, my content is already there — don't overwrite it. If Mintlify created the repo, it contains starter template content — replace that with my actual docs content from step 1. Only use `mint new [directory]` if I want a different theme or template than what's in the repo — scaffold it locally, then use its output in place of the seeded content. +9. Preview with `mint dev` (`http://localhost:3000`). It blocks until stopped, so run it as a background task — verify the preview loads, then stop it before continuing. +10. Commit and push your changes. Mintlify deploys automatically on push. +11. If I want a custom domain, run `mint add-domain `. It prints the DNS records I need to add with my domain provider — hand those to me directly, since only I can configure them at my registrar. +12. Confirm my site is live: fetch `https://.mintlify.app` (find the subdomain via `mint status`) and confirm it loads, then give me the URL. Deploys take a few minutes after pushing — retry before treating a failed fetch as an error. +13. Set yourself up to keep working here. Install the Mintlify skill with `npx skills add https://mintlify.com/docs`, then register the admin MCP at `https://mcp.mintlify.com` for your specific tool — for example `claude mcp add --transport http mintlify https://mcp.mintlify.com` for Claude Code, or fetch https://mintlify.com/docs/ai/mintlify-mcp.md for instructions for Claude, Cursor, Codex, or ChatGPT. Do this step yourself — don't ask me to run these commands. +14. Needs me: the first admin MCP tool call opens a browser window for OAuth login. Approve it there. Most tools don't load newly added MCP servers mid-session — if the Mintlify tools don't show up, tell me to restart you and we'll pick up from here. +15. If any command fails in a way not covered above, stop and tell me the exact error rather than guessing or retrying blindly. If it looks like something's wrong on Mintlify's end rather than in what you're doing, check https://status.mintlify.com or point me to https://mintlify.com/docs/contact-support. + + +{/* vale on */} From 355201b199322e90ff74a70d539ac4538a04dbde Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 28 Jul 2026 13:19:17 -0700 Subject: [PATCH 2/3] remove redundant SkillMcpPrompt --- quickstart.mdx | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index 68ebef7d09..5c3860f8be 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -6,14 +6,15 @@ boost: 3 --- import SetupAgentPrompt from "/snippets/setup-agent-prompt.mdx"; -import SkillMcpPrompt from "/snippets/skill-mcp-prompt.mdx"; After you complete this guide, you'll have a live documentation site ready to customize and update. Using an AI agent? - Copy the following prompt to have your agent complete this entire guide for you: create your account, deploy your site, and publish your content. The prompt tells your agent to hand off any steps that need you. + Copy the following prompt to have your agent set up your site for you. It directs your agent to create your account and deploy your site. It also adds the Mintlify [skill](/ai/skillmd) and [MCP server](/ai/model-context-protocol) for better results when you update your content. + + The prompt splits the quickstart into tasks your agent can complete and directs it to ask you for any information it needs while getting everything set up. @@ -24,14 +25,6 @@ Mintlify uses a docs-as-code approach to manage your documentation. Every page o When you connect your documentation repository to your project, you can work on your documentation locally or in the web editor and sync any changes to your remote repository. - - Using an AI coding tool? - - Copy the following prompt to add the Mintlify [skill](/ai/skillmd) and [MCP server](/ai/model-context-protocol) for better results when updating your documentation. - - - - ## Deploy your documentation site Go to [mintlify.com/start](https://mintlify.com/start) and complete the onboarding process. During onboarding, you'll connect your GitHub account, create or select a repository for your documentation, and install the GitHub App to enable automatic deployments. From b4ea28fa5753525f614f537c779717a61aea7351 Mon Sep 17 00:00:00 2001 From: Nivedh Mudiam Date: Tue, 28 Jul 2026 13:55:54 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> --- snippets/setup-agent-prompt.mdx | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/snippets/setup-agent-prompt.mdx b/snippets/setup-agent-prompt.mdx index 91bacc7585..8cff285643 100644 --- a/snippets/setup-agent-prompt.mdx +++ b/snippets/setup-agent-prompt.mdx @@ -1,23 +1,23 @@ {/* vale off */} - -Get my docs live on a published Mintlify site. Done = you hand me the live URL and confirm it loads. Tell me clearly whenever a step needs me — do everything else yourself. If this prompt was pasted before (for example, after a restart), continue from where things left off instead of starting over. If you don't have terminal or command execution access, tell me to follow the manual steps at [mintlify.com/start](https://mintlify.com/start) instead — everything below requires running commands. + +Get my documentation live on a published Mintlify site. You are successfully done when you give me the live URL and confirm it loads. Tell me clearly whenever a step needs my input—do everything else yourself. If this prompt was pasted before (for example, after a restart), continue from where things left off instead of starting over. If you don't have terminal or command execution access, tell me to follow the manual steps at [mintlify.com/start](https://mintlify.com/start) instead. Everything below requires running commands and requires Node.js v 20.17.0+ (LTS versions recommended). -1. Ask for my docs — a local folder or a repo. Verify the source before building: echo back exactly what you're reading and list its top-level contents so I can confirm it's right. If you can't access something I named (private repos return 404, same as nonexistent), stop and ask — never substitute a different source. -2. Check whether `mint` is installed with `mint --version`. If it's missing, install it with `npm i -g mint` (or `pnpm add -g mint`); requires Node.js v20.17.0+. If it's already installed, run `mint update` instead of reinstalling. +1. Ask for my existing content that will be used for my Mintlify site. This may be a local folder or a repo. Verify the source before building: echo back exactly what you're reading and list its top-level contents so I can confirm it's right. If you can't access something I named (private repos return 404, same as nonexistent), stop and ask. Never substitute a different source. +2. Check whether `mint` is installed with `mint --version`. If it's missing, install it with `npm i -g mint` (or `pnpm add -g mint`). If it's already installed, run `mint update` instead of reinstalling. 3. Run `mint status`. If it already shows an organization, skip to step 7. -4. If `mint status` shows I'm not logged in, ask me directly whether I already have a Mintlify account — that alone doesn't tell you whether I have one on a different machine or never signed up. Don't guess. - - If I have one: run `mint login`. Needs me for one browser step, approving access, then nothing else. - - If I don't: ask me for my first name, last name, company, and email if I haven't given them already — never invent these. Run `mint signup --firstName [firstName] --lastName [lastName] --company [company] --email [email]` as a background task, since it blocks until I click a verification link that can take several minutes. -5. Needs me: I'll check my email and click the verification link. That opens a browser tab that automatically finishes the rest — approve the CLI, then connect a GitHub repository or let Mintlify host one. Tell me clearly this step is mine, then wait for it before continuing. -6. Run `mint status` again to confirm an organization and subdomain now exist. Provisioning can lag a moment after onboarding finishes — if no subdomain appears yet, wait about 10 seconds and retry a few times before concluding something's wrong. +4. Needs me: If `mint status` shows I'm not logged in, ask me directly whether I already have a Mintlify account. Don't guess. + - If I have one: run `mint login`. You need me for browser steps and to approve access. + - If I don't: ask me for my first name, last name, company, and email if I haven't given them already—never invent these. Run `mint signup --firstName [firstName] --lastName [lastName] --company [company] --email [email]` as a background task since it blocks until I click a verification link that can take several minutes. +5. Needs me: I'll check my email and click the verification link. That opens a browser tab that automatically finishes the rest of account creation/logging in. I must approve the CLI, then connect a GitHub repository or let Mintlify host one. Tell me clearly this step is mine, then wait for it before continuing. +6. Run `mint status` again to confirm an organization and subdomain now exist. Provisioning can lag a moment after onboarding finishes — if no subdomain appears yet, wait about 10 seconds and retry a few times before concluding something is wrong. 7. Needs me: ask for the URL of the repository connected to my Mintlify project — `mint status` doesn't expose it, so you can't look it up yourself. Clone it once I give it to you. 8. Check what's in that repo. If I connected my own existing docs repo, my content is already there — don't overwrite it. If Mintlify created the repo, it contains starter template content — replace that with my actual docs content from step 1. Only use `mint new [directory]` if I want a different theme or template than what's in the repo — scaffold it locally, then use its output in place of the seeded content. -9. Preview with `mint dev` (`http://localhost:3000`). It blocks until stopped, so run it as a background task — verify the preview loads, then stop it before continuing. +9. Preview with `mint dev`, which generally starts on `http://localhost:3000` unless that port is in use. It blocks until stopped, so run it as a background task. Verify the preview loads, then stop it before continuing. 10. Commit and push your changes. Mintlify deploys automatically on push. -11. If I want a custom domain, run `mint add-domain `. It prints the DNS records I need to add with my domain provider — hand those to me directly, since only I can configure them at my registrar. -12. Confirm my site is live: fetch `https://.mintlify.app` (find the subdomain via `mint status`) and confirm it loads, then give me the URL. Deploys take a few minutes after pushing — retry before treating a failed fetch as an error. -13. Set yourself up to keep working here. Install the Mintlify skill with `npx skills add https://mintlify.com/docs`, then register the admin MCP at `https://mcp.mintlify.com` for your specific tool — for example `claude mcp add --transport http mintlify https://mcp.mintlify.com` for Claude Code, or fetch https://mintlify.com/docs/ai/mintlify-mcp.md for instructions for Claude, Cursor, Codex, or ChatGPT. Do this step yourself — don't ask me to run these commands. +11. Needs me: If I want a custom domain, run `mint add-domain `. It prints the DNS records I need to add with my domain provider. Tell me the DNS records, since only I can configure them at my registrar. Make it clear that this is a step I must complete. +12. Confirm my site is live: fetch `https://.mintlify.site` (find the subdomain via `mint status`) and confirm it loads. If I added a custom domain in step 11, also fetch that domain and confirm it loads before calling this step done-DNS propagation can lag, so retry a few times before treating a failed fetch as an error. +13. Set yourself up to keep working here: install the [Mintlify skill](https://mintlify.com/docs/ai/skillmd.md) with `npx skills add https://mintlify.com/docs`, then register the [admin MCP server](https://mintlify.com/docs//ai/model-context-protocol.md) at `https://mcp.mintlify.com` for your specific tool. For example, `claude mcp add --transport http mintlify https://mcp.mintlify.com` for Claude Code or fetch https://mintlify.com/docs/ai/mintlify-mcp.md for instructions for Claude, Cursor, Codex, or ChatGPT. Do this step yourself—don't ask me to run these commands. 14. Needs me: the first admin MCP tool call opens a browser window for OAuth login. Approve it there. Most tools don't load newly added MCP servers mid-session — if the Mintlify tools don't show up, tell me to restart you and we'll pick up from here. 15. If any command fails in a way not covered above, stop and tell me the exact error rather than guessing or retrying blindly. If it looks like something's wrong on Mintlify's end rather than in what you're doing, check https://status.mintlify.com or point me to https://mintlify.com/docs/contact-support.