Xây dựng và xác minh tài liệu Mintlify với ak:mintlify

Dùng ak:mintlify để xây dựng hoặc duy trì project tài liệu Mintlify. Skill bao phủ docs.json, MDX page cùng component, navigation, OpenAPI và AsyncAPI reference, AI-facing documentation asset, local validation cùng deployment pattern trong khi giữ repository edit tách biệt với hosted account change.

Chọn ak:mintlify cho project Mintlify

Dùng ak:mintlify khi

• Bạn cần scaffold hoặc restructure project tài liệu Mintlify.
• Bạn cần cập nhật docs.json, navigation, branding, theme, redirect, search, API configuration hoặc integration.
• Bạn cần Mintlify MDX page có frontmatter, content component, API field, request hay response example, card, tab, step hoặc Mermaid block.
• Bạn cần kết nối OpenAPI hoặc AsyncAPI source đã review với reference page.
• Bạn cần local check, preview, CI validation, AI-facing asset hoặc deployment plan cho site Mintlify hiện có.

Chọn workflow khác khi

• Repository dùng Fumadocs, Docusaurus, MkDocs, Sphinx hoặc platform khác. Dùng convention native thay vì implicit conversion project.
• Bạn chỉ cần factual prose ngắn gọn không phụ thuộc docs platform. Dùng ak:docs.
• Bạn chỉ cần deployment workflow tổng quát. Dùng ak:deploy sau khi project Mintlify hợp lệ và hosting target được duyệt.
• Bạn cần vận hành Mintlify dashboard, DNS provider, Git host, analytics account, Slack, Discord hay external service khác mà không có session được cấp quyền.

Chuẩn bị project và platform boundary

Trước khi bắt đầu:

• Hoàn tất Onboarding, rồi xác nhận Engineer Kit được cài cho runtime và scope hiện tại.
• Cung cấp docs root, docs.json hiện có hoặc legacy configuration, package manager, repository instruction, target audience, information architecture, brand asset, locale hoặc version được hỗ trợ cùng allowed file boundary.
• Xác định version Mintlify CLI đã cài. Skill được ghim dùng command mint, nhưng platform schema, component, theme, integration cùng hosting behavior có thể đổi; xác minh active version trước khi dựa vào reference example.
• Cung cấp authoritative API specification, endpoint behavior, example, authentication rule và error contract. Loại real credential cùng production token.
• Tách local authorization khỏi hosted authorization: file edit và local preview không cấp quyền kết nối Git, tạo preview, đổi DNS, bật analytics, expose API playground hay deploy.

Input được khai báo là [task] [path]. Hãy cung cấp project path chính xác, outcome mong muốn, file được phép đổi, validation command, network policy và run có phải dừng trước preview, account configuration hoặc deployment không.

Yêu cầu thay đổi documentation có giới hạn

/ak:mintlify "In ./docs-site, add an Authentication group using the existing docs.json structure and write overview.mdx from the approved OpenAPI spec. Preserve current branding and navigation order, use placeholder credentials only, run mint validate, mint broken-links, and mint openapi-check with the installed CLI, and stop before mint dev, Git changes, dashboard configuration, or deployment."

/ak:mintlify "In ./docs-site, add an Authentication group using the existing docs.json structure and write overview.mdx from the approved OpenAPI spec. Preserve current branding and navigation order, use placeholder credentials only, run mint validate, mint broken-links, and mint openapi-check with the installed CLI, and stop before mint dev, Git changes, dashboard configuration, or deployment."

$ak:mintlify "In ./docs-site, add an Authentication group using the existing docs.json structure and write overview.mdx from the approved OpenAPI spec. Preserve current branding and navigation order, use placeholder credentials only, run mint validate, mint broken-links, and mint openapi-check with the installed CLI, and stop before mint dev, Git changes, dashboard configuration, or deployment."

Request tốt nêu project đã tồn tại hay chưa, page tree bắt buộc, source-of-truth document, public cùng private boundary, device và language được hỗ trợ, link policy dự kiến, accessibility bar và external system nào phải giữ nguyên.

Ghép task với surface bị ảnh hưởng

Reference library chứa example cho nhiều platform feature. Đừng suy ra mọi example được enable cho plan, CLI version, theme, region hoặc hosting model của người dùng. Xác nhận support bằng installed CLI cùng target account trước khi thay đổi public behavior.

Dùng pinned CLI command có chủ đích

Skill khai báo các local command sau:

mint new
mint dev
mint validate
mint broken-links
mint a11y
mint openapi-check
mint rename <old> <new>
mint migrate-mdx
mint update

Chạy mint --help cùng subcommand help liên quan cho installed version trước mutation. mint new scaffold file, mint rename đổi file cùng reference, mint migrate-mdx migrate legacy configuration và mint update đổi package. Review planned effect rồi giữ diff hoặc backup.

mint dev khởi động local preview, được pinned Skill document trên port 3000. Nó mở listening process và có thể tải remote font, asset, API, analytics, frame hoặc integration được project tham chiếu. Dùng environment đã review, ghi actual host cùng port và dừng server sau inspection.

Quan sát các giai đoạn documentation

1. Skill inventory project. Skill đọc repository instruction, configuration, page tree, asset, specification, package state cùng convention hiện có trước khi đề xuất edit.
2. Skill xác nhận information architecture. Audience, product, version, locale, navigation depth, route, source ownership và non-goal thành contract rõ ràng.
3. Skill kiểm tra active platform surface. CLI help cùng target configuration xác định field và command nào từ pinned reference còn hợp lệ.
4. Skill áp dụng file change nhỏ nhất. Configuration, navigation, content, specification mapping và asset giữ nhất quán thay vì bị rewrite thành template không liên quan.
5. Skill validate local. Configuration, link, accessibility và API spec được check bằng command khả dụng liên quan; failure vẫn hiển thị.
6. Skill preview khi được phép. Page, navigation state, theme, viewport, component, code, API reference, search và error path bắt buộc được kiểm tra trong rendered site thật.
7. Skill dừng tại external gate. Git connection, provider dashboard, analytics, bot, domain, auth, preview publication và deployment chờ approval rõ ràng.
8. Skill trả evidence. Report nêu changed file, check, preview finding, network call, reference claim không được hỗ trợ và approval tiếp theo.

Kiểm soát secret, interactive API và hosted effect

• Không đặt real API key, token, password, webhook secret, provider credential, private endpoint hay customer data vào docs.json, MDX, OpenAPI example, playground prefill, generated AI asset, screenshot hoặc CI file. Dùng placeholder rõ ràng cùng approved secret storage.
• Interactive playground có thể tạo live browser request hoặc route chúng qua proxy. Mặc định nó tới environment an toàn hoặc disable đến khi authentication, CORS, rate limit, mutation behavior cùng data retention được review.
• Analytics, session replay, chat, marketing và consent integration ảnh hưởng privacy và có thể load third-party script. Yêu cầu product, legal và security approval phù hợp deployment.
• Contextual action có thể copy hoặc gửi page content tới AI tool, editor hay custom URL. llms.txt, skill.md, MCP, search, bot cùng AI indexing có thể tăng public machine-readable surface. Review inclusion và exclusion.
• Custom React component, iframe, custom CSS, redirect, reverse proxy, CSP cùng authentication đổi execution hoặc trust boundary. Validate như code và infrastructure.
• Kết nối Git, publish preview, đổi DNS hay TLS, provision domain, purge cache hoặc deploy tới Mintlify, Vercel, Cloudflare hay AWS là external state change. Quyền edit local không bao gồm chúng.

Xác minh output và evidence

Kết quả local đầy đủ nên gồm:

• File chính xác đã đổi và generate, gồm docs.json, MDX, API spec, asset, custom component, package metadata, CI configuration cùng migration output trong scope.
• Installed CLI version và result từ mint validate, mint broken-links, mint a11y cùng mint openapi-check khi phù hợp, với command không khả dụng hoặc đã rename được báo thay vì mô phỏng.
• Route và navigation reconciliation: mọi configured page tồn tại, ordering có chủ đích, product, version, locale cùng tab context khớp, redirect resolve và không orphan expected page.
• Factual reconciliation của prose, parameter, schema, authentication, example, response, error cùng generated AI-facing content với approved source.
• Preview evidence cho theme, viewport size, component, code block, image, Mermaid, API page, search, link, 404 behavior, keyboard access và contrast bắt buộc khi preview được cho phép.
• Network và privacy inventory cho playground, proxy, frame, font, analytics, support widget, AI tool, bot, MCP, Git, hosting cùng domain.
• Statement rõ rằng deployment không xảy ra, hoặc deployment evidence được cấp quyền riêng với target, URL, version, check và rollback.

Hai release stable và beta được ghim chứa file ak:mintlify giống hệt. Skill chỉ chứa reference Markdown, không có script, schema, fixture hay test. Số lượng theme, locale, component, listed integration, command behavior cùng hosted platform feature thay đổi theo thời gian và không được trình bày là hiện hành khi chưa xác minh.

Khắc phục sự cố và hiểu giới hạn

Dùng ak:docs cho prose không phụ thuộc platform, ak:deploy cho delivery workflow đã duyệt hoặc Runtime adapter để xem ranh giới tool riêng của session.