skills

Use when reviewing PRs, examining code changes, running `gh pr diff`, or when asked for code review. Also trigger after completing a feature implementation when review is needed before merging. NOT for test quality (see test-design).

Git conventional commits — use this skill whenever authoring new git commits from working tree changes, writing commit messages, or planning how to organize changes into commits. Also trigger when grouping changes into logical commits, cleaning up a messy working tree, or when any agent needs to create commit messages as part of a workflow. NOT for non-authoring git operations (branching, merging, rebasing, cherry-picking, reverting, squashing, resolving conflicts, creating PRs, git configuration, or exploring git history).

You MUST consult this skill when choosing a concurrency architecture: thread topology (thread-per-core, work-stealing, event loop), unit of concurrency (actors, goroutines, state machines), or inter-component communication model (message passing, channels, shared memory). Also trigger when designing fault isolation boundaries, supervision trees, or backpressure propagation; when scaling a single-threaded design to multi-core; or when choosing between actor vs CSP channel models. NOT for lock primitive implementation, network protocol state machines, database connection pooling, language-specific async runtime config (tokio, asyncio), compute parallelism (SIMD, GPU), or distributed consensus (Raft, Paxos).

You MUST consult this skill when writing, reviewing, or fixing tests at any level (unit, integration, e2e). Also trigger when delivering features where tests are expected, when tests break on refactors, or when asking what makes a good test — even if 'write tests' wasn't explicitly requested. NOT for TDD workflow (see test-driven-development), test infrastructure setup (CI config, test runners), or diagnosing production code bugs.

You MUST consult this skill when writing, reviewing, or generating Odin code. Also trigger on .odin files, Odin package structure, allocator patterns, or any Odin-specific design question. LLMs have significant knowledge gaps about Odin — this skill fills them. NOT for general systems programming advice or C/Zig/Rust unless comparing to Odin idioms.

You MUST consult this skill when writing, reviewing, or designing code. Also trigger when code seems verbose or over-documented (unnecessary wrappers, comments restating the code), when design behavior is ambiguous (what should happen on empty input, which error to propagate), or when conventions are silently violated without explanation. NOT for debugging existing errors, language syntax questions, framework setup (CI/CD, database migrations), performance benchmarking, test quality criteria (see test-design), API surface conventions (see api-design), or abstract pattern theory discussions.

Application-level structural patterns -- layering, business logic organization, data access strategy, domain modeling, and cross-boundary communication. Use when designing a new service, choosing how to structure an application, or reviewing code for architectural smells (logic in controllers, no domain boundary, tangled data access). NOT for code-level design (see software-design), API surface conventions (see api-design), or infrastructure/deployment architecture.

You MUST use this before any creative work — creating features, building components, adding functionality, or modifying behavior. Also trigger when the user mentions brainstorming, wants to think through a design, stress-test a plan, or says 'grill me'. NOT for debugging, code review, writing tests, committing, or mechanical refactors (renaming, version bumps, config changes).

You MUST consult this skill when reasoning about or evaluating game design decisions — analyzing mechanics, diagnosing why a design feels wrong or shallow, evaluating whether a mechanic is interesting, or discussing game feel, player motivation, balance, or systemic design. Also trigger when a game feels one-note, shallow, or like every other game in its genre. NOT for engine-specific implementation (see godot, love2d) or shader/VFX work (see godot-shader).

You MUST consult this skill when designing applied narrative mechanics — deduction systems, mystery design, non-linear story discovery, search-based storytelling, NPC agency, or interactive storytelling techniques. Also trigger when writing NPCs that feel alive, designing detective game loops, structuring player-driven revelation, or making story feel non-mechanical. NOT for diagnosing story-gameplay conflict at the system level (see game-design) or engine-specific implementation (see godot, love2d).

Consult this skill when making game architecture decisions, choosing how to structure game systems, or asking which pattern fits a problem. Also trigger when designing entity/component systems, input handling, game state machines, event/messaging systems, object pooling, spatial queries, or scripting/modding support. NOT for engine-specific implementation (see godot, love2d, odin-gamedev). NOT for general software design outside game development (see software-design).

You MUST consult this skill when reasoning about visual design decisions that serve gameplay — art direction for legibility, color and contrast for communication, palette design, making simulation systems visually readable, or diagnosing why a game looks muddy, unreadable, or tonally wrong. Also trigger on visual hierarchy, player visibility, colorblind accessibility, or art that needs to communicate game state. NOT for shader/VFX implementation (see godot-shader) or engine-specific rendering (see godot, love2d). NOT for UI/UX layout.

You MUST consult this skill when designing or reviewing any API — REST, gRPC, or OpenAPI specs. Also trigger on resource modeling, field naming, pagination, error handling, versioning, custom vs standard methods, or reviewing an existing API for consistency problems — even if the user doesn't mention AEP. NOT for implementation details (framework setup, middleware config) or general software design (see software-design).

You MUST consult this skill when diagnosing or fixing game performance problems — profiling GPU/CPU/memory bottlenecks, improving frame rate, reducing battery consumption, fixing hitches or frame drops, or optimizing for constrained hardware (handheld, mobile, integrated graphics). Also trigger when a game runs at target FPS but utilization is dangerously high, or when frame pacing is inconsistent. NOT for network performance (latency, tick rate, bandwidth), loading time optimization, architectural patterns that prevent performance problems (see game-patterns), shader authoring (see godot-shader), or engine-specific profiling tool configuration.

You MUST consult this skill when reasoning about 3D rendering pipelines — coordinate spaces (model/world/view/clip/screen), perspective vs orthographic projection, affine transformations, triangle rasterization, barycentric coordinates, z-buffering, backface and frustum culling, UV mapping with perspective-correct interpolation, and lighting models (flat, Phong, multi-light blending). Also trigger when implementing a software renderer, debugging projection issues, or reasoning about what a GPU does internally. NOT for shader implementation in a specific engine (see godot-shader). NOT for art direction or visual legibility (see game-visuals). NOT for engine-specific renderer configuration.

You MUST consult this skill when reasoning about how modern GPUs are *driven* — bindless resources and descriptor heaps, 64-bit GPU pointers / buffer-device-address, GPU memory type selection (CPU-mapped vs GPU-private), GPU-driven and indirect/multidraw rendering, struct-based shader data model, PSO/state management and the PSO-permutation problem, modern stage-based barriers and timeline-semaphore synchronization. Engine-agnostic, grounded in Vulkan 1.3+ / DX12 SM6.6 / Metal 3+. NOT for software-rasterizer math (see game-rendering). NOT for engine/GDSL shader authoring (see godot-shader). NOT for GPU perf profiling or bottleneck diagnosis (see game-performance).

Use when working on game projects in Odin — Raylib/Sokol integration, entity management, game state architecture, hot reloading, or implementing game patterns in Odin. Takes precedence over game-patterns for Odin-specific implementation. NOT for language syntax or idioms (see odin-design). NOT for engine-agnostic pattern theory (see game-patterns).

You MUST consult this skill when deploying or operating a monitoring stack (Loki, Prometheus, Grafana, Alertmanager) on a homelab — k3s or Docker Compose. Also trigger when choosing a log collection agent (Alloy, Fluent Bit, Docker log driver), configuring retention, setting up alerting contact points (Discord, email, webhook), or troubleshooting Loki not ingesting logs, Prometheus showing 0 targets, or containers hanging due to the Docker log driver. NOT for query syntax (see logql, promql), dashboard authoring (see grafana), or cloud/EKS deployments.

You MUST consult this skill when authoring Grafana dashboards, configuring panels or template variables, wiring datasources, or setting up alerting rules and contact points. Also trigger on GrafanaDashboard/GrafanaDatasource CRDs (Grafana Operator), file-based provisioning for Docker Compose, Discord/email alert routing, and drilldown dashboard design. NOT for PromQL query syntax (see promql), LogQL syntax (see logql), or deploying the monitoring stack (see homelab-monitoring).

You MUST consult this skill when writing or debugging LogQL queries for Grafana Loki. Also trigger when building Grafana dashboard panels backed by Loki, creating log-based alerting rules, diagnosing empty results or parser errors, extracting metrics from logs with rate/count_over_time/unwrap, or correlating logs across multiple services. NOT for Loki deployment or configuration (see homelab-monitoring), Prometheus metrics (see promql), or PromQL dashboards.

You MUST consult this skill when writing or debugging PromQL queries for Prometheus — dashboards, alerting rules, recording rules, or ad-hoc metric exploration. Also trigger on rate vs irate decisions, histogram quantiles, predict_linear for capacity planning, absent() for uptime alerts, or vector matching errors. NOT for Prometheus server deployment (see homelab-monitoring), Loki log queries (see logql), or Grafana datasource configuration.

You MUST apply this skill proactively when writing any code that will run in production — services, workers, queue consumers, schedulers, API servers (FastAPI, Flask, Django, gRPC), or any server-side code. Also trigger when adding error handling, implementing observability, adding try/catch blocks, mentioning correlation IDs or request tracing, or debugging a production issue where more context would help. Apply even when the user doesn't explicitly ask about logging — logging is massively undervalued. NOT for log aggregation infrastructure (see grafana-loki for cloud/k8s, homelab-monitoring for homelab), query syntax (see logql), or reviewing existing logging code in PRs (see code-reviewer).

Git pull request creation — use this skill whenever creating a pull request from a feature branch, writing PR titles or descriptions, or when any agent needs to open a PR as part of a workflow. Also trigger when the user says "open a PR", "create a pull request", or asks to submit their work for review. NOT for reviewing PRs (see code-reviewer), writing commits (see git-commit), or merging/rebasing.

Use when you want to review a peer's GitHub PR — runs the code-reviewer pipeline on the PR, transforms findings into courteous Google eng-practices-styled draft comments, tiers them by severity, and presents formatted text for you to selectively post. NOT for reviewing your own code (see code-reviewer).

Decompose a behavioral PRD into deliverable stories with technically specific acceptance criteria, saved as Markdown files. Use when the user wants to generate stories from a PRD, break capability groups into work items, create acceptance criteria, or go from PRD to implementable stories. Also trigger when the user mentions "stories from PRD", "decompose the PRD", "break down capabilities", or wants to turn behavioral requirements into testable deliverables.

Load when writing to the wiki, proposing wiki writes, or performing advanced graph operations (backlink queries, tag searches, decision-chain traversal). Explicit triggers: "log this", "remember", "add to the wiki", "wrap up". Also load on beads task closure when the promotion review requires wiki writes. NOT for reading alone — the AGENTS.md reading protocol handles session-start context loading without requiring this skill.

You MUST consult this skill when reasoning about combat arena design, encounter composition, spatial choice in action/shooter levels, player guidance through combat spaces, push-forward layout, or level flow in action games. Also trigger when a level feels like a corridor with decoration, when players camp or disengage, when combat encounters feel static, or when spatial choices feel cosmetic. NOT for puzzle, exploration, or platformer level design. NOT for game mechanics theory or depth analysis (see game-design). NOT for engine-specific implementation (see godot, love2d).

You MUST consult this skill when reasoning about game audio design — how music serves gameplay, designing sound that reinforces game feel, adaptive/reactive audio systems, tonal integration between music and sound effects, or creative process for game composers. Also trigger when audio feels generic, when a brief demands something unprecedented, or when discussing constraints as creative tools. NOT for Wwise/FMOD node graph configuration or middleware setup. NOT for general music composition theory outside a game context.

You MUST consult this skill when writing, reviewing, or generating Python code. Also trigger on Python-specific design choices (Protocol vs ABC, TypedDict vs dataclass, Pydantic boundaries), code style anti-patterns (broad exceptions, sentinel defaults, redundant docstrings, unnecessary future imports), or advanced patterns (functools, generator pipelines, typing). NOT for debugging Python errors, framework-specific setup (Django, Flask, FastAPI config), package management, or writing tests (see test-design).

Use this skill for any Nix, NixOS, Flakes, Home Manager, or nix-darwin task. Also trigger when the user mentions flake.nix, devShells, mkShell, nixos-rebuild, darwin-rebuild, home-manager switch, nix develop, overlays, derivations, or anything involving declarative system/package configuration on Linux or macOS — even if they don't explicitly say 'Nix'. NOT for writing packages from scratch with stdenv.mkDerivation or language-specific builders (see nix-packaging). NOT for the dendritic flake-parts pattern — if the query mentions import-tree, `flake.modules.<class>.<aspect>`, aspect-oriented config, generic module class, or feature-based module sharing across NixOS/darwin, see nix-dendritic instead.

Use when writing Nix packages from scratch, authoring derivations with stdenv.mkDerivation or language-specific builders (buildPythonPackage, buildRustPackage, buildGoModule), debugging build phase failures, patching package sources, or managing build/runtime dependencies. Also trigger on closure size analysis, wrapProgram, substituteInPlace, or fetchpatch. NOT for system configuration, dev shells, or customizing existing packages with override/overrideAttrs (see nix).

You MUST use this skill before implementing any feature, fixing any bug, or refactoring existing code. The TDD workflow applies whenever the task involves substantial new functionality, restructuring how code is organized, or reproducing a bug. Also trigger on mentions of TDD, red-green-refactor, or test-first development. NOT for trivial one-liner fixes, config changes, renaming, documentation, or test quality in isolation (see test-design).

Use when writing Dockerfiles, Docker Compose files, building or debugging container images, choosing base images, pushing to registries, or running containers locally. Also trigger when asked about multi-stage builds, .dockerignore, container networking, volumes, or self-hosting an application with Docker. NOT for Kubernetes workloads (see k8s-workloads), Helm charts (see helm), Docker in CI pipelines (see github-actions), or GPU operator configuration (see gpu-operator).

Use when working on any Godot 4.x development — writing or reviewing .gd files, designing scene trees, implementing game systems in GDScript, structuring Godot projects, or asking about nodes, signals, AutoLoads, Resources, or the Godot editor. Also trigger when implementing game patterns (Observer, State, Command, etc.) in a Godot project — this skill takes precedence over game-patterns for Godot-specific implementation. NOT for engine-agnostic pattern theory (see game-patterns). NOT for Love2D (see love2d). NOT for shaders or visual effects (see godot-shader).

You MUST consult this skill when writing or reviewing `.gdshader` files, GDSL shader code, visual effects, lighting models, or post-processing in Godot. Also trigger on Shadertoy porting, vertex displacement, procedural shapes in shaders, screen-space effects, normal maps, transparency sorting, ray marching, or particle shader logic. NOT for GDScript game logic, scene architecture, or node patterns (see godot). NOT for C# or visual shaders.

Use when working with Fennel and Love2D together — writing `.fnl` files in a Love2D project, setting up REPL-driven development, hot-reloading modules during live gameplay, using the min-love2d-fennel template, writing Fennel macros for state persistence across reloads, or structuring a Love2D project with the mode-based architecture. NOT for Love2D engine API patterns. NOT for engine-agnostic pattern theory (see game-patterns).

Use when working on any Love2D project — writing Lua for Love2D, implementing Love2D callbacks (love.load, love.update, love.draw), handling input, writing shaders, structuring a game loop, or asking about Love2D APIs. Also trigger when implementing game patterns (Observer, State, Command, etc.) in a Love2D project — this skill takes precedence over game-patterns for Love2D-specific implementation. NOT for Fennel interactive development workflow (see love2d-fennel). NOT for engine-agnostic pattern theory (see game-patterns).

Use when installing Helm charts, managing Kubernetes releases, overriding chart values, discovering charts on Artifact Hub, upgrading or rolling back deployments, or deploying third-party software (databases, message queues, stacks) on Kubernetes. Also trigger when extending a Bitnami chart image, writing a values override file, or pinning chart versions for reproducibility. NOT for cluster setup (see k3s), writing Kubernetes manifests directly (see k8s-workloads, k8s-storage), networking and ingress (see k8s-networking), or day-2 cluster operations (see k8s-operations).

Use when installing or managing a self-hosted Kubernetes cluster with k3s, setting up kubectl or kubeconfig, adding server or agent nodes, or choosing between single-node and multi-node topologies. Also trigger on embedded etcd vs SQLite datastore decisions, k3s systemd service configuration, or accessing a cluster remotely. NOT for workload resources like Deployments or Services (see k8s-workloads), networking and ingress (see k8s-networking), storage (see k8s-storage), Helm (see helm), or containerizing applications (see docker).

Use when configuring DNS records for a self-hosted domain, installing or configuring the NGINX Ingress controller, setting up TLS/SSL certificates with cert-manager and Let's Encrypt, writing NetworkPolicy resources, or creating a WireGuard VPN for cluster access. Also trigger on Flannel CNI configuration, exposing services externally, or debugging ingress routing. NOT for cluster setup (see k3s), workload resources (see k8s-workloads), storage/ConfigMaps/Secrets (see k8s-storage), Helm charts (see helm), or rollout strategies (see k8s-operations).