Dotfiles

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.

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.

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.

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.

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.

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.

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.

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.

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").

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.