GreatEugenius commented on code in PR #918: URL: https://github.com/apache/flink-agents/pull/918#discussion_r3655728043
########## 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. + +## Definition Strategy + +| Situation | Recommendation | +|---|---| +| New Workflow Agent or rewired event graph | Offer YAML plus Python/Java implementation files | +| Existing YAML application | Preserve and extend YAML | +| Existing programmatic Agent | Preserve its current API unless conversion is requested | +| `ReActAgent`, unsupported YAML surface, or explicit code-only request | Direct Python or Java API | + +For a new application, present YAML, direct Python API, and direct Java API as an +explicit choice after versions are confirmed. A recommendation explains the +tradeoff; it is not permission to select the API for the user. + +YAML does not declare an agent `type`. Do not add `type: workflow` or +`type: react`; `type` selects an implementation language where the schema allows it. + +YAML does not choose the business implementation language either. For a new YAML +application, ask the user to choose Python or Java before generating files. For an +existing application, detect and preserve the language from build metadata, source +files, function references, and explicit YAML `type` fields. Do not default to +Python merely because omitted YAML `type` fields currently resolve to Python. + +Workflow Agents already include built-in chat, tool-call, and context-retrieval +Actions. A model reasoning/tool loop can therefore remain YAML-defined. Choose +`ReActAgent` only when the user explicitly wants that programmatic abstraction, the +existing application already uses it, or a required ReAct-specific surface is not +available through YAML. + +## Scaffolding Boundary + +Complete framework-owned wiring, but do not invent business behavior. Unless the +user explicitly asks for an implementation and supplies its contract, generate only +an importable or compilable signature skeleton for each custom Action, Tool, domain +client, data transformation, and runtime Skill. Preserve user-provided names, +parameters, types, and descriptions. When those details are absent, derive a stable +name from the stated capability and use a minimal neutral signature such as one +opaque string request and string result; mark unresolved input fields and result +types with focused TODOs and fail explicitly with `NotImplementedError` or +`UnsupportedOperationException`. + +Do not author domain rules, REST endpoints, diagnostic procedures, prompts, data +models, Tool results, runtime Skill instructions, or test doubles from a high-level +application idea. Do not propose a standard REST API, MCP server, or mock backend as +the implementation of a custom Tool. Do not ask the user to lock a business input +identity schema, deployment platform, service API, authentication design, or log/ +metric backend merely to scaffold the application. Generate the neutral skeleton +and leave those choices as TODOs for the user. Built-in Flink Agents Actions are +framework behavior and need no generated implementation. + +## Interaction Discipline + +For a new or empty project, use sequential decision gates. Ask only the current Review Comment: **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. -- 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]
