confluentinc/agent-skills/confluent-skill-creator

Confluent Skill Creator

A specialized skill creator for building Confluent product skills that are tested against real Confluent environments (local, platform, cloud, or WarpStream).

This skill extends the base skill-creator workflow with Confluent-specific requirements:

• Flexible scope: Skills can be use-case focused (e.g., "CDC from PostgreSQL to Iceberg") or component-specific (e.g., "Flink SQL skill", "Schema Registry skill")
• Platform targeting: Skills either target a specific platform (named in the skill) or support all platforms with platform-specific reference files
• Environment testing: Real E2E tests against local Confluent, Confluent Platform, Confluent Cloud, or WarpStream
• Safe CRUD operations: Show full plan and get confirmation before creating/modifying Confluent resources
• Credential management: Proper .env file setup for all required credentials
• Spec compliance: Created skills validated against the Agent Skills specification
• Smart defaults: Schema Registry with JSON_SR (schema GUID in header) by default

Prerequisites

• Python 3.9+
• confluent-kafka[avro,json,protobuf], requests, jsonschema, python-dotenv Python packages (see scripts/requirements.txt)
• Access to a Confluent environment (Cloud, Platform, local Docker, or WarpStream) for E2E testing

When to use this skill

Use this skill when a user wants to create a skill for external users that involves:

• Kafka topics, producers, consumers, or streaming applications
• Flink SQL or stream processing
• Connectors (Debezium CDC, sink connectors, etc.)
• Schema Registry (Avro, JSON Schema, Protobuf)
• Tableflow for data lake integration
• CDC pipelines from databases to data lakes
• Real-time data enrichment or transformation

Core Workflow

1. Understand scope and platform targeting (Confluent-specific)
2. Capture intent and interview
3. Write the skill draft
4. Validate spec compliance (Confluent-specific)
5. Set up test environment and credentials (Confluent-specific)
6. Create test cases and run E2E tests (Confluent-specific)
7. Evaluate with viewer
8. Iterate until satisfied
9. Optimize description
10. Package and deliver

Skill Anatomy and Progressive Disclosure

Apply these structural principles to every skill you create. They extend the base skill-creator guidance; the spec-compliance checks in Step 4 enforce the specifics, while this section is the mental model.

Anatomy of a skill

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled resources (optional)
    ├── scripts/     — executable code for deterministic/repetitive tasks
    ├── references/  — docs loaded into context as needed
    └── assets/      — files used in output (templates, icons, fonts)

Progressive disclosure — a three-level loading system

Skills load context in three tiers, so the model only pays for what it needs:

1. Metadata (name + description) — always in context (~100 words). This is the trigger; invest here.
2. SKILL.md body — loaded whenever the skill triggers (<500 lines ideal).
3. Bundled resources — loaded only as needed (unlimited; scripts can execute without being read into context).

Word counts are approximate — go longer when a skill genuinely needs it.

Key patterns:

• Keep SKILL.md under 500 lines. Approaching the limit? Add a layer of hierarchy and point clearly to where the model should look next.
• Reference files explicitly from SKILL.md with guidance on when to read each one — never have SKILL.md pull them all in upfront (see Step 4).
• For large reference files (>300 lines), include a table of contents at the top.

Domain organization

When a skill spans multiple domains/frameworks, organize by variant and let the model read only the relevant file — the same pattern as cross-platform Confluent skills (references/confluent-cloud.md, references/warpstream.md, …):

cloud-deploy/
├── SKILL.md          # workflow + variant selection
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Principle of lack of surprise

A skill's behavior must not surprise a user who has read its description. Skills must never contain malware, exploit code, or anything that could compromise system security, and must not facilitate unauthorized access, data exfiltration, or other malicious activity. Benign creative framing (e.g. "roleplay as X") is fine — misleading or malicious skills are not.

Step 1: Understand Scope and Platform Targeting

Skill scope

Understand what the user wants to build. Skills can be either use-case focused or component-specific — both are valid.

Use-case focused — solves a specific end-to-end problem:

• "Real-time customer order enrichment using Flink SQL"
• "CDC pipeline from PostgreSQL to Iceberg using Debezium and Tableflow"
• "Real-time anomaly detection with Kafka Streams"

Component-specific — covers a Confluent component's capabilities:

• "Flink SQL skill"
• "Kafka connector skill"
• "Schema Registry skill"
• "Tableflow skill"

If the user's request is ambiguous, ask:

"What should this skill cover? It can be a specific use case (e.g., 'CDC pipeline from Postgres to Iceberg') or focused on a component (e.g., 'Flink SQL skill'). What's the scope you have in mind?"

Platform targeting

After understanding scope, determine platform targeting:

"Which platforms should this skill support?

1. All supported platforms (Confluent Cloud, Confluent Platform, Apache Kafka, WarpStream)

2. Specific platform only (e.g., Confluent Cloud only, WarpStream only)"

If platform-specific:

• The platform name MUST appear in the skill's name field (e.g., confluent-cloud-cdc-tableflow, warpstream-producer-optimization)
• The skill description should explicitly state the target platform
• Testing must run against that specific platform

If cross-platform:

• The skill name should NOT include a platform prefix
• The generated SKILL.md must include a platform-detection step that asks which platform the user is targeting
• Platform-specific nuances go in references/<platform>.md files:
• references/confluent-cloud.md — Cloud-specific config, API keys, managed services
• references/confluent-platform.md — Self-managed specifics, security config
• references/apache-kafka.md — OSS defaults, no managed features
• references/warpstream.md — Object-storage architecture, config overrides
• The SKILL.md points to these conditionally: "If user's target is WarpStream, read references/warpstream.md and apply overrides"
• See PR #27 in agent-skills for the reference pattern

Once you understand scope and platform, proceed to the interview.

Step 2-3: Capture Intent and Write Skill

Follow the base skill-creator process for capturing intent and writing the skill draft. Ask about:

1. What should this skill enable users to do?
2. When should it trigger? (phrases users would say)
3. What components are involved? (topics, schemas, Flink, connectors, etc.)
4. How should the skill interact with Confluent? Ask the user:

> "How should this skill interact with Confluent? > 1. MCP tools (via Confluent MCP server — discover, manage, operate Confluent resources) > 2. CLI (Confluent CLI — confluent kafka topic create, confluent flink statement create, etc.) > 3. REST APIs (Confluent Cloud API, Schema Registry API, Kafka REST Proxy) > 4. Client libraries (confluent-kafka-python, Java clients, etc.) > 5. Combination (e.g., MCP for discovery + CLI for provisioning + client libs for data)"

Based on the answer, the created skill must include:

• The specific tool/CLI/API calls required, in execution order
• Any prerequisite setup (MCP server config, CLI login, API key creation)
• Error handling for each interaction method

1. What's the expected output? (working pipeline, sample data, SQL statements, etc.)

When writing the skill:

• Include links to relevant Confluent documentation (docs.confluent.io)
• Reference specific API endpoints, CLI commands, or MCP tool names
• Specify the execution order of tool/CLI/API calls clearly (step-by-step)
• Use bundled scripts for common operations (see scripts/ directory)
• Explain the "why" behind Confluent best practices
• Link to external docs so the skill automatically stays current. Prefer the .md form of a docs.confluent.io page over .html when it exists (docs.confluent.io serves clean Markdown at the same path, which is easier for agents to consume), and verify every link resolves before shipping:

``markdown For Flink SQL syntax, see [Confluent Flink SQL Reference](https://docs.confluent.io/cloud/current/flink/reference/overview.md) ``

Plan-before-execute requirement

The created skill MUST include a plan-before-execute step. Before the skill performs any operations (creating topics, registering schemas, deploying Flink statements, etc.), it must:

1. Present a numbered plan of all operations to the user
2. List which tools/CLI commands/API calls will be made and in what order
3. Wait for explicit user confirmation before proceeding
4. Never execute resource-modifying operations without approval

See plan-template.md for the plan format with interaction method examples.

Step 4: Validate Spec Compliance

Before proceeding to testing, validate the created skill against the Agent Skills specification.

Frontmatter validation

• name: required, max 64 chars, lowercase letters + numbers + hyphens only, no consecutive hyphens, must match parent directory name
• description: required, max 1024 chars, must describe both what the skill does AND when to use it
• If platform-specific: platform name must appear in name (e.g., confluent-cloud-cdc-tableflow)
• metadata: must include author: confluent, version (semver string), and last_updated (YYYY-MM-DD)
• compatibility: recommended if the skill requires specific packages, CLI tools, or environment access

Trigger overlap check

Before finalizing the description, check for unintended overlap with existing skills in the repo:

1. Scan skills/*/SKILL.md in the target repo and extract each skill's description: field
2. Compare the new skill's description keywords against existing skills
3. If significant overlap exists (≥2 non-generic keywords shared), verify the boundary is clear — a user prompt should unambiguously trigger only one skill, not both
4. If the boundary is ambiguous, refine the new skill's description to make the scope distinction clear, or add explicit exclusions where needed

Structure validation

• SKILL.md body under 500 lines — move detailed content to references/
• Do NOT inline reference file contents into SKILL.md — references must be lazy-loaded, read only when needed. Every activation pays the full context cost when references are inlined.
• Reference files one level deep from SKILL.md (no nested reference chains)
• Large reference files (>300 lines) include a table of contents at the top
• If SKILL.md exceeds ~200 lines and covers multiple workflows, include a mode-detection table near the top

Required artifacts