Docs automation

How this site keeps itself in sync with ~40 public repos: the mintlify-docs-update skill, plus the five planned improvements.

The docs build themselves. Almost.

mintlify-docs-update is a Claude Code skill that scans JacobPEvans (and dryvist), diffs the result against this site, and proposes the missing pages. It lives in .claude/skills/mintlify-docs-update/ and is invoked manually via /mintlify-docs-update or on a cadence by the global auto-maintain orchestrator.

How the skill works

1. Enumerate repos

   gh repo list against JacobPEvans and dryvist.

2. Filter

   Keep public, non-archived, non-fork.

3. Diff

   Compare the filtered list against pages already on this site.

4. Scaffold

   For each missing repo, copy template-repo-page.mdx and update docs.json sidebar.

5. Validate

   Run the page-length guard and mint broken-links before reporting back.

The skill is conservative: it only scaffolds missing pages. Existing pages are never overwritten. The author edits in detail, then commits.

Page tiers

Every page declares a tier in frontmatter. The skill enforces caps:

Tier 1 — overviews & landings

First-encounter pages. Single screen. ≤450 words. No scrolling on a 1080p browser.

Tier 2 — repo & technical

Repo deep dives and how-to pages. 1–2 screens. ≤900 words. Over budget → split into sub-pages.

Planned improvements

These five skills are filed as GitHub issues and tracked in the enhancement + skill labels.

mintlify-page-author

Author a single page from a repo URL or topic. Enforces Reef Green theme, house voice, the tier cap, and standard components (Card grid + Steps + Frame + Mermaid).

mintlify-visual-audit

Grade every page on tier-aware word count, component variety, theme compliance, dead-link risk. Output: red/amber/green report with a prioritized fix list.

mintlify-mermaid-theme

Generate Reef Green-themed Mermaid with pinned theme variables and house shape conventions. Wraps obsidian-visual-skills:mermaid-visualizer with project-specific defaults.

mintlify-nav-sync

Keep docs.json sidebar in sync with the filesystem. Detect orphan pages, missing files, and propose ordered group structures.

mintlify-build-guard

Pre-commit + CI validator. mint dev + mint broken-links + frontmatter check + image refs + tiered word cap + Mermaid parse. Pass/fail report with line numbers.

All open issues

The live tracker for skill improvements.

Where to go next

Tools overview

The rest of the developer-utility surface.

claude-code-plugins

The broader plugin ecosystem this skill draws from.

Automation overview

The other half of the automation story — the issue → mergeable PR pipeline that runs across every JacobPEvans repo.

/ship and /finalize-pr

The Claude Code skill that takes a PR through CI, CodeQL, threads, and the final merge gate.