Hello all , *Proposal*: I'd like to propose adding operational agent skills to the Apache Flink ecosystem, which would include structured, action-oriented guides that help AI coding assistants (and humans) troubleshoot, debug, tune, and deploy Flink applications.
*What exists today*: So far there have been several amazing tickets for AI-assisted contributions: - FLINK-39477 Clarify how Flink accepts and supports AI-Assisted Contributions and AI Tooling Support - FLINK-39714 Backport AGENTS.md to active branches 1.20, 2.0, and 2.2 - FLINK-39529 Extend planner's Agents.md with more detailed SQL to operator lifecycle - FLINK-39881 [FKO] Adopt AI-assisted contribution guidelines for the Kubernetes Operator - FLINK-39539 Extend planner's Agents.md with more detailed information for our internal table module CDC processing For operations on AWS, the aws/agent-toolkit-for-aws repo includes detailed Flink skills covering checkpoint tuning, first-fault isolation, state management, but these are specific to AWS Managed Service for Apache Flink (KPU sizing, CloudWatch metrics, aws CLI commands). *What's missing*: provider-agnostic operational skills for the many teams running Flink on self-managed Kubernetes, bare-metal, or non-AWS clouds. Flink's official docs (docs/ops/) cover the topics well as reference material, but they aren't structured as concise symptom→diagnosis→resolution guides optimized for AI agent consumption. *More Detailed Proposal* A set of markdown-based operational skills, each one a self-contained guide following a consistent structure: - Symptoms: what the operator sees (metrics, logs, behavior) - Diagnosis steps: how to narrow down the root cause - Resolution patterns: concrete fixes with commands/config - Common pitfalls: tribal knowledge that isn't obvious from docs Example topics: 1. Restart loop diagnosis: "recent logs show side effects, not root cause; find attempt #0's first exception" 2. Classloader conflicts: parent-first vs child-first, shading, version mismatches (e.g., NoSuchFieldError from AWS SDK conflicts) 3. Checkpoint failure triage: alignment timeout vs state size vs slow sink vs backpressure 4. State migration / skip-state: when it's safe, how to do it, what breaks 5. Backpressure analysis: interpreting metrics, identifying bottlenecks, tuning 6. Memory tuning: TaskManager/JobManager OOM diagnosis, RocksDB memory accounting Where the skills could live: - A skills/ or ops-skills/ directory within apache/flink - A dedicated repo (like apache/flink-agent-skills) - Within the existing docs/ alongside module-level AGENTS.md files These would be provider-agnostic (no AWS/GCP/Azure specifics) and complement the existing official documentation rather than replace it. I'm happy to contribute initial skills based on real operational patterns. The classloader conflict and restart-loop examples above come from production issues I've debugged in the past week. Looking forward to the community's thoughts. Best regards, James Pizagno (github repo <https://github.com/jpizagno>)
