Create Connector
Developmentcreate-connectorCreate Connector is an Agent Skill for development published in the elastic/kibana repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Creates a new connector spec for Kibana. Use when asked to create (or add) a new connector, integration, or data source.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/elastic/kibana/blob/HEAD/src/platform/packages/shared/kbn-connector-specs/.claude/skills/create-connector/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/create-connector, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Create a Connector
We're going to create a new connector spec for $0. The connector will enable Kibana to interact with the third-party service and expose operations as tools for AI agents.
Reference Materials
- reference/connector-patterns.md — Directory structure, file templates, and registration patterns
Step 1: Determine the Connector Strategy
Check if $0 has an official hosted MCP server. If so, creating an MCP-native connector is preferred.
MCP server available? → Read reference/mcp-connector-setup.md and follow its steps.
No MCP server available? → Read reference/custom-connector-setup.md and follow its steps.
Follow only the steps for the chosen path. Do not mix them.
Step 2: Create the Connector Spec
Create the connector spec in src/platform/packages/shared/kbn-connector-specs/src/specs/{connector_name}/.
Follow the patterns in reference/connector-patterns.md:
{connector_name}.ts— ConnectorSpec definition with metadata, auth, schema, and actionstypes.ts— Zod input schemas and inferred TypeScript types for each action{connector_name}.test.ts— Unit testsicon/index.tsx— Brand icon component
Register in src/platform/packages/shared/kbn-connector-specs/src/all_specs.ts and connector_icons_map.ts.
Replace the placeholder icon with a proper brand icon. Search for existing SVG/PNG files in:
src/platform/packages/shared/kbn-connector-specs/src/specs/*/icon/x-pack/platform/plugins/shared/stack_connectors/public/connector_types/{connector}/
Step 3: Write LLM-Quality Descriptions and Skill Content
AI agents rely on descriptions to choose the right action and construct valid inputs. Every action and parameter must have high-quality descriptive text.
isTool and action descriptions
Actions should set isTool: true to be discoverable by AI agents in Agent Builder. This is the default for most actions. Use isTool: false only for actions that should not be invoked autonomously (e.g. destructive or admin-only operations).
Every entry MUST have a description field (plain string, NOT i18n.translate()) that explains:
- What the action does
- When an agent should use it (vs. other actions)
- What it returns
- For download/binary actions: a WARNING about large base64 payloads and the need for post-processing
Parameter descriptions
Every Zod parameter in input schemas MUST have a .describe() call that includes:
- What the parameter controls
- Concrete examples or allowed values
- Any constraints (format, length, required vs. optional behavior)
See the ServiceNow, Slack, and GitHub connector specs for examples of strong description quality.
The skill property
Add a skill property to the ConnectorSpec — a markdown string providing higher-level LLM guidance:
- Multi-step workflow patterns (e.g., "to create an incident, first call X, then Y")
- Common gotchas and error cases
- Best practices for the service
Use the [...].join('\n') pattern to keep the string readable in source:
skill: [
'## $0 Connector',
'',
'Use this connector to ...',
'',
'### Common patterns',
'- To do X, first call `actionA` then `actionB`',
].join('\n'),
Step 4: Create Tests
Add tests following the existing examples:
- Connector spec tests — See
google_drive/google_drive.test.tsorslack/slack.test.tsfor the pattern.
You do not need to execute the tests — just create the files.
Step 5: Write Documentation
Create a connector doc page in docs/reference/connectors-kibana/{name}-action-type.md.
Prerequisites
This step requires documentation skills from https://github.com/elastic/elastic-docs-skills. Check availability by invoking docs-check-style (use the Skill tool). If it fails with "skill not found", stop and tell the user:
Documentation skills are not installed. Please install them:
curl -sSL https://raw.githubusercontent.com/elastic/elastic-docs-skills/main/install.sh | bashThen re-run this step.
Write the doc page
- Read 1-2 existing connector docs from
docs/reference/connectors-kibana/as templates (for example,zendesk-action-type.md,jira-cloud-action-type.md). Follow the same structure. - Write the new doc page. Use
docs-syntax-helpif unsure about MyST Markdown syntax. - Run these skills on the new file and fix any issues:
frontmatter-description— generate thedescriptionfrontmatter fieldpage-opening-optimizer— verify H1 and opening paragraphapplies-to-tagging— validateapplies_toblockdocs-check-style— check Elastic style guide compliance
Update navigation and listings
- Add an entry in
docs/reference/toc.ymlunder the connectors section. - Add a row in
docs/reference/connectors-kibana/_snippets/elastic-connectors-list.md.
Once you are done developing the connector spec, tests, and documentation, let the user review your work before next steps.
Important Notes
- Stop if architectural gaps emerge — This skill is for adding connectors to the catalog, not for enhancing platform features
- Write rich descriptions — Every action and parameter must have descriptive text that helps LLMs choose the right action and construct valid inputs; add a
skillproperty with multi-step patterns and gotchas - Follow existing patterns — Look at Slack, GitHub, Google Drive, and ServiceNow connectors for reference
- DO NOT modify existing documentation — There may be existing connectors with similar names. Do not modify their documentation files.