Skip to Content
Usage GuideAI Agents

AI Agents

GlassFlow Agent Skills  let you create and operate GlassFlow pipelines from any AI coding assistant that reads SKILL.md files, including Claude Code, Cursor, and OpenAI Codex. Each skill is an instruction set that the assistant loads when you describe a matching task. Skills are scoped to common GlassFlow workflows like creating a pipeline, sending test messages, or diagnosing a failing stage.

The repository is open source and lives at glassflow/agent-skills.

Prerequisites

  • An AI coding assistant with skill or rule support. Install instructions for Claude Code, Cursor, OpenAI Codex, and other tools are in the Installation section below.
  • A reachable GlassFlow API. Local installs default to http://localhost:8081; remote installs point at whatever endpoint your team exposes.
  • Source and sink credentials. Skills will ask for them; they do not assume defaults.

Installation

Pick your AI coding tool.

Inside Claude Code:

/plugin marketplace add glassflow/agent-skills
/plugin install glassflow-agent-skills@glassflow-agent-skills

Claude Code fetches the skills and loads their descriptions. Skills do not run automatically; Claude only invokes a skill when your prompt matches its description.

To update later:

/plugin marketplace update glassflow-agent-skills

Skills load at the start of each session. If you edit a SKILL.md while the assistant is running, restart the session (or reload the window in Cursor) to pick up the change. To pull newer versions from this repository: run /plugin marketplace update glassflow-agent-skills in Claude Code, or git pull your local clone and re-copy skills/* for tools that use the file-drop install.

Available skills

SkillDescription
create-pipelineCreate a GlassFlow pipeline end-to-end. Walks through source configuration (Kafka or OTLP), optional dedup/filter/transform stages, ClickHouse sink mapping, then submits the v3 config to the GlassFlow API and waits for the pipeline to reach Running.
debug-pipelineLocalize a pipeline failure or missing-events problem. Starts with component logs (via kubectl or the OTel Collector’s log backend) and cross-checks with metrics for silent failures, backpressure, and DLQ rate.
tune-pipelineResolve sustained backpressure or sink-lag by reading GlassFlow’s emitted metrics to confirm the bottleneck, proposing targeted changes to replicas, batch sizes, stream limits, or dedup storage, applying them via the appropriate API endpoint, and verifying by re-reading the same metrics.

More skills are added as we surface common workflows. The canonical list lives in the repository.

Walkthrough: your first pipeline lifecycle

Skills chain naturally across the pipeline lifecycle. Here is one end-to-end story that uses all three.

1. Create the pipeline

“Create a GlassFlow pipeline named orders-prod that reads from the orders Kafka topic on kafka.local:9092 (SASL_PLAINTEXT, user glassflow, password in KAFKA_PASSWORD), deduplicates on order_id with a 1-hour window, and writes to the analytics.orders table on clickhouse.local.”

This invokes create-pipeline. The skill confirms the inputs it parsed, asks for anything missing (schema fields, ClickHouse credentials), builds a v3 pipeline config, submits it via POST /api/v1/pipeline, and polls until overall_status reaches Running. It finishes by suggesting a test-message recipe and a ClickHouse verification query.

2. Diagnose a problem when something looks off

“Diagnose pipeline orders-prod, the sink table stopped growing 30 minutes ago.”

This invokes debug-pipeline. The skill reads /health and /dlq/state, fetches sample DLQ records if any are present, and reports a structured diagnosis citing the verbatim error and a concrete next move. If the DLQ is clean, it picks the implicated component (sink, dedup, ingestor) and tails its logs via kubectl or the OTel Collector’s log backend, then cross-checks metrics for silent failures.

3. Tune for throughput once it is running

“Pipeline orders-prod has sustained sink lag, can you tune it?”

This invokes tune-pipeline. The skill captures a baseline of the symptom metric, maps it to a specific tunable (sink replicas, batch size, NATS stream sizing, dedup storage, etc.), proposes a concrete diff tied to the measured value, applies it via PUT /api/v1/pipeline/<id>/resources or POST /api/v1/pipeline/<id>/edit, and re-pulls the same metric queries 5 minutes later to verify the change helped.

Skills always confirm before they touch your environment. Nothing is submitted without an explicit yes.

Example prompts

Use the skills for any task you would normally run by hand against the GlassFlow API. The assistant infers which skill matches your prompt.

  • “Create an OTLP logs pipeline writing to observability.app_logs on the staging ClickHouse.”
  • “Set up a Kafka pipeline for the events topic with deduplication on event_id over 30 seconds.”
  • “Diagnose pipeline orders-prod, the sink table stopped growing 30 minutes ago.”
  • “Check the DLQ for pipeline orders-prod and tell me what’s failing.”
  • “Pipeline orders-prod is showing ingestor backpressure, can you tune it?”
  • “Sink lag on events-prod is 2 minutes behind real time, please fix.”
  • “Tune orders-prod so it can sustain 50,000 events per second.”

Contributing

The glassflow/agent-skills repository carries skills that are useful to GlassFlow users in general. If you have a workflow you would like distilled into a skill, open an issue describing the user-visible task, the inputs the skill needs, and the steps the agent should take. Or open a PR with a draft SKILL.md under skills/<skill-name>/ matching the structure of existing skills.

Last updated on
Python SDKInstallation