dotfiles

Records demo and verification videos of web pages using playwright-cli's screencast, and checks the result by inspecting extracted frames. Use when asked to record a video, screen recording, demo, or walkthrough of a web app or page; to show a flow working end to end; or to capture visual proof that a UI change behaves correctly. Not for making a thumbnail from an existing video (video-thumbnails), or for terminal recordings (terminal-control, terminal-fabricate).

C4 architecture diagrams - System Context, Container, Component, Code, plus Dynamic and Deployment views (Simon Brown's C4 model). Use whenever the user wants to draw, update, or review an architecture diagram, model or visualise a system's structure, reverse-engineer C4 from an existing codebase or repo, write or edit a Structurizr DSL workspace (workspace.dsl), or produce a Mermaid / PlantUML / D2 architecture diagram - even when they don't say "C4" (e.g. "diagram how this service fits together", "draw the containers for this repo").

Audit, implement, and fix web accessibility with a screen-reader-first lens. Use when building or reviewing UI components, forms, dialogs, navigation, dynamic content, or any interactive element. Covers WCAG 2.2 AA compliance, ARIA patterns, keyboard navigation, focus management, and assistive technology compatibility (NVDA, JAWS, VoiceOver). Trigger on: "accessible", "a11y", "screen reader", "WCAG", "ARIA", or when adding any interactive UI.

Writes and maintains architecture decision records (ADRs) for a decision that has already been taken, and reads existing records before touching what they govern. Use when asked to "write an ADR", "record this decision", "document why we chose X", "why did we do it this way", "supersede an ADR", "add this to docs/adr", or to write up a call after it was made - and when about to change a subsystem whose repo has an ADR directory. Not for reaching the decision: design-forking widens and compares the options, deciding-under-uncertainty commits to one as a calibrated bet, and architecture designs the target shape.

Audit a repository for agent readiness: can a coding agent (Claude Code, Codex, Cursor) change it and verify its own work without a human. Produces a repeatable report with a gated level, a flat score and gaps routed to the skills that fix them. Use when asked how agent-ready, AI-ready or autonomous-ready a repo is, for a readiness report, level or score, or to find what stops agents working unsupervised in a codebase. Not for fixing one known gap (use that gap's own skill) or reviewing a diff.

Design the target structure of software: clear boundaries, typed domain models, and testable flows. Use for substantial design work, hard-to-test code, domain modelling, module organisation, API and endpoint contract design, ports/adapters, functional core / imperative shell, explicit error handling, observability, or when code structure is fighting the change. Defines the target shape; the refactoring skill owns the migration path that moves existing code there safely.

Bootstrap or harden a project into a verified repository with official scaffolders and house conventions. Use for a new app, service, library or CLI; requests to scaffold, spin up or start a repo; and requests to bring an existing repository up to house standard. Also use in advisory mode when the user asks for a bootstrap plan or prompt. Do not use for feature work, deployment-only work, architecture selection before a stack is chosen, or an isolated lint, test or hook change in an established project.

Set up, deploy, and troubleshoot Cloudflare Workers projects using Wrangler, Workers Builds Git integrations, custom domains/routes, static assets, and Cloudflare Access. Use this skill whenever the user mentions Cloudflare Workers deployment, Workers Builds, GitHub-connected or GitLab-connected Workers, Wrangler static assets, Worker custom domains, build branches, preview builds, build watch paths, monorepo Workers Builds, build triggers, build logs, pnpm/npm/yarn/bun deploy commands in Workers Builds, creating a Worker project without deploying locally, or protecting a Worker hostname with Cloudflare Access.

Hardens a recommendation on a consequential, hard-to-reverse call into a calibrated bet with a pre-agreed exit, instead of a single confident verdict. Use when advising or deciding: build vs buy, adopt or swap a dependency or platform, migrate now or wait, rewrite vs refactor, quit or double down, ship or delay - any "should we / should I" where being wrong is expensive to undo. Also for judging a past decision fairly. Not for generating design alternatives - the design-forking skill owns widening the option set; this skill disciplines the commitment once a leading option exists.

Forks a design decision into genuinely different alternatives before committing - divergent thinking for software design. Use when facing an architecture or design decision, weighing approaches, or planning a non-trivial refactor; when the user asks for options, alternatives or trade-offs; when about to implement the first approach that came to mind for anything hard to reverse; or when reviewing a plan that considered only one design. This skill widens and compares the option set; committing to the winner as a calibrated bet with a pre-agreed exit is deciding-under-uncertainty's job.

Choose or distil canonical domain language through structured interrogation. Use when naming a new domain concept, pinning down a project's ubiquitous language, when a term fights its own definition, several words compete for one concept, a glossary has bloated, or a hidden concept needs surfacing before terms are written into CONTEXT.md.

Design messaging across service and process boundaries - when to go async, how events propagate between contexts, reliable publication (outbox/inbox, dual-write), delivery semantics (at-least-once, idempotent consumers, DLQ, ordering), and event/schema versioning. Use when work crosses a service boundary with queues, brokers, or streams (Kafka/RabbitMQ/SQS), integration events, or an evolving event schema.

Guides using formal methods and judging what a verification result actually establishes: model checking designs (TLA+, PlusCal, Quint, P, Alloy) and proving code or theorems (Lean 4, Dafny, Verus, Kani, SPARK, Bend 2). Use when writing or running a TLA+ spec or TLC model, proving something in Lean, adding Dafny or Verus contracts or Kani harnesses, reviewing an AI-written proof or spec, when someone says formally verify, prove correct, model check, invariant, liveness, sorry or axiom, or when deciding whether formal verification is worth it for a concurrency, distributed-systems, protocol or security bug. Not for weighing empirical evidence (prove-it) or ordinary test design, including property-based and simulation testing (testing).

Designs and critiques games, mechanics, encounters, progression, game feel and social play. Use when inventing a game or playable sequence, adapting reference games, improving shallow or boring play, interpreting playtest feedback, or deciding how rules and presentation create an intended player experience. Covers digital and non-digital design across genres. Not for an already specified engine optimisation, code refactor, asset export or deployment with no unresolved game-design decision.

Plays running games to verify connected progression, investigate control, camera and collision jank, and confirm repairs. Use when asked to playtest a build, check whether a game can be completed, reproduce a gameplay defect, or test a fix through actual play. The workflow targets browser execution; other engines need equivalent control and observation tools. Not for judging enjoyment, inventing game mechanics, visual target matching, or a specified unit-test change that needs no live-game investigation.

Sets up and uses AWS credentials through granted.dev's `assume`. Use when configuring AWS CLI or console access with granted, adding IAM-user access keys to the OS keychain, running `granted sso populate` for Identity Center, choosing between the IAM-user and SSO flows, opening the AWS console in a specific browser profile, or debugging `assume` / `granted credentials add` errors like "no such file or directory" on ~/.aws/config or "region not set on profile". Not for plain aws-cli profile config unrelated to granted.

Set up and maintain hk git hook manager in any repository. Use when adding pre-commit hooks, configuring linters, setting up code quality automation, working with hk.pkl, or maintaining existing hook configurations. Triggers on tasks involving hk, git hooks, pre-commit checks, commit-msg validation, or linting pipelines.

Produces evidence-led UX decisions from research and behaviour data. Use to diagnose user-facing drop-off, confusion, trust or recovery, synthesise UX research, or create a new analytical UX artefact before a solution is chosen. Supports experience-over-time maps, frontstage and backstage service maps, task decision and recovery maps, principle reviews and low-fidelity wireframes. The task must contain an unresolved experience question.

Create, update, validate, and submit Homebrew Casks (macOS and Linux/AppImage). Use when the user mentions Homebrew cask/cask, Homebrew/homebrew-cask, adding a new cask, updating a cask, cask token naming, sha256, url verified:, livecheck, zap/uninstall, AppImage/app_image, on_linux/on_macos, cross-platform cask, or when asked to run brew style/audit for a cask.

Create, update, validate, and submit Homebrew formulae (homebrew-core, built from source). Use when the user mentions a Homebrew formula, Homebrew/homebrew-core, adding/updating a formula, brew create, building from source, a build system in a brew context (cargo/rust, go, cmake, meson, autotools/configure, make, python virtualenv, node/npm, ruby gem), resource blocks, depends_on/keg_only/uses_from_macos, the mandatory test do block, bottles, livecheck, brew bump-formula-pr, or when asked to run brew audit --new / brew test / brew style for a formula. For macOS GUI apps and prebuilt binaries use the homebrew-cask-authoring skill instead.

Designs and builds application screens and task flows. Use when creating or improving a working user interface and deciding its screen structure, navigation, collection controls, repeated entry, progress or recovery. Covers review queues, editors, import screens and multi-step forms. Not for marketing pages, research diagnosis, feature prioritisation, or an already specified cosmetic or accessibility fix.

Control UTM virtual machines on macOS programmatically - create and configure VMs via AppleScript, manage lifecycle with utmctl, run commands and transfer files in guests, and set up Windows 11 ARM for headless automation (SSH, not the guest agent). Use whenever the user mentions UTM, utmctl, VMs on Apple Silicon, creating/cloning/scripting a virtual machine on a Mac, or wants to run commands inside a local Windows or Linux VM - even if they don't name UTM explicitly.

Diagnoses and fixes what a user sees on a route's first load - font-swap flashes, image decode pop-in, layout shift (CLS), slow LCP/FCP, blank-then-paint, hydration/theme flips, streamed-SSR skeletons that flash or pop, Lighthouse/PageSpeed complaints - on static (Astro/SSG), Vite SPA, SSR, or streamed routes (Next.js App Router/PPR, TanStack Start); a soft navigation is that route's first load. Use on "flash", "shimmer", "pop", "jump", "flicker", "skeleton", or slow first paint; when the LCP is webfont text or content fades in after JS; for font loading (self-hosted, Google Fonts, Adobe Fonts, next/font), image loading (next/image), Suspense boundary placement, skeleton swaps, subsetting fixed copy, resource hints, metric fallbacks; or to assert first-load invariants on built HTML, a booted route, or a streamed shell. Not for bundle-size analysis, steady-state INP, SEO, or backend latency past the TTFB-vs-skeleton trade-off; where a framework automates the fix, defer to its output but inspect wrapping code.

Look at real production websites before designing one. Searches a curated archive of 832 captured sites - screenshots, palettes, fonts, extracted design systems, reference components - filters it by style, vibe, macrostructure, colour, page type and industry, and downloads the screenshots so you can actually see them. Use before building any landing page, marketing site, dashboard, portfolio or app UI from a brief, when picking a visual direction or page structure, when a design needs a concrete reference rather than adjectives, or when the user asks what sites like theirs look like. Not for polishing UI you have already chosen, and not for one named brand's own site.

Writes durable, trustworthy documentation that does not rot - for AI agents (AGENTS.md/CLAUDE.md, skills) and humans (ADRs, READMEs, knowledge bases). Distilled from Cyrille Martraire's "Living Documentation". Use when authoring or reviewing an AGENTS.md/CLAUDE.md, writing a skill, writing an ADR or doc, deciding whether something is worth documenting, or when docs keep going stale. Triggers: "living documentation", "is this doc trustworthy", "should this be documented", "why does this doc keep going stale", "doc rot", "documenting a legacy or inherited codebase", "rescuing a codebase nobody understands".

Design, review, or refactor logging for a service so it works as an observability primitive - the canonical wide-event / structured-log pattern. Use when the user is setting up logging for a new service, adding or auditing middleware, building a logger config (structlog, pino, winston), enabling Cloudflare Workers observability or Analytics Engine, instrumenting OpenTelemetry logs, planning sampling strategy, proposing logging schema changes, or saying things like "our logs are noisy", "we can't find anything in the logs", "improve our logging", or "add proper logging". Do NOT trigger for single casual `console.log`/`print`/`logger.info` additions during unrelated work.

Catalogue of preferred linter rules, TypeScript flags, clippy thresholds, import-boundary checks, contract-compat gates, and architecture tests for making bug classes and design drift mechanically impossible. Use when setting up linting in a new project, hardening an existing project, responding to a class of bug by encoding a rule, or deciding which linter to reach for on a given stack. Pairs with the `hk` skill which handles wiring hooks.

Persistent browser and Electron interaction through `js_repl` for fast iterative UI debugging.

Decide what to build before committing to a named solution: reframe outputs as measurable behaviour-change outcomes, map alternative opportunities, and find the cheapest test of the riskiest assumption. Use when a feature request names a solution with no stated outcome, when prioritising or choosing what to build next - "what should I build", "roadmap", "which of these ideas", "is this feature worth building" - or before writing a PRD for a product-facing feature. Sits upstream of PRD/spec writing, which specs a committed feature; for journey maps, wireframes, or service blueprints use holistic-ux; for forking software-design alternatives use design-forking.

Tests whether evidence warrants an empirical claim at its stated strength and scope. Use when declaring a bug fixed or a root cause found, closing an investigation, validating or verifying a factual conclusion, auditing the factual premises of a plan, or when the user says prove it, are we sure, or asks whether evidence really supports a claim in any domain. Not for mathematical or formal proof, type-system guarantees, choosing among forward-looking options, or designing the test itself.

Write idiomatic, type-safe Python: errors as values (Result/typed errors) and composing them, parse-don't-validate with pydantic, frozen kw-only dataclass value objects, unions with match and assert_never (structural pattern matching), Protocol vs ABC ports, persistence-ignorant domain models, package layout, import discipline and circular imports, config parsed once at a composition root that is a scope (DI/bootstrap), structured concurrency with asyncio task groups and retries, smart constructors, which interpreter and library versions to target, basedpyright, and the Any/cast/type-ignore discipline. Use when designing or reviewing Python specifically. Routing: architecture for agnostic design, mechanical-enforcement for lint and type-checker config, testing for test strategy.

Build, maintain, and review Raycast extensions (the @raycast/api / TypeScript apps published to github.com/raycast/extensions). Use whenever the user mentions a Raycast extension, command, or tool; the @raycast/api or @raycast/utils packages; List/Detail/Form/ActionPanel/MenuBarExtra UI; useCachedPromise/useFetch/useForm hooks; getPreferenceValues; the ray CLI (ray develop/build/lint/evals); an AI extension or AI tools; preparing/publishing an extension to the Raycast Store; or reviewing an existing extension against store guidelines. Also use for "scaffold a Raycast command", "my Raycast extension errors", "fix the manifest", "add a preference", "add an OAuth login", or porting a CLI/app idea to Raycast - even if they don't say "@raycast/api" explicitly.

Refactor and restructure existing code safely without stopping delivery. Use when inheriting a legacy, untested, or vibe-coded/AI-generated codebase, deciding where to start on a ball of mud, planning an incremental migration to a new architecture, ORM, framework, or provider, replacing a dependency without a feature freeze, making zero-downtime database schema changes, escaping a long-lived rewrite branch, or paying down technical debt. Owns the migration path and its sequencing; the architecture skill owns the target shape, the testing skill owns test design.

Performs static-first reverse engineering and binary decompilation without launching the target. Use when the user asks to inspect, decompile, triage, recover symbols/types/strings, identify endpoints/models/dependencies, explain executable behaviour, or recover implementation patterns from an unknown, stripped, packed, or obfuscated binary, CLI, DMG, macOS app bundle, Mach-O, ELF, PE, WASM, firmware image, Go binary, Android APK/XAPK/AAB, or packaged JavaScript/TypeScript executable. Also use for jadx, apktool, Ghidra, IDA, Binary Ninja, radare2, strings, xrefs, Swift/Objective-C metadata, Bun compile, Node SEA, pkg/nexe, and Deno compile analysis. Not for source-only code review or ordinary archive extraction where executable behaviour is irrelevant.

Harden software supply chains across ecosystems (npm/pnpm/bun/yarn/aube, uv/pip, Cargo, GitHub Actions/aqua) by reasoning about what installing or importing a dependency actually executes, then choosing controls: release-age quarantine gates, install-script and load-time trigger removal, lockfile pinning and checksums, provenance/SLSA verification, and osv-scanner malware detection. Use when hardening a project or machine/global config (new or incremental); when converting age-gate settings/units between package managers; when a gate fires mid-task - a blocked install or build script, an age-gate or provenance refusal, a slopsquatted or unfamiliar package - and you must decide whether to allowlist; when adding a dependency you have not vetted; or when auditing a suspected compromised package. For linter rules, gitleaks, and zizmor use the mechanical-enforcement skill; for wiring checks into git hooks use the hk skill; for code-level vulnerability review of your own code use security-review.

Systematically audit, improve, and enforce test coverage, and gate test quality in CI - across any ecosystem (TypeScript, Python, Go, Rust). Use to raise coverage, set thresholds, audit gaps, manage exclusions, merge reports, wire coverage into CI/hooks, or add mutation testing and fuzzing as quality gates. Composes with the hk skill for pre-commit enforcement. For how to design and write good tests - property-based, snapshot/approval, differential, contract, flaky-test handling - use the testing skill.

Design and write effective tests for behavioural changes, bug fixes, and refactors. Use when choosing a test layer, practising TDD, picking doubles/fakes, designing scenario or e2e suites for critical journeys, reducing brittle or flaky tests, designing the characterisation tests that make refactoring safe, or applying property-based, snapshot/approval, differential/metamorphic, or contract testing. For coverage, thresholds, mutation testing, fuzzing, and CI/hook enforcement, use the test-coverage skill; for legacy migration and refactoring strategy, use the refactoring skill.

Write idiomatic, type-safe TypeScript: errors as values and composing them, parse-don't-validate, branded and domain types, the record-type choice (interface, type, class, brand, readonly, as const satisfies), deep domain modules and import cycles, cancellation with AbortSignal and structured concurrency, resource and transaction scopes with using and AsyncDisposableStack, the composition root, retries and the injected clock, exhaustiveness and the cast/`any`/`!` discipline, the Effect adoption boundary, and which compiler and runtime to target (TS 7, Node, Bun, Deno, erasable syntax). Use when designing or reviewing TypeScript specifically. Routing: architecture for agnostic design, mechanical-enforcement for lint and tsconfig config, testing for test strategy, the vendored effect skill for programs written in Effect.

Guides creating, editing, reviewing, and debugging Agent Skills and SKILL.md directories. Use when writing a new skill, improving or reviewing an existing skill, fixing a skill description or frontmatter, structuring references, scripts, assets or evals, packaging a skill, or diagnosing a skill that does not trigger or does not change agent behaviour. Covers portable Agent Skills spec, progressive disclosure, eval design, and client compatibility notes. Not for using an existing skill to perform its domain task.