​

Mintlify documentation

​

Working relationship

• ALWAYS ask for clarification rather than making assumptions
• NEVER lie, guess, or make up information
• Push back if something seems wrong or like it makes the documentation worse
• NEVER be agreeable just to be nice - I need your honest technical judgment.
• NEVER tell me I’m “absolutely right” or anything like that. You ARE NOT a sycophant.
• If you are making an inference, stop and ask for confirmation or say that you need more information

​

Context and tool usage

​

Context management

• Read only files necessary for the current task - avoid speculative “just in case” reading
• Ask for guidance on which files matter rather than reading multiple files to explore
• When context usage reaches 60% or higher, ask whether to compact before starting new complex tasks
• Use TodoWrite proactively for multi-step documentation tasks - todo lists prevent goal drift during context compaction by keeping objectives in recent context

​

Tool selection

• Use direct tool calls (Read, Glob, Grep) instead of sub-agents when you know file paths or can search for specific terms
• Only use the Explore agent for genuinely open-ended codebase searches
• Example: If asked to “update the accordion component docs”, read /content/components/accordions.mdx directly rather than spawning an agent to find it

​

Workflow for complex tasks

1. Complete a full end-to-end implementation
2. Present the output for review
3. Iterate with new prompts based on feedback

​

Project context

• Format: MDX files with YAML frontmatter
• Config: docs.json for navigation, theme, settings
  • See the docs.json schema: https://mintlify.com/docs.json
• Use Mintlify components. If you ever need to learn how a component works, search in the https://github.com/mintlify/docs/blob/main/components remote dir
• Only update English language content. All translations are handled automatically after a PR merges into the docs repo. This includes languages other than english in the docs.json navigation.

​

Content strategy

• We document just enough so that users are successful. Too much content makes it hard to find what people are looking for. Too little makes it too challenging to accomplish users’ goals.
• Prioritize accuracy and usability of information
• Make content evergreen when possible
• Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
• Check existing patterns for consistency
• Start by making the smallest reasonable changes
• When creating new pages, include them in the navigation group related to the user journey. For example, new content on customizing a site would go in the “Customize” group and information about adding a second deployment would go in “Deploy”

​

Frontmatter requirements for pages

• title: Clear, descriptive page title
• description: Concise summary for SEO/navigation
• keywords: relevant keywords for search and SEO

​

Audience

• The Ravenna audience is varied. Some people are highly technical and others are not
• We need to support users who prefer to work locally with the CLI and are comfortable with Git and people who use the web editor and prefer Git to be abstracted away

​

Writing standards

• Second-person voice (“you”)
• Prerequisites at start of procedural and tutorial content
• Match style and formatting of existing pages
• All code blocks must have language tags
• All images and media must have descriptive alt text
• Use root-relative paths for internal links like /content/components/accordions
• Lead with context when helpful - explain what something is before diving into implementation details
• Use sentence case for all headings (“Getting started”, not “Getting Started”)
• Use sentence case for code block titles (“Expandable example”, not “Expandable Example”)
• Use active voice and direct language
• Remove unnecessary words while maintaining clarity
• Break complex instructions into clear numbered steps
• Use Lucide icon library
• Use kebab-case for file naming

​

Language and tone standards

• Avoid promotional language: Never use phrases like “rich heritage,” “breathtaking,” “captivates,” “stands as a testament,” “plays a vital role,” or similar marketing language in technical documentation
• Reduce conjunction overuse: Limit use of “moreover,” “furthermore,” “additionally,” “on the other hand” - favor direct, clear statements
• Avoid editorializing: Remove phrases like “it’s important to note,” “this article will,” “in conclusion,” or personal interpretations
• No undue emphasis: Avoid overstating importance or significance of routine technical concepts

​

Technical accuracy standards

• Verify all links: Every internal link and external reference must be tested and functional before publication
• Use precise citations: Replace vague references with specific documentation, version numbers, and accurate sources
• Maintain consistency: Use consistent terminology, formatting, and language variety throughout all documentation
• Valid technical references: Ensure all code examples, API references, and technical specifications are current and accurate

​

Formatting discipline

• Purposeful formatting: Use bold, italics, and emphasis only when it serves the user’s understanding, not for visual appeal
• Clean structure: Avoid excessive formatting or decorative elements that don’t add functional value. Never use emoji
• Minimal markup: Keep formatting clean and functional, avoiding unnecessary markdown or styling

​

Component introductions

• Start with action-oriented language: “Use [component] to…” rather than “The [component] component…”
• Be specific about what components can contain or do
• Make introductions practical and user-focused

​

Property descriptions

• End all property descriptions with periods for consistency
• Be specific and helpful for actual use cases rather than generic
• Add scope clarification where needed (for example, “For Font Awesome icons only:”)
• Use proper technical terminology (“boolean” not “bool”)

​

Code examples

• Keep examples simple and practical
• Use consistent formatting and naming
• Provide clear, actionable examples rather than showing multiple options when one will do

​

Content organization

• Structure content in the order users need it with most commonly needed information first and most specific information last
• Combine related information to reduce redundancy

​

Git workflow

• NEVER use —no-verify when committing
• Ask how to handle uncommitted changes before starting
• Create a new branch when no clear branch exists for changes
• Commit frequently throughout development
• NEVER skip or disable pre-commit hooks

​

Before submitting work

• Preview changes locally with mint dev
• Run mint broken-links to check internal links
• Manually test external links don’t 404
• Run vale $(git diff --name-only main) to check style and spelling
• Verify all code blocks have language tags
• Confirm frontmatter includes title, description, keywords
• Check formatting matches similar existing pages
• Read changes aloud to catch awkward phrasing
• List any uncertain areas that need extra review

​

When submitting work

• What changed: Specific files and modifications
• Rationale: Why these changes solve the problem
• Alternatives considered: Other approaches evaluated
• Areas of uncertainty: What needs extra review

​

Documenting AI agent tools

​

For Ravenna (built-in) tools

• Add new tool as an accordion within the existing AccordionGroup
• Include tool description, common use cases, and example rules
• For approval/permission-based tools, include authorization requirements
• Follow the pattern established by existing tools

<Accordion title="Tool Name">
  Brief description of what the tool does and its purpose.

**Common use cases:**

- Use case 1
- Use case 2
- Use case 3

**Example rule:**

</Accordion>

​

For third-party integration tools

• New integration is added with agent tool support
• Existing integration adds agent tool capabilities

1. Create integration agent tools page at /integrations/{integration-name}/agent-tools.mdx Frontmatter:
   Copy

   Ask AI

   ---
   title: Agent Tools
   sidebarTitle: Agent Tools
   description: Use {Integration} tools in agent rules to [primary use case]
   keywords: {integration} agents, [relevant keywords], agent tools
   ---
   
   Content structure:
   • Introduction paragraph explaining tool capabilities with tooltip to agent rules
   • “Available tools” section with accordion for each tool
   • “Setup” section with steps
   • “Best practices” section
   • Link callout to agent configuration docs
2. Update configure.mdx - Add integration to the list under “Third-party integration tools”:
   Copy

   Ask AI

   - [{Integration Name}](/integrations/{integration-name}/agent-tools)
   
3. Update docs.json - Add agent tools page to integration navigation:
   Copy

   Ask AI

   {
     "group": "{Integration Name}",
     "icon": "/icons/{integration}.svg",
     "pages": [
       "integrations/{integration}/overview",
       "integrations/{integration}/setup",
       "integrations/{integration}/agent-tools"
     ]
   }
   

<Accordion title="Tool Action Name" defaultOpen>
  Description of what the tool does and what data it returns.

**Tool name:** `@Action with Integration`

**Input fields:** (if applicable)

- Field description

**Output data:** (if applicable)

- Data returned

**Common use cases:**

- Use case 1
- Use case 2
- Use case 3

**Example rule:**

</Accordion>

​

Reference existing examples

• Ravenna tools: /documentation/automate/agents/configure.mdx (Add Approver, Approve Ticket)
• Integration tools:
  • /integrations/fleet/agent-tools.mdx
  • /integrations/hubspot/agent-tools.mdx
  • /integrations/jamf/agent-tools.mdx

​

Do not

• Skip frontmatter on any MDX file
• Use absolute URLs for internal links
• Include untested code examples
• Make assumptions - always ask for clarification