agent-engineering-handbook

Core coding standards and best practices for code review and generation. Provides KISS and measurable clean-code outcomes, guiding principles (DRY, YAGNI, SOLID), priority frameworks, tooling baselines, dependency management, and response formats. Use when reviewing code, generating code, asking about coding standards, or when the user needs general engineering guidance that applies across all languages.

Principal-level IAM and security architecture advisor for identity protocols, IGA, PKI, PAM, secrets delivery, and non-human identity. Use for architecture decisions, protocol deep dives, design reviews, threat models, or mentoring involving OAuth, OIDC, SAML, SCIM, mTLS, certificates, workload identity, or privileged access.

Structured development workflow with Plan/Implement/Review phases, QA validation, context management, and audit requirements. Enforces explicit authorization for remote mutations, risk-based checkpoints, and proportional audit reports. Use when working on complex tasks, multi-file changes, or when the user mentions planning, workflow, implementing features, or needs structured development guidance.

Databricks playbook. Workflows for workspace bootstrap, Unity Catalog migration, Lakeflow Spark Declarative Pipelines (formerly Delta Live Tables / DLT), Declarative Automation Bundles (formerly Databricks Asset Bundles), cluster policies/access modes, serverless SQL and jobs, Photon and cost tuning, governance audit, Mosaic AI/MLflow, and recovery via Delta time travel. Use when designing, operating, or auditing Databricks.

Documentation best practices including Markdown formatting, Mermaid diagrams, technical writing, ADRs, and open source standards. Use when writing documentation, README files, markdown content, creating static diagrams in Markdown, or when asking about documentation structure, technical writing, or open source project setup. For interactive React Flow canvases in a SPA, use the reactflow-architecture-diagrams skill instead.

Delivers narrative interactive architecture diagrams using React, TypeScript, Tailwind, and @xyflow/react (React Flow): node and edge patterns, optional Cloudflare orange shell grouping, routing, and verification. Use when adding or editing React Flow diagram components (Diagram.tsx suffix convention), files under components/diagrams, xyflow edges, animated canvas traffic, or when the user asks for a React Flow architecture diagram alongside documentation.

Bash scripting best practices for production-grade scripts, CLI tools, and Makefiles. Covers strict mode, error handling, portability, performance patterns, and argument parsing. Use when working with .sh files, Makefiles, shell scripts, or when asking about Bash, shell scripting, CLI design, or command-line tools.

Cloud platform best practices for AWS, Azure, GCP, and Cloudflare. Covers Zero Trust architecture, IAM patterns, EKS/AKS/GKE configurations, serverless patterns, and multi-cloud strategies. Use when working with cloud infrastructure, AWS services, Azure resources, GCP projects, Cloudflare Workers, or when asking about cloud architecture and deployment.

Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use for any Cloudflare development task. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

Workflow for building production-grade Cloudflare Workers in TypeScript - bootstrap, bindings and storage choice, routing (Hono + RPC via WorkerEntrypoint), testing with @cloudflare/vitest-pool-workers, gradual deployments, and common pitfalls. Use when adding a new Worker, adding endpoints to an existing Worker, choosing between KV / R2 / D1 / Durable Objects / Hyperdrive, setting up testing, configuring deployment, or reviewing a Worker PR.

Docker and container orchestration best practices for production-ready containers. Covers multi-stage builds, security scanning, distroless images, Docker Compose patterns, health checks, and CI/CD integration. Use when working with Dockerfile, docker-compose.yml, .dockerignore files, or when asking about Docker, containers, image optimization, or container security.

Go and Rust systems programming best practices for performance-critical, concurrent, and safe applications. Covers error handling, ownership/borrowing (Rust), context and goroutines (Go), testing patterns, and production deployment. Use when working with .go, .rs files, Cargo.toml, go.mod, or when asking about Go or Rust development.

Infrastructure as Code best practices for Terraform, Docker, Ansible, and CloudFormation. Covers secure-by-default configurations, multi-stage builds, state management, and modular patterns. Use when working with .tf, Dockerfile, docker-compose.yml, .yaml/.yml Ansible files, CloudFormation templates, or when asking about IaC, containers, or infrastructure automation.

Python development standards for code review and generation. Covers Python 3.14+ patterns including template strings (t-strings), deferred annotations, free-threading, type hints, async/await, testing with pytest, package management with uv, AWS Lambda/boto3 patterns, and Pydantic validation. Use when working with .py files, pyproject.toml, requirements.txt, Lambda functions, or when asking about Python best practices, code review, or generation.

Advanced Bash automation patterns for production-grade scripts and automation workflows. Covers retry logic, lock files, signal handling, advanced error handling, performance optimization, testing with BATS, and cross-platform compatibility. Use when building automation scripts, deployment tools, CI/CD helpers, or when asking about advanced Bash patterns, script reliability, or automation best practices.

Biweekly maintenance workflow for improving Agent Skills and matching rules in this handbook. Use when the user asks to review, refresh, audit, improve, harden, or update skills/rules, or when doing a scheduled every-2-weeks quality pass over skills. Finds drift between rules and skills, stale examples, unsafe snippets, broken/clickability issues, duplicated guidance, and missing non-negotiables; applies high-confidence fixes and reports larger follow-ups.

TypeScript and JavaScript development standards for modern web and Node.js development. Covers strict TypeScript configuration, type safety patterns, ESM modules, async/await, testing with Jest/Vitest, and security best practices. Use when working with .ts, .tsx, .js, .mjs files, package.json, tsconfig.json, or when asking about TypeScript/JavaScript best practices.

Build AI agents on Cloudflare Workers using the Agents SDK. Load when creating stateful agents, durable workflows, real-time WebSocket apps, scheduled tasks, MCP servers, chat applications, voice agents, or browser automation. Covers Agent class, state management, callable RPC, Workflows, durable execution, queues, retries, observability, and React hooks. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

Create and review Cloudflare Durable Objects. Use when building stateful coordination (chat rooms, multiplayer games, booking systems), implementing RPC methods, SQLite storage, alarms, WebSockets, or reviewing DO code for best practices. Covers Workers integration, wrangler config, and testing with Vitest. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

Build sandboxed applications for secure code execution. Load when building AI code execution, code interpreters, CI/CD systems, interactive dev environments, or executing untrusted code. Covers Sandbox SDK lifecycle, commands, files, code interpreter, and preview URLs. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

Analyzes web performance using Chrome DevTools MCP. Measures Core Web Vitals (LCP, INP, CLS) and supplementary metrics (FCP, TBT, Speed Index), identifies render-blocking resources, network dependency chains, layout shifts, caching issues, and accessibility gaps. Use when asked to audit, profile, debug, or optimize page load performance, Lighthouse scores, or site speed. Biases towards retrieval from current documentation over pre-trained knowledge.

Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

Kubernetes and Helm best practices for container orchestration. Covers deployments, services, RBAC, resource management, Helm charts, Podtrace runtime debugging, and production patterns. Use when working with Kubernetes manifests, Helm charts, kubectl commands, Podtrace, or when asking about container orchestration, pod configuration, or cluster management.

Workflow for crafting Cloudflare WAF rules across all three authoring interfaces - Terraform (cloudflare_ruleset), the Cloudflare Dashboard, and the Rulesets API. Covers both Custom Rules (actions like block, managed_challenge, log, skip-as-allow) and Managed-Rule Exceptions (action skip). Forces a docs-first read, peer-rule survey, explicit rule-type branch, and guards-by-type checklist before any expression is drafted. Use when adding or editing any Cloudflare WAF rule, when the user asks for a WAF block / challenge / allow / skip / OWASP child-rule bypass, or when reviewing such a change.

Add client-side PDF export to a web app using jspdf + html2canvas-pro. Use when the user asks to download, save, or export the current page, a report, a slide deck, a chart, or any DOM element as a PDF. Covers single-element snapshots and multi-page documents with TOC bookmarks. No server, no Puppeteer at runtime - all browser-side.

AWS IAM deep-dive skill - principal types, policy evaluation, STS assume role, SCP guardrails, KMS key policies/grants, and AccessDenied debugging. Use when designing AWS authz/authn, cross-account access, or troubleshooting IAM/KMS/SCP AccessDenied errors.

End-to-end codebase security audit using the practical eight-layer model - secrets scanning (regex + entropy), SAST (with taint analysis), SCA (deps + license), data-flow / taint, semantic / code-property-graph, IaC, custom rules, and DAST validation. Produces a severity-ranked remediation plan, .env templates, and a ready-to-use CI/CD continuous-scanning workflow. Covers OWASP Top 10 (2021) A01-A10 with curated ripgrep playbooks per category. Use when the user asks to "security audit", "harden this repo", "check for secrets", "find committed secrets", "OWASP audit", "SAST scan", "SCA / dependency audit", "IaC audit", "DAST validation", or "check for vulnerabilities".

Framework-agnostic frontend architecture playbook. Workflows for picking rendering (SSG / SSR / SPA / ISR), setting bundle budgets, choosing state management (local / server / global), Core Web Vitals tracking + INP debugging, accessibility floor enforcement, testing pyramid, and supply-chain security. Use when designing a new frontend project, auditing an existing one, picking between React / Vue / Svelte / Astro, debugging perf, or wiring CI gates for a SPA / SSG / SSR app.

Networking and transport-layer architecture for production services. TCP keepalive, head-of-line blocking, TTFB budget, HTTP/1.1 vs HTTP/2 vs HTTP/3, when to choose gRPC/Protobuf over REST/JSON, connection pooling, long-lived connections (websockets / SSE / gRPC streaming), and CDN-to-origin patterns. Use when designing service-to-service APIs, debugging tail latency, choosing a wire protocol, configuring load balancer idle timeouts, or evaluating HTTP/3 / QUIC for mobile / cross-region workloads.

GitHub Actions best practices for CI/CD workflows. Covers security (permissions, secrets), performance (caching, matrix builds), reusable workflows, and common patterns for testing, building, and deploying. Use when working with .github/workflows/*.yml files, GitHub Actions, or when asking about CI/CD pipelines and automation.

Build single-file zero-dependency interactive HTML dashboards for analytical artifacts that must be emailable, offline-viewable, or airgap-safe. Inline vanilla-SVG charts, no CDN, no remote scripts, no web fonts, no images. Useful for client deliverables, security audit reports, executive dashboards, post-mortems, technology consolidation analyses, and anything that needs to render identically in a browser, an email client, an airgapped laptop, or a regulator review. Use when the user asks for a "dashboard", "interactive HTML report", "shareable analysis", "offline dashboard", "airgap-safe report", or wants to turn an analytical workbook / dataset into a presentable HTML view.

Structured multi-advisor review of an architecture, vendor, strategy, or design decision. Each advisor (data, architecture, business value, operations, risk, executive sponsor, etc.) gives a position vote, a one-sentence pro and con, and the sharp question they would ask. Every assertion carries a "what worked" and "horror story" industry-precedent pair. A weighted scoring model lets the user influence outcomes via emphasis profiles (balanced, value-first, risk-averse, platform-forward, ops-heavy, data-forward, executive-sponsor, custom). Use when the user wants stakeholder perspectives, panel review, pro/con across multiple lenses, weighted recommendation, or wants to re-weight an existing analysis with a different strategic emphasis.

Patterns for composing multiple Cursor / Agent Skills into orchestrated workflows. Covers slash commands that chain skills, project-vs-personal scope resolution, sibling-skill auto-detection with graceful degradation, sequential vs parallel chaining, HITL gates between phases, parameter passing, and error handling. Use when designing a multi-step workflow that spans skills, building a slash command that delegates to several skills, or deciding when to add a new skill vs extend an existing one.

Refresh a project knowledge base from web research with strict tool-call budgets, cross-referenced sources, atomic file swaps, and rollback-on-failure. Use when refreshing a KB-backed analysis (vendor facts, compliance posture, market data, security advisories), running long web-research workflows that must be predictable in cost and time, or designing any "regenerate-from-the-web" command. Generalizes the /facts-update pattern of capping web-tool calls per unit of work, keeping research separate from analyst judgment, and writing back atomically with a timestamped archive.

Workload identity playbook (SPIFFE/SPIRE, cloud IAM, OIDC federation). Workflows for picking SPIFFE vs cloud IAM, deploying SPIRE on EKS, federating trust domains, bridging to AWS/GCP/Azure via OIDC, and migrating off long-lived workload secrets. Use when designing or hardening service-to-service auth for k8s, multi-cloud, or AI agents.

Okta Workforce Identity playbook. Workflows for new SSO app integration, sign-on policy hardening, SCIM provisioning rollout, IdP migration, login-failure debugging, signing key rotation, and admin role audit. Use when designing, operating, or auditing Okta (orgs, apps, users/groups, policies, lifecycle, Workflows, ASA, Admin API, terraform-provider-okta).

Snowflake playbook. Workflows for RBAC rollout, warehouse sizing and cost control, secure data sharing, Streams/Tasks/Snowpipe pipelines, permissions audit, and Time Travel / Fail-safe recovery. Use when designing, operating, or auditing Snowflake.

Distinguished-engineer playbook for Zero Trust design reviews across identity, network, data, workload, and AI/agent systems. Principles-first, opinionated, threat-model-driven. Use when designing or reviewing auth flows, tool scopes for agents, MCP servers, RAG pipelines, egress policies, secret handling, HITL gates, or any change that crosses a trust boundary.

Security best practices (OWASP Top 10) and testing strategies for software development. Covers secure coding, vulnerability prevention, testing pyramid, API design, and observability patterns. Use when reviewing code for security, writing tests, designing APIs, or when asking about security vulnerabilities, testing strategies, logging, or monitoring.

Data engineering workflows for designing and reviewing batch/streaming pipelines across Databricks, Snowflake, Confluent Kafka, and Teradata (contracts, backfills, quality, governance, cost, observability). Use when the user mentions data engineering, ETL/ELT, lakehouse/warehouse, Kafka, Databricks, Snowflake, or Teradata.