agent-skills

Modernize Go code with the rebuilt go fix command in Go 1.26+. Applies safe, version-aware rewrites to newer language and stdlib idioms (interface{} to any, 3-clause loops to range-over-int, min/max, strings.Cut, new(expr), and 20+ more), iterating to a fixed point and verifying the build afterward. Use whenever Go code should be modernized, cleaned up, or made idiomatic — after a go.mod version bump, when old-style or AI-generated patterns accumulate, when migrating callers off deprecated or renamed APIs (go:fix inline directives), when the user mentions go fix or gofix, or to enforce modern idioms as a CI gate. Not for gofmt formatting, dependency upgrades, or go vet bug-finding.

Prepares Go applications to work effectively with AI coding agents. Use when setting up a new Go project or retrofitting an existing one to ensure: structured JSON logging (slog/Zap/ZeroLog/Logrus), machine-readable command output, thorough golangci-lint configuration, non-interactive CLI design with --yes flags, structured error handling with meaningful exit codes, proper context.Context propagation, graceful shutdown, health check endpoints, and a standardized Makefile. Triggers when a user asks to make their Go app "agent-ready," "AI-friendly," wants to improve agent tooling/observability in a Go project, or needs to audit an existing Go project against agent-readiness best practices.

Validate GitHub Actions workflow files for syntax errors, invalid references, and common mistakes. Auto-detects actionlint binary or guides installation. Checks project config or falls back to sensible defaults. Use when creating or modifying GitHub Actions workflows, validating CI/CD pipelines, or catching workflow errors before pushing.

Validate Dockerfiles against best practices for syntax errors, image tagging, package pinning, and shell script issues in RUN commands. Auto-detects hadolint binary or Docker image fallback. Checks project config or falls back to sensible defaults. Use when creating or modifying Dockerfiles, reviewing container images, or catching Dockerfile anti-patterns before building.

Validate shell scripts for syntax errors, common bugs, quoting issues, and portability problems. Auto-detects shellcheck binary or guides installation. Checks project config or falls back to sensible defaults. Use when creating or modifying shell scripts, validating bash/sh files, or catching shell scripting mistakes before committing.

Strategic roadmap management for GitHub repositories. Syncs ROADMAP.md with GitHub Issues and labels, bootstraps roadmap files from scratch, runs brainstorming sessions with boundary checking, and provides quick status summaries. Use when managing project planning, syncing roadmap state, or exploring feature ideas.

Generate a PR_MESSAGE.md file from session context using GitHub CLI. Detects related issues via branch-keyword search, writes a structured PR description with commit subject, summary, test plan, and changelog. Validates with commitlint and markdownlint. Use when preparing a pull request on GitHub.

Audit Go nolint directives for staleness and lazy justifications. Mechanically verifies each suppression with golangci-lint, then runs adversarial Red/Blue/White debates on the top candidates for removal. Use when inheriting a Go codebase, during periodic cleanup, or when nolint count is growing unchecked.

Scout Rule — identify the top 3 highest-impact improvement opportunities in files you're already touching. Analyzes entire file content, not just changed lines. Focuses on pre-existing code quality, not PR bugs. Use when preparing a PR, during code review, or after completing a feature.

Validate markdown files against formatting standards. Auto-detects and installs markdownlint-cli if missing. Checks project config or falls back to sensible defaults. Supports auto-fix mode. Use when creating or modifying markdown files, validating documentation, or enforcing markdown conventions.

Diagnose Tailscale subnet router connectivity failures. Traces the full route lifecycle: advertisement, approval, client acceptance, policy routing (table 52), and IP forwarding. Use when clients can reach Tailscale peers by IP but not devices on advertised subnets, or when subnet routes appear approved but traffic doesn't flow. Also use when Docker containers fail to advertise routes, when `ip route` shows no subnet route (it's in table 52), or when traffic flows one way but responses don't return.

Validate commit messages against the Conventional Commits specification. Auto-detects and installs commitlint CLI if missing. Checks project config or falls back to sensible defaults. Use when validating commit messages, preparing PRs, or enforcing commit conventions.

Generic cost estimation for IaC projects. Detects the IaC stack (Pulumi, Terraform) and compatible cost tool (finfocus, infracost), runs cost analysis, flags expensive resources, cost increases, and total cost against configurable thresholds. Produces a terminal summary and COST_CHECK.md report. Use when checking infrastructure costs, reviewing cost impact of changes, or enforcing budget thresholds in CI.

Drift analysis for Pulumi infrastructure costs. Runs finfocus to compare actual vs projected spend, flags drifting resources against configurable thresholds, generates likely-cause explanations with investigation prompts, and tracks drift trends over time. Produces a terminal summary and COST_DRIFT.md report. Use when investigating cost overruns, validating projections against reality, or monitoring spend drift in CI.

Diagnose Tailscale connectivity and DNS failures inside Docker containers. Detects userspace vs kernel mode, DNS resolver conflicts, TUN interface issues, and multi-tailnet mismatches. Use when Tailscale peers connect by IP but MagicDNS names fail, or when containers fall back to userspace networking unexpectedly. Also use when a customer deploys Tailscale in Docker or Podman and reports DNS not working, or when migrating from docker run to docker compose breaks TUN functionality.