elastic / elastic/integrations
[docs] Document AI-assisted integration development with integration-skills
- Dominant language
- Handlebars
- Stars
- 333
- Forks
- 647
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 209
Description
## Summary
We have a public repository of agentic workflows for building and maintaining Elastic integrations: [elastic/integration-skills](https://github.com/elastic/integration-skills). These skills work with Cursor, Claude Code, Codex, and other LLM-powered coding environments.
External contributors and partners building integrations would benefit from knowing these workflows exist. The developer documentation at https://www.elastic.co/docs/extend/integrations (source: `docs/extend/`) is a natural place to surface them, since that's where developers go when they start building.
## Motivation
Integration quality varies significantly between contributors. The integration-skills repository encodes the team's best practices into structured, repeatable agent workflows — covering research, package scaffolding, CEL programs, ingest pipelines, field mappings, dashboards, and testing. Making developers aware of these workflows at the point where they're actually doing the work should raise the floor on quality without requiring more reviewer time.
## Proposal
Add references to integration-skills in the developer docs where they're most relevant to the task at hand. This could be a dedicated page (e.g. an "AI-assisted development" or "Agent workflows" page) linked from the existing docs, or inline callouts/tips in existing pages — or both. The specifics are open for discussion.
### Pages that would benefit from linking to integration-skills
The following `docs/extend/` files cover tasks where corresponding skills exist and could be referenced:
| File | Relevant skills |
|------|----------------|
| `index.md` | Top-level landing page — general mention of the toolkit |
| `build-new-integration.md` | `/research-integration`, `/create-integration` |
| `build-overview.md` | Tooling setup — integration-skills as part of the development environment |
| `build-create-package.md` | `/create-integration` |
| `add-data-stream.md` | `/create-integration`, `/input-configurations` |
| `edit-ingest-pipeline.md` | `/ingest-pipelines` |
| `add-mapping.md` | `/ecs-field-mappings` |
| `create-dashboards.md` | `/dashboard-guidelines`, `/dashboard-review` |
| `testing-validation.md` | `/integration-testing` |
| `tips-for-building.md` | General reference — `/cel-programs`, `/package-spec`, etc. |
| `quick-start.md` | Mention as an alternative fast-start path |
### Possible new page
A standalone page (e.g. `docs/extend/ai-assisted-development.md`) could:
- Explain what integration-skills is and who it's for
- List prerequisites (Docker, elastic-package, celfmt, mito, etc.)
- Show how to install skills (`npx skills add elastic/integration-skills`)
- Link to the repo README for full details
This page would then be linked from the "Building Integrations" section in `index.md` and the prerequisites in `build-overview.md`.
## Open questions
- Should we add a dedicated page, inline tips/callouts in existing pages, or both?
- How prominent should the references be? (e.g. tip admonition vs. a full section)
- Should this be positioned as "optional but recommended" tooling alongside elastic-package, or as a more prominent recommendation?
- Are there other surfaces beyond the developer docs where we should reference this? ([PR template](https://github.com/elastic/integrations/blob/main/.github/PULL_REQUEST_TEMPLATE.md), [CONTRIBUTING.md](https://github.com/elastic/integrations/blob/main/CONTRIBUTING.md), etc.)
## Related
- Repository: https://github.com/elastic/integration-skills
- Current developer docs: https://www.elastic.co/docs/extend/integrations
cc: @narph @P1llus
Contributor guide
Assessment
This issue has not been assessed yet.