Goal

Help the agent turn an orchestration request into a correct DataKit flow, or debug an existing flow, without drifting into generic Gateway or declarative tool guidance.

Own DataKit reasoning: phase choice, node selection, DAG structure, connection shape, cache or vault requirements, and debug strategy.

Tool Selection

Prefer working from the artifact that already owns the flow:

• If the repo already contains DataKit YAML under deck, kong.yaml, or other

declarative config, edit that artifact in place.

• If the request depends on current Konnect state and kong-konnect MCP is

available, use it to inspect the attached plugin instance and confirm whether the problem is in the saved config or only in the repo copy.

• If the request is only about DataKit flow behavior, stay in this skill. Hand

off only when the work becomes mainly about decK, kongctl, or Terraform packaging.

References To Load

Load only the file that matches the current branch:

• references/node-reference.md
• Load when choosing node types, checking required fields, or confirming what

a node or implicit object can read or write.

• references/patterns.md
• Load when translating a user workflow into a starter flow shape such as

fan-out merge, auth injection, caching, XML conversion, dynamic URLs, or header mutation.

• references/resources-and-debugging.md
• Load when the problem depends on cache or vault resources, live debug

traces, deployment topology, or version-gated behavior.

Run scripts/validate_datakit_flow.py when a local YAML file already exists and you need deterministic checks for node naming, references, branch targets, cycles, implicit-field misuse, or missing cache or vault resources.

Workflow

1. Classify the request before drafting YAML.

• Identify whether the flow runs in access or response phase.
• Confirm whether the plugin should mutate service_request, mutate

response, or short-circuit with exit.

• Confirm the attachment boundary: service, route, consumer, consumer group,

or global.

1. Reduce the task to a small DAG.

• List the external calls, transforms, gates, and writes that must happen.
• Prefer the fewest nodes that preserve clarity.
• Treat independent call nodes as concurrent by default unless the output

of one is required by another.

1. Choose nodes from behavior, not from examples.

• Use call for HTTP work, jq for reshaping, branch for scheduling

conditional paths, cache for lookup or store, property for Kong internals, and exit only when the flow must terminate early.

• Load references/node-reference.md instead of guessing field names or

outputs.

1. Encode the flow around references and resources.

• Reserve explicit node names for actual nodes; never redeclare implicit

names such as request or response.

• Keep connections explicit with input or inputs.
• Add resources.cache or resources.vault only when the chosen nodes

require them.

• Prefer vault-backed secrets over hardcoded credentials.

1. Debug from the first broken edge, not from the final symptom.

• Start with the node whose output feeds the failing downstream node.
• If the issue is structural, run the validator first.
• If the issue is live execution, enable DataKit debug mode and inspect the

trace to find the earliest NODE_ERROR or the upstream cause of NODE_CANCELED.

DataKit-Specific Gotchas

• Implicit nodes are phase-bound interfaces, not normal nodes:

request and service_request belong to access; service_response and response belong to response.

• branch controls which named nodes are scheduled. It does not replace normal

data dependencies, so downstream nodes still need valid input or inputs wiring.

• cache and vault nodes are incomplete without matching resources.*

configuration.

• Non-2xx call responses are usually flow errors. Do not assume a response

body exists downstream unless the call succeeded or the user explicitly wants error-path handling.

• Some capabilities are version-gated, including newer node types and dynamic

URL overrides. If the request targets an older gateway, verify support before leaning on those features.

Validation Checklist

• Confirm the plugin is attached at the intended scope and phase.
• Confirm every explicit node name is unique and does not shadow an implicit

node.

• Confirm each reference base exists and each referenced field is valid for that

node or implicit object.

• Confirm cache and vault resources exist only when required and match the node

usage.

• Confirm downstream nodes consume the actual output shape produced upstream,

especially after jq, cache lookups, and XML conversion.

• Run

python3 plugins/kong-konnect/skills/gateway-plugin-datakit/scripts/validate_datakit_flow.py <yaml-path> for local files before concluding the structure is sound.

• For live debugging, prove the intended node path executed by checking the

first failing trace event, not just that the request reached Kong.

Handoffs

• Hand off to deck-gateway when the main job becomes declarative Gateway file

integration, diff, or apply workflow.

• Hand off to terraform-kong-gateway or terraform-konnect when the repo is

Terraform-owned and the problem becomes provider schema or state behavior.

• Hand off to kongctl-declarative when the repo already uses kongctl plan or

apply workflows for Konnect resources.