​

Mintlify Documentation — CLAUDE.md

​

Project Context

• Platform: Mintlify (replaces GitBook)
• Format: MDX files with YAML frontmatter
• Config: docs.json for navigation, theme, and settings
• Components: Mintlify MDX components (Cards, Steps, Tabs, Accordions, CodeGroups, Callouts, etc.)
• Schema reference: https://mintlify.com/docs.json
• Full docs index: Append /llms.txt to the deployed docs URL for structured AI-readable index

​

Working Relationship

• ALWAYS ask for clarification rather than making assumptions about product behavior
• NEVER guess or fabricate feature descriptions — verify against the codebase in /nest and /next
• You can push back on documentation approaches — cite reasoning when you do

​

Content Strategy

• Document just enough for user success — not too much, not too little
• Prioritize accuracy and usability over completeness
• Make content evergreen when possible — avoid version-specific language unless necessary
• Search for existing content before adding anything new — avoid duplication
• Check existing pages for consistency before writing new ones
• Start by making the smallest reasonable changes

​

docs.json

• Refer to the docs.json schema when modifying navigation or settings
• Required top-level keys: theme, name, colors.primary, navigation
• Pages are referenced as relative paths without .mdx extension (e.g., "getting-started/introduction")
• The landing page is index.mdx, referenced in navigation as "index"
• Navigation uses groups with group (title) and pages (array) keys
• Empty groups (no pages) won’t render in the sidebar — add placeholder pages or remove the group

​

Frontmatter Requirements

---
title: Clear, descriptive page title
description: Concise summary for SEO and navigation
---

• sidebarTitle — abbreviated nav label when title is long
• icon — visual identifier in sidebar (Font Awesome, Lucide, or Tabler icons)
• tag — badge like “NEW” or “BETA” next to sidebar title
• hidden — removes from sidebar but keeps URL accessible

​

Writing Standards

​

Dual Audience: Humans + AI

1. Human readers who need to complete tasks quickly
2. Mintlify’s AI assistant (and external LLMs via llms.txt / MCP) which answers user questions by referencing your content

​

Core Principles

• Good: “To add a flag to a skill, navigate to Library > Skills > [Skill Name] and select Add Flag.”
• Bad: “Flags can be added to skills through the library interface where skills are managed by administrators who have the appropriate permissions.”

• Good: “Admin users can create custom flags. Manager users can apply flags to their direct reports. Standard users cannot modify flags.”
• Bad: “Different user types have different permissions when it comes to flags.”

• Good: “The Expert flag grants training approval rights. Users designated as Experts can approve training requests for their assigned skills.”
• Bad: “This flag grants training approval rights. They can approve training requests.”

​

Voice and Tone

• Direct: Use active voice. “Select Save” not “The Save button should be selected”
• Confident: State facts clearly. “This requires admin access” not “This may require admin access”
• Respectful: Assume user intelligence. Don’t over-explain obvious UI elements
• Helpful: Anticipate confusion and address it proactively
• Tone spectrum: Admin/technical content → more formal, precise terminology. End-user content → warmer, more supportive. Troubleshooting → calm, solution-focused.

​

Grammar and Mechanics

• Voice: Second person (“you”) — address the reader directly
• Pronouns: Use “you” for the reader. Use “we” for the product team (sparingly). Avoid “I” entirely. Never use ambiguous “it” or “this” without an explicit noun.
• Tense: Present tense for current features (“The flag appears in the table”). Future tense for outcomes (“This will create a new flag”). Imperative for instructions (“Select Save”).
• Sentences: Under 25 words when possible. One idea per sentence. Front-load key information.
• Paragraphs: 2-4 sentences maximum. Single-sentence paragraphs are acceptable for emphasis.
• Language: American English spelling (e.g., “organize” not “organise”).
• Prerequisites: List at the start of any procedural content.
• Code examples: Test before publishing; include language tags on all code blocks.
• Images: Alt text on all images; use relative paths; 20 MB max file size.
• Internal links: Use relative paths (e.g., /getting-started/introduction), never absolute URLs.

​

AI-Optimized Writing Patterns

​

Pattern 1: Explicit Capability Statements

[Role] can [action] when [condition].
[Role] cannot [action] because [reason].

Administrators can create and delete custom flags from **Company > Settings > Configure Flags**.
Managers can apply existing flags to users within their reporting structure.
Standard users can view flags assigned to them but cannot modify or apply flags.

​

Pattern 2: Structured Prerequisites

Before you [action], you need:
- **Permission level**: [Specific requirement]
- **Setup requirement**: [Specific state needed]
- **Access requirement**: [Specific access needed]

Before you create custom flags, you need:
- **Permission level**: Administrator role
- **Setup requirement**: At least one team created in SkillsDB
- **Access requirement**: **Company > Settings > Configure Flags**

​

Pattern 3: Cause-Effect Relationships

When you [action], [specific outcome occurs].

​

Pattern 4: Comparative Tables

| Element | Purpose | Available To | Example |
|---------|---------|--------------|---------|
| Expert flag | Identifies SMEs and grants training approval | Admins, Managers | Mark Sarah as Expert for Python |
| Mentor flag | Identifies coaching resources | Admins, Managers | Mark John as Mentor for Agile |

​

Pattern 5: Explicit Navigation Paths

• Good: “Navigate to Library > Skills > [Skill Name] > Expert Matrix”
• Bad: “Go to the skill’s Expert Matrix”

1. Navigate to **[Section] > [Subsection] > [Page]**
2. Select **[Specific Button Text]**
3. In the **[Modal/Page Name]**, [action]

​

Pattern 6: Conditional Logic

If [condition], then [outcome].
Otherwise, [alternative outcome].

If you are an Administrator, you can create flags for all users in the organization.
If you are a Manager, you can only apply existing flags to your direct reports.
If you are a Standard User, you can view flags applied to you but cannot modify them.

​

Pattern 7: Settings-Dependent Features

​

Formatting Standards

​

Headers

# Article Title (H1) — Only one per article
## Major Section (H2) — Primary content divisions
### Subsection (H3) — Subdivisions within H2
#### Minor Section (H4) — Use sparingly

• H2 headers should be task-oriented: “Creating a Custom Flag” not “Custom Flags”
• Exception: Concept sections can be noun phrases: “Understanding Flag Types”
• Never skip levels (don’t go from H2 to H4)

​

Lists

1. Navigate to **Company > Settings**
2. Select **Configure Flags**
3. Select **+ New**
4. Enter flag details
5. Select **Create**

Flags can be applied to:
- Individual skills
- Entire sections
- Complete careers

• Don’t use lists in the main overview/introduction
• Don’t list things that would be better as a table
• Don’t create single-item lists

​

Callout Components (Mintlify)

• Maximum 3 callout components per section
• Keep callout text to 1-3 sentences
• Always include a bolded label (e.g., Tip:, Warning:, Note:)

<Warning>
  **Warning:** Deleting a custom flag permanently removes all assignments. This action cannot be undone.
</Warning>

<Tip>
  **Tip:** Apply Expert flags at the career level to automatically designate someone as an expert for all underlying skills.
</Tip>

​

Tables

• Comparing features, options, or specifications
• Showing permissions matrices
• Listing field definitions
• Displaying keyboard shortcuts

• Keep columns to 5 or fewer
• Use sentence case for headers
• Keep cell content concise (under 20 words)
• Left-align text, right-align numbers

​

Code and UI Elements

• Button/menu text: Use bold — Select Save, Navigate to Company > Settings
• Field names: Use bold — Enter the Flag Name, Toggle Enabled
• User input examples: Use code formatting — Enter Expert in the Flag Name field, Set the limit to 50
• Code blocks: Use fenced code blocks with language tags for multi-line code, commands, or JSON
• Navigation paths: Always bolded and complete — Settings > Flags Configuration

​

Content Depth Guidelines

​

Overview Section (200-400 words)

• What this feature/concept is (1-2 sentences)
• Why it exists / what problem it solves (2-3 sentences)
• Who uses it / who it’s for (1-2 sentences)
• High-level benefits or outcomes (2-3 bullet points in prose, not list)

• Include key terminology that users might search for
• Define any ambiguous terms
• State relationships to other features explicitly

## Overview

Flags are special designations you can apply to skills and people in SkillsDB. They help
identify experts, mentors, focus areas, and potential within your organization. Flags can be
applied at multiple levels — from individual skills to entire careers — and unlock additional
functionality like training approval.

There are two types of flags: skill-related flags (applied to skills, sections, or careers)
and people-related flags (applied to individuals). The most important skill flag is the Expert
flag, which automatically grants training approval rights to designated users.

Only administrators can configure and manage flags. However, the functionality unlocked by
certain flags (like Expert designation) is available to all users who receive those flags.

​

Task Sections (minimum 150 words per task)

1. Context statement — One sentence explaining when/why to do this
2. Navigation/Access — How to reach the starting point
3. Step-by-step instructions — Numbered list of actions (use <Steps> component)
4. Outcome statement — What happens when complete
5. Optional: Next steps — What users typically do after

• Start each instruction with an action verb
• Include the full path even if mentioned elsewhere
• State the outcome explicitly, don’t assume it’s obvious

### Creating a Custom Skill Flag

Custom skill flags let you create organization-specific designations beyond the four system
defaults (Expert, Mentor, Focus, Interest).

<Steps>
  <Step title="Open flag settings">
    Navigate to **Company > Settings > Configure Flags**
  </Step>
  <Step title="Add a new flag">
    In the "Flags that apply to skills, sections, and careers" section, select **+ New**
  </Step>
  <Step title="Configure the flag">
    Enter a **Flag Name** (maximum 50 characters). Toggle **Trainer** on if this flag should
    grant training approval rights.
  </Step>
  <Step title="Save">
    Select **Create**
  </Step>
</Steps>

The new flag appears in the skill flags table and becomes immediately available for assignment
throughout SkillsDB. Users with appropriate permissions can now apply this flag to skills,
sections, or careers.

​

Common Questions Section

• Use <AccordionGroup> with <Accordion> components for each question
• Phrase questions exactly as users would ask them
• Provide yes/no answers before elaborating
• Include alternative phrasings in the question

1. Capability questions — “Can I [action]?”
2. Limitation questions — “What happens if [edge case]?”
3. Troubleshooting questions — “Why is [problem] happening?”
4. Best practice questions — “Should I [approach A] or [approach B]?”

## Common Questions

<AccordionGroup>
  <Accordion title="Can I create unlimited custom flags?">
    Yes, you can create as many custom flags as needed for both skills and people. However,
    consider whether each flag serves a distinct purpose to avoid confusion. Most organizations
    use 2-5 custom flags in addition to the system defaults.
  </Accordion>
  <Accordion title="What happens to existing flag data if I disable a flag?">
    All existing flag assignments are preserved when you disable a flag. Disabling a flag
    simply hides it from view throughout SkillsDB — users won't see it in dropdowns, tables,
    or matrices. You can re-enable the flag anytime to restore visibility without needing to
    reassign it to anyone.
  </Accordion>
  <Accordion title="Can the same person have multiple flags for one skill?">
    Yes. A person can have multiple flags for the same skill. For example, someone could be
    both an Expert (can approve training) and a Mentor (guides others) for Python. Each flag
    serves a different purpose and they can coexist.
  </Accordion>
</AccordionGroup>

​

Required Article Structure

1. Frontmatter — YAML metadata (title, description minimum)
2. Title — Clear H1 with feature/concept name (auto-generated from frontmatter title in Mintlify)
3. Quick Summary — <Info> callout with 1-2 sentence TL;DR
4. Overview — What/why/who in 200-400 words
5. Prerequisites (if applicable) — Required permissions, setup, or knowledge
6. Main Content — Task-oriented sections with clear H2 headers, 150+ words each
7. Common Questions — FAQ using <AccordionGroup>, minimum 3 questions
8. Related Articles — Cross-references to related content using <CardGroup> / <Card>
9. Need More Help? — Support contact info

• Advanced Options — Power user features
• Troubleshooting — Common problems and solutions (see Special Content Types)
• Examples — Real-world use cases
• Best Practices — Tips for optimal usage

​

AI Agent Optimization Checklist

• All prerequisites are explicitly stated in a Prerequisites section
• Every task includes the full navigation path from the top level
• All tables have clear, semantic column headers
• Code blocks include language specification

• No ambiguous pronouns (it, this, that, they) without explicit antecedents
• All conditional statements use “If…then…” structure
• All capability statements follow “[Role] can/cannot [action]” pattern
• All outcomes are stated explicitly (“This creates…” not “You’ll see…”)

• Every feature mentioned has a brief explanation inline (no dangling references)
• All acronyms are defined on first use
• All relationships between features are explicitly stated
• All limitations and edge cases are documented

• Article includes all common search terms users might use
• Headers use natural language (how users think about tasks)
• Alternative terminology is mentioned where appropriate
• Related articles are cross-linked

​

Quality Standards

​

Accuracy Requirements

• Button text must match actual UI exactly (case-sensitive)
• Navigation paths must be complete and correct
• Field names must match the product precisely
• Error messages should be quoted exactly

• Test all workflows before documenting them
• Verify permissions and role restrictions
• Confirm field validations and limits
• Check feature availability across plans/tiers

​

Completeness Standards

1. What is this? (Definition and purpose)
2. Who is it for? (Roles and permissions)
3. When would I use it? (Use cases and scenarios)
4. How do I use it? (Step-by-step instructions)
5. What can go wrong? (Limitations and edge cases)
6. What’s related? (Connected features and workflows)

• Overview: 200-400 words
• At least 2 task sections: 150+ words each
• At least 3 common questions
• At least 3 related article links

​

Consistency Standards

• Use product terminology exactly as it appears in the UI
• Never mix synonyms (choose one term and stick with it)

• Product feature names: Sentence case (“Training approval” not “Training Approval”)
• UI elements: Match the UI exactly
• Section headers: Sentence case
• Button text: Match the UI exactly (including case)

• Always use: Section > Subsection > Page
• Always bold the full path
• Use full paths even when abbreviated elsewhere

​

Examples: Good vs Bad

​

Permission Statements

Different users can do different things with flags depending on their role.

Administrators can create, edit, and delete custom flags from **Company > Settings > Configure Flags**.
Managers can apply existing flags to users within their reporting structure.
Standard users can view flags assigned to them but cannot modify or apply flags.

​

Task Instructions

To create a flag, go to settings and add one. Fill in the information and save.

<Steps>
  <Step title="Open flag settings">
    Navigate to **Company > Settings > Configure Flags**
  </Step>
  <Step title="Add a new flag">
    In the "Flags that apply to skills" section, select **+ New**
  </Step>
  <Step title="Configure">
    Enter a **Flag Name** (maximum 50 characters).
    Toggle **Trainer** on if this flag should grant training approval rights.
  </Step>
  <Step title="Save">
    Select **Create**
  </Step>
</Steps>

The new flag appears in the skill flags table and is immediately available for assignment.

​

Feature Relationships

Flags work with the training system to help manage approvals.

The Expert flag is integrated with SkillsDB's training approval system. When you designate
someone as an Expert for a skill, they automatically gain the ability to approve training
requests for that skill. Expert-designated users receive training requests in their Inbox
and can approve or deny them from **Team > Skills > Training Matrix**.

​

Conditional Logic

You might be able to see the Training Matrix depending on your permissions.

Access to **Team > Skills > Training Matrix** depends on your role:
- Managers can always view the Training Matrix for their team
- Users designated as Experts can view the Training Matrix for skills where they are Experts
- Standard users without Expert designation cannot access the Training Matrix

​

Writing Process

​

1. Research Phase (before writing)

• Read Linear issues/PRDs for the feature
• Access staging/production to verify UI
• Review code for validation rules and error messages
• Identify related features and dependencies Identify structure:
• List all user roles involved
• Map all workflows/tasks users perform
• Identify edge cases and limitations
• Note common questions from support tickets

​

2. Drafting Phase

1. Frontmatter — Set the scope (title, description)
2. Overview — Establish context
3. Task sections — Core instructional content
4. Common Questions — Address edge cases
5. Related Articles — Create connections
6. Prerequisites (if needed) — Fill in requirements

• Write for clarity first, optimization second
• Link to related articles as you write (even if they don’t exist yet)
• Flag any questions or uncertainties for the user — do not leave TODO/FIXME comments in the published MDX

​

3. Optimization Phase

• Remove all ambiguous pronouns
• Add explicit capability statements
• Convert vague conditionals to “If…then…” format
• Ensure all task sections include full navigation paths
• Add tables where comparisons exist

• Break up long paragraphs
• Add callout components for important information
• Ensure scannable structure with clear headers
• Vary sentence length and structure

​

4. Review Phase

• Read article out loud — does it sound natural?
• Can each section stand alone if quoted by the AI?
• Are all terms defined on first use?
• Do all internal links work?
• Does it pass the “five-year-old test” (no unexplained jargon)?

• Pick 5 questions a user might ask about this topic
• Can you find a complete answer by reading one section?
• Are answers unambiguous (yes/no, or clear explanation)?

​

Special Content Types

​

Troubleshooting Content

### Problem: "Flag name already exists" error when creating a flag

**Symptoms:** When you select **Create** after entering a flag name, you see an error
message: "A flag with this name already exists."

**Cause:** Flag names must be unique across your entire SkillsDB instance. This error
appears when you try to create a flag with a name that matches an existing flag, including
system flags (Expert, Mentor, Focus, Interest).

**Solution:**
1. Select **Cancel** to close the create flag modal
2. Review the existing flags in the flags table to see what names are taken
3. Choose a different, unique name for your flag
4. Try creating the flag again with the new name

**Prevention:** Check the existing flags list before creating new flags to avoid naming
conflicts.

​

Conceptual Content (vs. task-based)

• Clear definition in first paragraph
• Real-world analogy or example
• Comparison to related concepts
• Visual representation (diagram or table)
• Link to task-based articles for “how to use”

​

API Documentation

• Endpoint URL and method
• Authentication requirements
• Request parameters table (name, type, required, description)
• Response schema with example
• Error codes table
• Rate limits

​

Maintenance and Updates

​

When to Update an Article

• UI text changes (button labels, page titles)
• Workflows change (different steps required)
• Permissions change (who can access)
• Features are added or removed
• Error messages change

• Related features change
• Best practices evolve
• Common questions emerge from support

​

Version Control

docs: update flags article with new Expert Matrix feature
docs: fix broken link in training approval section
docs: clarify permission requirements for flag creation

​

Getting Started Checklist

• Access to the product (staging or production)
• Linear issues or PRDs for the feature
• Access to the codebase (for verification against /nest and /next)
• This writing guide reviewed
• 2-3 existing articles from the same section read for tone matching

• Follow the Required Article Structure above
• Include all required sections
• Pass the AI Agent Optimization Checklist
• Be reviewed by someone familiar with the feature

​

Additional Resources

• Mintlify Documentation — Platform docs and component reference
• Mintlify MDX Components — Full component API
• Microsoft Writing Style Guide — Industry standard
• Google Developer Documentation Style Guide — Technical writing best practices

​

Questions and Feedback

1. Check this guide for relevant patterns
2. Look at existing articles for precedent
3. Consult with the docs team lead
4. Document your decision for future reference

​

Article Template (Mintlify)

---
title: Article Title
description: >-
  Action-verb lead, under 160 chars, includes key search terms.
icon: relevant-icon-name
---

<Info>
  **Quick Summary:** Brief 1-2 sentence overview of what users will learn or accomplish
  in this article.
</Info>

## Overview

Provide a brief introduction to the feature or concept (200-400 words). Explain:

- What it is
- Why users would use it
- Who it's for (if role-specific)

## Prerequisites

Before you begin, make sure you have:

- **Permission level**: Required role (e.g., Administrator, Manager)
- **Setup requirement**: Any necessary setup completed (e.g., SSO configured, team added)
- **Access requirement**: Specific navigation path or access needed

## How to [Main Task]

<Steps>
  <Step title="First Action">
    Clear description of what to do in this step.

    1. Specific action to take
    2. Another specific action
    3. Expected result or confirmation
  </Step>
  <Step title="Next Action">
    Continue with detailed instructions.

    <Warning>
      **Important:** Critical information users need to know to avoid mistakes.
    </Warning>
  </Step>
  <Step title="Final Steps">
    Complete the workflow with clear outcomes.

    <Tip>
      **Tip:** Helpful tips or best practices.
    </Tip>
  </Step>
</Steps>

## Advanced Options

### Optional Feature A

Explain advanced or optional functionality that power users might need.

### Optional Feature B

More advanced topics or edge cases.

## Troubleshooting

### Problem: [Common Issue]

**Symptoms:** What the user sees or experiences.

**Cause:** Why this happens.

**Solution:**
1. Step-by-step fix
2. Verification step

**Prevention:** How to avoid this in the future.

## Common Questions

<AccordionGroup>
  <Accordion title="How do I [common question]?">
    Provide clear, concise answer. Start with yes/no if applicable.
  </Accordion>
  <Accordion title="What if [edge case scenario]?">
    Address common issues or variations.
  </Accordion>
  <Accordion title="Can I [specific limitation]?">
    Clarify what is and isn't possible. State the reason.
  </Accordion>
</AccordionGroup>

## Related Articles

<CardGroup cols={2}>
  <Card title="Related Feature" icon="link" href="/path/to/page">
    Brief description of how it relates.
  </Card>
  <Card title="Another Related Topic" icon="link" href="/path/to/page">
    Brief description of how it relates.
  </Card>
  <Card title="Advanced Guide" icon="link" href="/path/to/page">
    Brief description of how it relates.
  </Card>
</CardGroup>

## Need More Help?

If you need additional assistance:

- Email [support@skillsdb.com](mailto:support@skillsdb.com)
- Use the in-app help chat
- Schedule a training session with your account manager

​

Available MDX Components

​

File Organization

help-docs/
├── docs.json                  # Mintlify config (navigation, theme, settings)
├── index.mdx                  # Landing page
├── CLAUDE.md                  # This file — Claude Code context
├── .mintlify/
│   └── Assistant.md           # AI assistant behavior customization
├── getting-started/           # Onboarding and introduction
├── user-guide/                # End-user guides (7 pages)
├── manager-guide/             # Manager-specific guides (9 pages)
├── core-concepts/             # Platform concepts and features (19 pages)
├── configurations/            # Admin configuration guides (7 pages)
├── explore-your-org/          # Browse and search features (5 pages)
├── libraries/                 # Library management guides (4 pages)
├── org-settings/              # Organization settings (1 page)
├── scim/                      # SCIM provisioning and Azure sync (2 pages)
├── tutorials/                 # Step-by-step tutorials (9 pages)
├── use-case-guide/            # Industry use case guides (3 pages)
└── api-docs/                  # GraphQL API documentation (7 pages)

​

Local Development

# Install CLI (once)
npm i -g mint

# Preview locally
cd help-docs && mint dev

# Validate (CI-safe)
mint validate

# Check broken links
mint broken-links

# Accessibility audit
mint a11y

​

Relationship to Codebase

• Code changes that affect the UI should have corresponding doc updates in this directory
• The /update-docs skill automates identifying and drafting doc changes based on code diffs
• Engineers own doc updates — they happen in the same PR as code changes, not as a follow-up

​

Deployment Model

• PR merge → auto-deploy: Merging a PR into the deployment branch triggers a rebuild
• Open PRs → preview only: PRs get a preview URL and CI checks, but don’t affect live docs
• Web editor → creates PRs: Edits via the Mintlify web editor create GitHub PRs (they don’t push directly, especially on protected branches)
• No bypass needed: The GitHub App works within branch protection rules — no special permissions required

​

Do Not

• Skip frontmatter on any MDX file
• Use absolute URLs for internal links
• Include untested code examples
• Edit docs.json without validating the schema
• Add pages to docs.json navigation without creating the corresponding .mdx file
• Make assumptions about product behavior — verify against the actual codebase
• Hard-code version numbers in prose — use Mintlify variables ({{variable}}) if needed