[infra] Add a coding-agent development skill

[wenjin272]

Linked issue: #917

Purpose of change

Add a repository-managed, self-contained flink-agents-dev skill for coding agents that build Flink Agents applications.

The skill bundles the YAML schema and focused references for YAML, Python, Java, local development, and verification. It guides coding agents through version, API, language, Resource, and Python environment decisions before scaffolding a project, while leaving user-owned Actions, Tools, prompts, and runtime Skills as explicit implementation placeholders.

It also documents dependency-managed Maven and Python project setup, cross-language Resource usage, and local verification through RemoteExecutionEnvironment and a MiniCluster. Platform-specific interaction guidance is isolated in adapters for Codex, Claude Code, Gemini CLI, Qoder, and generic coding agents.

Tests

• python3 /Users/jhin/.codex/skills/.system/skill-creator/scripts/quick_validate.py dev/agent-skills/flink-agents-dev
• cmp docs/yaml-schema.json dev/agent-skills/flink-agents-dev/assets/yaml-schema.json
• git diff --check upstream/main...HEAD
• ./tools/check-license.sh

No Java or Python runtime tests were run because this change adds a coding-agent instruction bundle and repository metadata without changing executable project code.

API

This change does not touch public Flink Agents APIs.

Documentation

• doc-needed
• doc-not-needed
• doc-included

[weiqingy]

Thanks for putting this together @wenjin272. Only one question inline.

[weiqingy]

The version table just above (lines 44–47) mirrors tools/install.sh, which makes it lovely and easy for a coding agent to confirm. This 3.12 → Flink Agents 0.3+ / Flink 2.1+ pairing is the one concrete version constraint here I couldn't trace back to an in-tree source — pyproject.toml pins requires-python = ">=3.10,<3.13" but doesn't seem to gate 3.12 on those component versions. Is it coming from the per-release wheel matrix? If so, might it be worth either pointing a coding agent at where it can confirm this, or leaning on the same escape hatch the snapshot note at 73–76 already uses ("use a target-version installer, release metadata, or compatibility matrix ... because it overrides this bundled snapshot")? You'd know the release matrix far better than I can reconstruct from the tree — mostly curious whether there's a source a coding agent could check.

[wenjin272]

Thanks, this is a good point. I checked this again, and the constraint is encoded in the installer rather than in a standalone compatibility matrix.

tools/install.sh::python_minor_ceiling() derives the effective Python ceiling from both selected versions: Flink Agents 0.1.x/0.2.x require Python <3.12, while Flink <2.1 also requires Python <3.12. Therefore, Python 3.12 is accepted only with Flink Agents 0.3+ and Flink 2.1+. The concrete accepted and rejected combinations are covered by tools/test/unit/validate_python_bin.bats, and the same constraint is documented in docs/content/docs/get-started/installation.md.

python/pyproject.toml only describes the current Flink Agents wheel's own Python range, so it does not capture the cross-version constraint with Flink.

[weiqingy]

Thanks for the details. I'd missed python_minor_ceiling() and the installation.md note. Nothing further from me. LGTM.

[joeyutong]

I evaluated this Skill with clean-workspace scenarios covering both its workflow and generated artifacts. The case numbers in the inline comments are internal identifiers from that evaluation.

[joeyutong]

Case 013 — selected-version contract. The input selected Flink Agents 0.3.0, Flink 2.0.2, YAML, and Python, with the release-0.3.0 source and schema available. The expected behavior was to bind the generated YAML to that selected release. Instead, the result used trigger_conditions from this bundled/current example, while release-0.3.0 requires listen_to.

Since the latest source uses trigger_conditions, I do not think this review should prescribe one field as the universal fix. Could you make the support policy explicit and consistent—either make the patterns version-aware when older releases are selectable, or scope the Skill to the current snapshot and stop presenting incompatible historical releases as supported targets? A version offered to the user should not produce artifacts using another version's YAML contract.

[joeyutong]

Case 016 — unresolved business contracts. The input specified only the high-level flow: retrieve context, invoke a chat model, allow an order-query Tool/runtime Skill, and emit an answer. It did not define the input-to-query mapping, context formatting, chat-message construction, or output contract. The expected result was importable Action skeletons that fail explicitly. Instead, the generated Actions chose those transformations and added tests that asserted the invented behavior.

Could we strengthen this boundary with an explicit checklist or equivalent constraint logic? For each custom Action, Tool, or domain client, first classify its business contract as supplied or unresolved using only user requirements, existing code, and tests. If unresolved, allow only a signature, focused TODO, and explicit failure; do not emit events, transform payloads, compose messages, return business data, or add tests that assert those behaviors. The exact mechanism can be left to the contributor, but it should be more operational than the current general “do not invent business behavior” rule.

[joeyutong]

Two additional observations from clean-context evaluation.

[joeyutong]

Case 005 — negative trigger scope. The input requested an ordinary PyFlink DataStream word-count and explicitly excluded Agent, Action, Resource, and Flink Agents dependencies. The expected behavior was for this Skill not to enter the request. In one clean-context run, however, the agent loaded the full Skill before eventually producing the correct plain PyFlink job.

This may be a host/model routing outcome rather than a deterministic Skill bug, but the frontmatter is the main discovery signal. Would it be worth making the negative boundary explicit: use this Skill only when the target is, or is being converted into, a Flink Agents application, and not for ordinary Flink/PyFlink requests that mention Flink Agents only to exclude them?

[wenjin272]

Agreed. I've also observed this in my local development work.

[joeyutong]

Case 030 — stop when a Provider contract cannot be verified. The input asked to add two vendor Provider classes to an existing Java/YAML application, but no JAR, source, constructor or descriptor documentation, dependency coordinates, or accessible vendor documentation were available. A runnable integration therefore could not be generated safely. In one clean-context run, the agent correctly refused to guess, but only after loading all five bundled references and continuing through later Build Workflow steps.

Could we make this blocked path explicit? Once the available sources cannot establish the required external Provider contract, preserve the working configuration and stop the dependent integration work. The response should report what was checked, the exact missing contract, and the minimum vendor input needed to continue. This would be a narrow early-exit rule for unverifiable external integrations, not a general stop for unresolved business TODOs.

[GreatEugenius]

Make Codex interaction capability-driven and keep the policy authoritative in one place.

I tested this flow on a Codex surface where /plan was not an available user command. The adapter stopped the task and requested a mode switch even though the generic numbered fallback could have continued.

Could we make the current tool contract the only capability signal?

• If request_user_input is currently exposed and callable, use it.
• Otherwise, immediately use the generic numbered fallback.
• Do not require /plan, Shift+Tab, or a Plan-to-Default handoff.

The mode and fallback sequence is currently defined in SKILL.md, application-patterns.md, and platforms/codex.md. Could we keep the portable rule authoritative in one place and have the other files reference it? Otherwise, changing only one copy may leave the Skill with inconsistent instructions.

[GreatEugenius]

Resolve already-confirmed decisions before entering the gated interview.

The Skill says to skip gates that the user or existing project has already answered, but it does not make that resolution pass an explicit step before selecting a host adapter. In practice, the workflow can start a handoff or repeat a question before reconciling the complete context.

Could we require the workflow to:

1. inspect the existing project and all explicit user requirements;
2. resolve each decision, with the latest explicit user choice taking precedence;
3. build a list containing only genuinely unresolved gates; and
4. invoke a host interaction adapter only when that list is non-empty?

This would prevent repeated questions and avoid unnecessary host interaction when every required decision is already known.