+kestra skills

skills/kestra-flow/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: kestra-flow
+description: Generate, modify, or debug Kestra Flow YAML by fetching the live flow schema and applying the same guardrails used by the Kestra AI Copilot. Use when users ask to create, write, update, or fix a Kestra flow.
+compatibility: Requires curl and network access to https://api.kestra.io/v1/plugins/schemas/flow. No Kestra instance required.
+---
+
+# Kestra Flow Skill
+
+Use this skill to generate production-ready Kestra Flow YAML grounded in the live schema.
+
+## When to use
+
+Use this skill when the request includes:
+
+- Generating a new Kestra flow from scratch
+- Modifying, extending, or debugging an existing flow
+- Translating a workflow description into valid Kestra YAML
+
+## Required inputs
+
+- A description of the desired flow behavior
+- Namespace (and tenant ID if applicable)
+- Existing flow YAML if the request is a modification
+
+## Workflow
+
+### Step 1 — Fetch the flow schema
+
+Fetch the full schema with `curl` and read it directly — do not pipe it through any interpreter:
+
+```bash
+curl -s https://api.kestra.io/v1/plugins/schemas/flow
+```
+
+Read the raw JSON output to validate every type, property name, and structure used in the output. Do not generate anything before the schema is available.
+
+### Step 2 — Collect context
+
+Identify from the user message or conversation:
+
+- `id` — flow identifier (preserve if provided)
+- `namespace` — target namespace (preserve if provided)
+- Existing flow YAML (for modification requests)
+- Whether this is an **addition / deletion / modification** or a **full rewrite**
+
+### Step 3 — Generate the YAML
+
+Apply all generation rules below, then output raw YAML only.
+
+## Generation rules
+
+**Schema compliance**
+
+- Use only task types and properties explicitly defined in the fetched schema. Never invent or guess types or property names.
+- Property keys must be unique within each task or block.
+
+**Structural preservation**
+
+- Always preserve root-level `id` and `namespace` if provided.
+- For modification requests, touch only the relevant part. Do not restructure or rewrite unrelated sections.
+- Avoid duplicating existing intent (e.g., replace a log message rather than adding a second one).
+
+**Triggers**
+
+- Include at least one trigger if execution should start based on an event or schedule.
+- Do NOT add a `Schedule` trigger unless a regular occurrence is explicitly requested.
+- Trigger outputs are accessed via `{{ trigger.outputName }}`; only use variables defined in the trigger's declared outputs.
+
+**Looping**
+
+- Use `ForEach` for repeated actions over a collection.
+- Use `LoopUntil` for condition-based looping.
+
+**Flow outputs**
+
+- Only include flow-level `outputs` if the user explicitly requests returning a value from the execution.
+
+**State tracking between executions**
+
+- For state-change detection, use KV tasks (`io.kestra.plugin.core.kv.Set` / `io.kestra.plugin.core.kv.Get`) to store and compare state across executions.
+
+**JDBC plugin**
+
+- Always set `fetchType: STORE` when using JDBC tasks.
+
+**Date manipulation in Pebble**
+
+- Use `dateAdd` and `date` filters for date arithmetic.
+- Apply `| number` before numeric comparisons.
+
+**Credentials and secrets**
+
+- Never embed secrets or hardcoded credentials.
+- Use flow `inputs` of type `SECRET` or Pebble expressions (e.g., `{{ secret('MY_SECRET') }}`).
+
+**APIs and connectivity**
+
+- Prefer public/unauthenticated APIs unless the user specifies otherwise.
+- Never assume a local port; use remote URLs.
+
+**Quoting**
+
+- Prefer double quotes; use single quotes inside double-quoted strings when needed.
+
+**Error handling**
+
+- If the request cannot be fulfilled using only schema-defined types and properties, output exactly:
+  ```
+  I cannot generate a valid Kestra Flow YAML for this request based on the available schema.
+  ```
+
+## Output format
+
+- **Raw YAML only** — no prose, no markdown fences, no explanations outside the YAML.
+- Use `#` comments at the top of the output for any caveats, assumptions, or warnings.
+- The output must be ready to paste directly into the Kestra UI or deploy via `kestractl`.
+
+## Example prompts
+
+- "Write a Kestra flow that fetches a public API every hour and stores the result in KV store."
+- "Add a Slack notification task to this existing flow when any task fails."
+- "Generate a flow in namespace `prod.data` that reads from a Postgres table and writes the result to S3."
+- "Debug this flow YAML — it has a trigger variable reference that doesn't exist."

skills/kestra-ops/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: kestra-ops
+description: Operate Kestra environments using kestractl for context setup, flow inspection, flow validation and deployment, execution monitoring, namespace operations, and namespace file management. Use when users request Kestra operational CLI tasks in dev, staging, or production.
+compatibility: Requires kestractl, network access to the Kestra API, and valid tenant/token credentials.
+---
+
+# Kestra Operations Skill
+
+Use this skill to perform day-to-day Kestra operations with `kestractl`.
+
+## When to use
+
+Use this skill when the request includes:
+
+- Listing, inspecting, validating, or deploying flows
+- Triggering executions and checking execution status
+- Managing namespaces or namespace files (`nsfiles`)
+- Configuring or switching Kestra CLI contexts
+
+## Required inputs
+
+- Target environment or context (`dev`, `staging`, `prod`)
+- Host URL, tenant, and authentication method (usually token)
+- Namespace, flow ID, execution ID, and/or local file paths
+- Output preference (`table` for human-readable, `json` for automation)
+
+## Prerequisites
+
+- `kestractl` is installed and executable
+- Access token and tenant are available
+- A valid context exists in `~/.kestractl/config.yaml` or values are provided via env vars/flags
+
+## Configuration precedence
+
+Resolve config from highest to lowest precedence:
+
+1. Command flags (`--host`, `--tenant`, `--token`, `--output`)
+2. Environment variables (`KESTRACTL_HOST`, `KESTRACTL_TENANT`, `KESTRACTL_TOKEN`, `KESTRACTL_OUTPUT`)
+3. Config file (`~/.kestractl/config.yaml`)
+4. Built-in defaults
+
+Common setup:
+
+```bash
+kestractl config add dev http://localhost:8080 main --token DEV_TOKEN
+kestractl config add prod https://prod.kestra.io production --token PROD_TOKEN
+kestractl config use dev
+kestractl config show
+```
+
+## Standard workflow
+
+1. Resolve and confirm the target context.
+2. Run read-only discovery first.
+3. Validate artifacts before any deployment.
+4. Execute the requested operation with explicit flags.
+5. Verify outcomes (`--wait` for run operations where needed).
+6. Return a concise ops report with results and follow-up actions.
+
+## Command patterns
+
+Flows:
+
+```bash
+kestractl flows list my.namespace
+kestractl flows get my.namespace my-flow
+kestractl flows validate ./flows/
+kestractl flows deploy ./flows/ --namespace prod.namespace --override --fail-fast
+```
+
+Executions:
+
+```bash
+kestractl executions run my.namespace my-flow --wait
+kestractl executions get 2TLGqHrXC9k8BczKJe5djX
+```
+
+Namespaces:
+
+```bash
+kestractl namespaces list
+kestractl namespaces list --query my.namespace
+```
+
+Namespace files:
+
+```bash
+kestractl nsfiles list my.namespace --path workflows/ --recursive
+kestractl nsfiles get my.namespace workflows/example.yaml --revision 3
+kestractl nsfiles upload my.namespace ./assets resources --override --fail-fast
+kestractl nsfiles delete my.namespace workflows --recursive
+```
+
+## Guardrails
+
+- Confirm production context before write operations (`deploy`, `upload`, `delete`).
+- Prefer `flows validate` before `flows deploy`.
+- Use `--output json` for scripting and automation reliability.
+- Avoid `--verbose` in shared logs because it can expose credentials.
+- For destructive `nsfiles` actions, confirm path scope and only use `--force` intentionally.
+
+## Response format
+
+- Context used (host, tenant, context name)
+- Commands executed (grouped by read vs write)
+- Results (success/failure and key IDs)
+- Risks, rollback notes, and follow-up actions
+
+## Example prompts
+
+- "Use `kestra-ops` to validate and deploy all flows in `./flows` to `prod.namespace` with fail-fast enabled, then report what changed."
+- "Use `kestra-ops` to run `my-flow` in `my.namespace`, wait for completion, and summarize execution status."
+- "Use `kestra-ops` to upload `./assets` to namespace files under `resources` with override enabled, then list uploaded files recursively."