agentic-dotfiles

Generate and serve rich HTML companions to markdown discovery documents: paired markdown→HTML rendering (marked + mermaid + data-driven cytoscape/plotly fenced blocks), a vendored draw.io stencil library (~AWS/GCP/Azure/K8s SVG icons) for composing custom architecture diagrams, an injectable design-tokens brandpack, and a reliable localhost server for HTML that pulls pinned CDN libraries. Use when turning a review/architecture/cost markdown doc into an interactive HTML view, when a diagram needs real cloud provider icons, when serving local HTML that file:// breaks, or when building a data-driven graph/chart view. Skip when the deliverable is plain mermaid-in-markdown authoring with no HTML companion, or a Python-rendered architecture diagram image.

Introspect Claude Code sessions - query conversation history, tool usage, event trees, and costs. Use when reviewing past sessions, debugging failures, or recovering user intent post-compaction.

Documentation quality skill with three modes: (1) AUDIT — fan out parallel subagents to corroborate that docs still reflect the reality of the code (commands run, paths exist, signatures match, claims hold) and produce a drift report; (2) WRITE/IMPROVE — author or rewrite docs using the researched lens taxonomy (Diátaxis + distilled style principles from great OSS docs), optionally in the maintainer's personal voice; (3) RESTRUCTURE — reorganize an existing doc, spec, or plan file for structural readability (heading hierarchy, list/table discipline, whitespace rhythm, BLUF) without changing its claims. Use when the user asks to check/audit docs, fix stale docs, write or improve documentation, restructure a doc/spec/plan for readability, or says 'gooddocs'. Add 'voice' to the invocation to write in the maintainer's voice; default is the neutral researched style.

Render and analyze Mermaid.JS diagrams embedded in markdown files. Enforces visual complexity limits AND WCAG color-contrast requirements via automated analysis. Every diagram MUST derive its palette from `resources/color_theming.md` and pass `scripts/mermaid_contrast.ts` before being declared done. Use when creating or updating architecture diagrams, analyzing diagram complexity, improving documentation clarity, or exploring a codebase to produce dual-density architecture diagrams for a README.

Playbook for building and extending project-local developer CLIs and the recurring assets they generate, so the same patterns are never re-derived from scratch. Use when: scaffolding or adding a subcommand to a repo CLI (argparse/Typer, project-root discovery, packaged assets); generating a STATIC HTML single-page viewer (client-side SPA routing, collapsible sidebar, light/dark + rebrandable design-tokens theming, Cytoscape graph or Plotly chart, generate/serve, --inline single-file, --archive zip); templating GitHub Actions workflows from a base template (create/update/validate, trigger-path glob distillation, reusable composite-action assets); using git worktrees to act on another branch/ref safely; autogenerating SVG/PNG diagrams from a stencil pack; or automating sticky PR comments and embedding a CI-run artifact image in a PR comment. Skip for non-CLI app code, or one-off scripts with no reuse. Invoke as /cli or when the user names one of these patterns.

Script-driven gap-analysis planning: a deterministic state machine (pgsm.py) owns the phases of a tiered gap-analysis spec — bootstrap → refinement → validation → decomposition → execution → complete — with evidence-based transition gates, per-state-only instructions composed into a single prompt, durable pause/resume state, and session-log forensics. Use for long-horizon work-breakdown planning where phase tracking must not live in the model's head. Requires uv. Skip for quick single-file plans (use plan-gap) or when no plan document is wanted.

Principled, evidence-based code review of a diff, branch, or PR. Runs parallel perspective passes, validates every candidate finding before reporting, and filters aggressively for precision over volume. Use when the user asks to review code, a diff, a branch, or a pull request with this skill.

Walk a human through any PR or diff, regardless of size. Distills 100s-1000s of changed files into their deeper structure: a few distinct mechanical change patterns (each shape-checked for hidden deviants) plus the genuinely novel changes, then acts as an interactive guide revealing detail incrementally until the reviewer is satisfied. Use when the user says 'walk me through this PR', 'explain this diff/PR', 'what actually changed here', or faces a huge PR they can't review file-by-file. Skip when the user wants a verdict on code quality — that's /codereview.

Macro-level, evidence-based refactoring: maps the system's dependency structure and churn hotspots, reads ADRs and project decisions as a lens of values, and executes behavior-preserving change in small test-guarded steps. Use when the user asks to refactor, restructure, untangle modules, reduce coupling, or 'clean up' a codebase area. Skip for pure formatting (linters own that) and for bug fixes or feature work (refactoring never mixes with behavior change).

Deterministic, offline image post-processing — background removal (U2-Net or distance-from-white), multi-signal alpha matting, a 'steps' pipeline visualiser that emits intermediate masks for visual debugging, and two-tone wordmark composition. Every output gets a JSON sidecar recording the exact settings so any edit is reproducible. Use when the user wants to make a generated image's background transparent, crop to content, build a matte, debug a segmentation pipeline, or add a text wordmark — without paying for a fresh AI generation. Runs entirely offline (no API key).

Generate images from curated prompt files via Google's GenAI image models (Gemini 'Nano Banana' + Imagen 4). Each image is written with a JSON sidecar recording the exact prompt and settings, so runs are reproducible and the next prompt can be curated from prior ones. Supports fan-out across multiple prompt files in one invocation. Use when the user wants to generate, explore, or iterate on logos, icons, illustrations, or other AI imagery from text prompts. Requires a non-empty GOOGLE_API_KEY.

Generate cloud architecture diagrams (AWS, GCP, Azure, Kubernetes, on-prem) as code using the Python `diagrams` library (mingrammer/diagrams). Provides guidance on layout engines, graph attributes, cluster design, and edge routing for production-quality infrastructure diagrams, plus a runnable example gallery.

Gap analysis planning mode. Iteratively refines a gap analysis spec — a tiered file set (index + per-gap + per-ticket + discovery files, or a GitHub issue with per-gap sub-issues) covering Execution Plan, Overview, Gap Analysis, Decisions (ADRs), Success Measures, and Negative Measures, with Current/Desired State held in a review-only Discovery file. Validates Mermaid diagrams and enforces requirement integrity through structured questioning.

Split and trim a single source video into multiple chapter mp4s via a hand-edited JSON spec (edits.json). Uses ffmpeg for frame-accurate cuts and configurable output filenames. Use when the user wants to chapter a long recording, trim sections out of a video, or produce per-chapter mp4s from one source with custom naming conventions.

Local Whisper speech-to-text via mlx-whisper (Apple Silicon native). Produces an SRT subtitle file from any audio or video file ffmpeg can decode. Use when the user wants to transcribe audio, generate subtitles, or produce a verification copy of an existing transcript.

Automated setup for a fullstack web app — Python (FastAPI + uv) backend + React/Vite/TypeScript/Tailwind/shadcn/Biome/Vitest/Playwright frontend, sibling `backend/` and `frontend/` directories under a top-level Makefile that delegates per-language targets (`format-ts`/`format-py`, `lint-ts`/`lint-py`, `typecheck-ts`/`typecheck-py`, `test-ts`/`test-py`) and rolls them up into `format`, `lint`, `typecheck`, `test`, with `make fix ci` as the canonical inner-loop. Use when scaffolding a new fullstack web application with a Python API backend and a React frontend, initializing the standard `backend/` + `frontend/` project layout, or asking for "Python + React fullstack".

The 5 Why's is a root cause analysis technique that helps you identify the underlying cause of a problem by asking 'why' five times. This skill guides you through the process of applying the 5 Why's to a problem statement, allowing you to uncover the root cause and potential solutions.

Automated setup for Vite + React + TypeScript + Tailwind CSS v4 + shadcn/ui + Vitest + Playwright + Biome projects, using bun as the runtime and package manager. Includes GitHub Actions workflow with build, e2e, and Pages deploy. Use when setting up new React projects, creating Vite apps, initializing React TypeScript projects, or setting up modern React development environments.

Attention Is Scarce. Use mid-session when two or more ambiguities have accumulated and you'd otherwise interrupt the user with several questions. Consolidates the open question set into the single highest-leverage multiple-choice question with a recommended pragmatic default, then cascades the answer across every related ambiguity before asking another.

Evidence-based AI coach/tutor for any topic. Researches the topic via parallel subagents (web, arxiv, GitHub, official docs), produces a ≤5-bullet precise summary in plain language, then runs a one-question-at-a-time Socratic quiz loop (multiple-choice or open-ended, learner's choice each turn) that diagnoses misconceptions and builds a persistent model of the learner's knowledge gaps. Use when the user wants to learn, be quizzed on, be coached through, or build deeper understanding of a topic. Also use when the user says 'coach me on X', 'teach me X', 'quiz me on X', or 'help me understand X'.

Add or update a markdown file's table of contents (TOC) based on its header structure. Use when creating new documentation, updating existing files, or ensuring TOC accuracy. Supports GitHub-style TOC with configurable header levels.

Expert assistance with Snowflake connectivity and dbt Cloud. Use when working with Snowflake databases, testing connections, running dbt commands, or debugging environment setup issues.

Query language servers (pyright, typescript-language-server) for code intelligence — symbols, definitions, references, hover info, diagnostics, and impact analysis. Use for exploring codebases, planning code changes, and reviewing change impact across Python and TypeScript projects.

Manage hierarchical planning documents with token-budgeted lazy loading, automatic rebalancing, and cascading context injection. Use when working with large planning docs, splitting oversized plans, or loading plan hierarchies into context efficiently.

Ensure every stated user requirement is treated as mandatory to be implemented correctly BEFORE considering designing graceful degradation paths. Invoke this during planning. Review a plan or implementation for requirement erosion — where explicit requirements have been silently downgraded to optional/fallback/skip-with-warning patterns.

Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.

Inject captured OAuth/Firebase auth state into Playwright MCP browser sessions. Use when testing authenticated pages with Playwright MCP, debugging Firebase auth issues, or setting up E2E auth capture workflows for Google OAuth.

Expert assistance with Vite + React 19 + TypeScript + Tailwind CSS v4 + Shadcn UI + Vanilla JS Google ADK integration. Use when building frontend applications with SSE streaming, session management, or working with this specific tech stack. Specializes in the project's patterns for ADK agent communication, styling conventions, and component architecture.