// Scan Warp Astro Starlight documentation for UI menu paths and Command Palette command names, then validate them against the warp-internal codebase for accuracy. Catch and surface outdated steps automatically.
| name | validate_ui_refs |
| description | Scan Warp Astro Starlight documentation for UI menu paths and Command Palette command names, then validate them against the warp-internal codebase for accuracy. Catch and surface outdated steps automatically. |
This skill scans Warp's Astro Starlight documentation for references to UI paths (e.g. Settings > AI > Active AI) and Command Palette command names (e.g. "Open Theme Picker"), then validates them against a snapshot of known-valid paths extracted from the warp-internal codebase.
From the docs repo root:
python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --all
--check-paths: Only validate UI menu paths (Settings, File, View, Warp Drive)--check-commands: Only validate Command Palette names--check-format: Check that UI paths use the canonical bold format: Settings > AI > Active AI--all: Run all checks (default)--fix: Auto-fix high-confidence issues (e.g. case mismatches)--create-pr: Create a branch and PR with auto-fixes (requires gh CLI)--slack-notify: Post results to Slack (only sends when issues are found; requires SLACK_BOT_TOKEN and SLACK_CHANNEL_ID env vars)--slack-channel ID: Override default Slack channel--include-changelog: Include changelog/ in the scan (excluded by default since it's a historical record)--refresh-valid-paths: Re-extract valid paths from warp-internal and update valid_paths.json--warp-internal-path PATH: Path to the warp-internal repo (default: ../warp-internal relative to docs root, or WARP_INTERNAL_PATH env var)--output FILE: Save results to a JSON filepython3 .warp/skills/validate_ui_refs/validate_ui_refs.py --check-paths
python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --all --fix --create-pr
The script outputs a report like:
=== UI REFERENCE VALIDATION REPORT ===
Generated: 2026-02-19T00:17:00Z
Files scanned: 174
### SETTINGS PATH ISSUES (5 found)
❌ "Current Theme" is not a known sub-section of Appearance
themes.md:26
Path: Settings > Appearance > Current Theme
Suggestion: Valid sub-sections: Themes, Icon, Window, Input, Panes, Blocks, Text, Cursor, Tabs, Full-screen Apps
⚠️ "active ai" is not a known sub-section of AI
codebase-context.md:34
Path: Settings > AI > active ai
Suggestion: Did you mean "Active AI"? (score: 0.92)
### COMMAND PALETTE ISSUES (1 found)
❌ UNMATCHED COMMAND
themes.md:26
Reference: "Open Theme Creator"
Did you mean "Open theme picker"? (score: 0.85)
The valid_paths.json file is a static snapshot of valid UI paths. To update it from the latest warp-internal source:
python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --refresh-valid-paths --warp-internal-path /path/to/warp-internal
This parses:
SettingsSection enum and Display impl from settings_view/mod.rsCategory::new(...) and build_sub_header(...) calls from settings page filesEditableBinding::new(...) registrations from terminal/view/init.rs and workspace/mod.rsThe macOS menu bar and Warp Drive sections are maintained as manual lists in valid_paths.json since they change infrequently.
Settings > [Section] > [Sub-section] — validates section and sub-section names against the SettingsSection enumFile > ..., View > ..., Warp > ... — validates against known menu itemsWarp Drive > ..., Personal > ... — validates against known spaces and object types`Settings > AI`), full bold wrapping (**Settings > AI**), italic, and bare formats are flagged--fix converts non-canonical paths to the correct bold formatSaveX", "click the X" are also caughtEnter, hit Esc) — "press" and "hit" are excluded from the check--fix converts backtick UI elements to boldCommand Palette > CommandName arrow patternschangelog/ directory (historical record; use --include-changelog to opt in)_book/ and node_modules/ build artifactsWhen run with --fix, the script automatically corrects:
Settings > ai → Settings > AISave → Click SaveFixes that require manual review (e.g. renamed sections, removed features) are reported but not auto-fixed.
Slack notifications are designed for scheduled/automated runs, not ad-hoc usage. When running the skill manually (e.g., during a PR review or docs update), you can review results directly in the terminal output.
The --slack-notify flag posts a summary to the configured Slack channel when unfixed issues remain after a run. If the scan is clean (0 issues), no notification is sent.
When this skill is configured as a scheduled cloud agent, Slack notifications should alert the team in two cases:
If a scheduled run finds no issues at all, the notification should be skipped (no noise).
Note: This two-condition notification logic is not yet implemented. The current
--slack-notifyflag only covers condition 2 (unfixed issues). When we set up scheduled runs, the script should be updated to also notify on condition 1 (auto-fixes with PR link).
Create a Warp team secret for the Slack bot token:
oz secret create SLACK_BOT_TOKEN --team --description "Slack bot token for UI ref validation reports"
The token needs chat:write scope.
python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --all --slack-notify
For scheduled cloud agent runs:
valid_paths.json up-to-date by running --refresh-valid-paths as a pre-step (requires warp-internal in the environment)SLACK_BOT_TOKEN secret in the environmentpython3 .warp/skills/validate_ui_refs/validate_ui_refs.py --all --fix --create-pr --slack-notifyA typical scheduled agent would:
--refresh-valid-paths to update the snapshot--all --fix --create-pr --slack-notify to check, fix, and reportrequests (for Slack notifications): pip3 install requestsgh CLI (for PR creation)warp-internal repo (only for --refresh-valid-paths)
Scan Warp Astro Starlight documentation for style guide violations including formatting issues (Settings path format, UI element format, header case, missing frontmatter, image alt text, callout syntax) and terminology issues (product name casing, Oz terms to avoid, deprecated terms). Run with --changed for PR workflows or --all for periodic audits. Optionally auto-fix high-confidence issues with --fix.
Answer questions about Warp, Oz, agents, terminal features, billing, pricing, troubleshooting, privacy, skills, MCP, integrations, or any other Warp-related topic. Use when a user, support person, or engineer asks a question that can be answered from Warp's documentation. Searches the docs, synthesizes a comprehensive answer, and provides links to relevant doc pages.
Find and fill documentation gaps in Warp's Astro Starlight docs by auditing coverage against code surfaces in warp-internal and warp-server, then drafting missing pages. Use when asked to find missing docs, audit documentation coverage, identify undocumented features, draft docs for new features, or do a docs coverage check. Runs a Python audit script to identify gaps, then researches source code and writes first-pass doc pages. Can run audit-only, draft-only, or end-to-end.
Detect new platform error codes in warp-server that are missing documentation pages in the docs repo. Creates doc pages, astro.config.mjs (sidebar config) entries, and redirects for any gaps. Use on a weekly schedule or when error codes change.
Audit docs.warp.dev for SEO issues like duplicate titles, missing meta descriptions, title length problems, and H1 tag issues. Crawls the live sitemap, generates a report, and fixes issues in the source files. Use when asked to check SEO, fix duplicate titles, audit meta tags, improve search rankings, or run an SEO check on the docs site.
Sync the public Oz Agent API OpenAPI spec from warp-server into the docs repo, regenerating `developers/agent-api-openapi.yaml` (the file that powers the Scalar API reference at `docs.warp.dev/api`). Use when the warp-server public API has changed, when the Scalar reference looks stale, or on a scheduled cadence to keep the public API docs aligned with the canonical spec.