agent-context: fix wrong claims and API docs gaps in Mintlify skill

[ethanpalm]

Summary

Content fixes from a review of the canonical Mintlify skill against the current docs. Each change was checked against the doc source it cites.

Wrong claims corrected

• navigation.md: global.languages and global.versions require href (organize/settings-reference.mdx). The example also adds it.
• configuration.md: stop recommending hidden: false. organize/pages.mdx:61 says to remove the field instead.
• configuration.md: add mode: "assistant" (organize/pages.mdx:176-186).
• components.md: <Icon> takes custom images through src, not icon (snippets/icons-required.mdx). Steps titleSize includes h4 and also applies to <Steps>. Step title is required. Adds id and noAnchor (components/steps.mdx).
• cli.md: mint test SDK prerequisites and exit codes. mint analytics requires Pro or Enterprise (cli/commands.mdx).

API docs gaps filled (api-docs.md)

• Spec requirements: 3.0/3.1, internal $ref only, servers needed for the playground, security schemes.
• Page generation from openapi on navigation elements: directory, inheritance, spec.json METHOD /path entries, hosted-spec redeploys, --local-schema.
• MDX pages from a spec, including the warning to always include the spec path when the repo has multiple specs. Also webhooks, openapi-schema, and the scraper.
• Manual pages: ParamField/ResponseField, RequestExample/ResponseExample, per-page playground and authMethod (including none), and mdx.auth.name.
• x-mint fields: metadata, content, href, pre/post.

Not in this PR

• Docs vs. published schema disagreements (iconType, devin-desktop, banner.color, errors.404.description, and others). These need a docs or schema decision first.
• Smaller component prop gaps (Cards type, Tabs defaultTabIndex, Tree highlight, and others), settings gaps (redirect wildcards, SEO fields, integrations), and GraphQL/SDK reference coverage. Happy to follow up.
• SKILL.md structure (description trigger terms, moving the admin MCP section to a reference file).

For review

• organize/pages.mdx:61 ("do not set false") and organize/hidden-pages.mdx:38 ("same effect, but avoid in hidden groups") disagree. The skill follows the stricter one.
• Vale doesn't lint .md files in this repo, so these edits haven't had a style check.
• Kiro version: agent-context: bump Kiro manifest version automatically on sync #7472 handles bumps automatically at sync time, whichever order these merge in.

Validation

npm test and npm run check pass.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only edits to agent skill reference files; no runtime or product code changes.

Overview
Updates the Mintlify agent skill reference markdown under agent-context/context/skills/mintlify/reference/ so agents get accurate guidance aligned with current Mintlify docs.

Corrections: navigation.md now states global.languages and global.versions entries require href. configuration.md says to remove hidden instead of setting false, and documents mode: "assistant". components.md documents <Icon src> for custom images, Steps-level titleSize (including h4), and Step id / noAnchor. cli.md adds mint test agent SDK prerequisites and exit codes, and notes Pro or Enterprise for mint analytics.

API reference expansion (api-docs.md): Replaces a minimal top-level api.openapi story with spec requirements (3.0/3.1, internal $ref only, servers, security), attaching openapi on navigation elements (directory, mixed pages, spec-qualified METHOD /path, hosted-spec redeploys, --local-schema). Adds MDX from OpenAPI (multi-spec path warning, webhooks, openapi-schema, scraper), richer manual MDX API pages (ParamField/ResponseField, examples, per-page playground/authMethod, mdx.auth.name), and detailed x-mint operation customization.

^{Reviewed by Cursor Bugbot for commit 86a74ce. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
mintlify	🟢 Ready	View Preview	Sep 23, 2026, 6:01 PM