joeyutong commented on code in PR #918: URL: https://github.com/apache/flink-agents/pull/918#discussion_r3649565847
########## dev/agent-skills/flink-agents-dev/SKILL.md: ########## @@ -0,0 +1,321 @@ +--- +name: flink-agents-dev +description: Use when building, scaffolding, modifying, debugging, converting, or verifying Apache Flink Agents applications, including Flink Agents YAML, Workflow Agent, ReAct Agent, Actions, Resources, MCP servers, vector stores, runtime skills, Python, or Java. +--- + +# Developing Flink Agents Applications + +## Core Model + +Model every application as four connected parts: + +1. **Resources**: named models, prompts, tools, skills, vector stores, MCP servers, + and connections. +2. **Actions**: event handlers that use Resources and emit events. +3. **Orchestration**: trigger conditions and emitted-event graph. +4. **Implementation**: Python/Java functions, types, and runner. + +Skills, vector stores, MCP, RAG, and memory are combinations of these parts. + +The Agent API language and custom Action/Tool language do not constrain every +Resource implementation. Chat-model connections/setups, embedding-model +connections/setups, and vector stores support Python/Java bridging in both +directions in the bundled snapshot. For those Resource types, offer every +target-version implementation supported natively or through the bridge, regardless +of whether the application uses YAML, direct Python, or direct Java. Treat the +selected implementation's language as part of that Resource choice; do not add a +separate application-wide cross-language confirmation. Do not generalize this rule +to Resource types that lack a verified bridge. + +## Source Authority + +This skill must work from its installed directory; never assume the user cloned the +Flink Agents repository. Resolve bundled paths relative to this `SKILL.md`. + +Inspect the target version and conventions. Use sources in this order: + +1. Target application code, dependency metadata, installed package/JAR APIs, and tests. +2. Version-matching Flink Agents schema, docs, examples, or source when available. +3. This skill's references and [bundled YAML schema](assets/yaml-schema.json) as + the offline baseline. + +The bundled schema and patterns describe the Flink Agents revision that published +this skill. If the target dependency differs, prefer its matching contracts and +state any compatibility assumption that could not be verified. + +Do not invent APIs, versions, or commands from memory. + +Before presenting code as runnable, resolve every nontrivial import, constructor, +method, descriptor argument, and dependency coordinate against those sources. If a +contract cannot be resolved, either use a documented alternative or label the +fragment as pseudocode and state exactly what remains unresolved. Never create an +adapter or wrapper merely to make a speculative API look complete. Review Comment: **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. ########## dev/agent-skills/flink-agents-dev/SKILL.md: ########## @@ -0,0 +1,321 @@ +--- +name: flink-agents-dev +description: Use when building, scaffolding, modifying, debugging, converting, or verifying Apache Flink Agents applications, including Flink Agents YAML, Workflow Agent, ReAct Agent, Actions, Resources, MCP servers, vector stores, runtime skills, Python, or Java. Review Comment: **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? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
