Validate Integration Docs

Documents

validate-integration-docs

Validate Integration Docs is an Agent Skill for documents published in the elastic/integrations repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Lint an Elastic integration package's markdown with vale and propose fixes. Use when the user says "vale check," "lint docs," "validate the README," "check integration markdown," or wants to polish an integration's docs before opening a PR. Filters out false positives inside Go-template comment blocks in _dev/build/docs/, then re-runs vale against the rendered docs/ output after `elastic-package build` as a final pass.

View on GitHub ↗

QUICK START

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.

Prompt to paste

Inspect the Agent Skill at https://github.com/elastic/integrations/blob/HEAD/.agents/skills/validate-integration-docs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/validate-integration-docs, 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.

validate-integration-docs

Lint an integration package's docs source, filter template noise, propose fixes, then verify the rendered output.

Phase 1 — Lint the source

Check prerequisites: run both checks before continuing:
- vale --version — if not found, tell the user to install it by following the Elastic vale linter guide.
- elastic-package version — if not found, tell the user to install it by following the elastic-package install guide.
Stop and report any missing tools before proceeding.
Locate the package root: find the nearest ancestor directory (including cwd) that contains both manifest.yml and _dev/build/docs/README.md. If not found, ask the user for the path before continuing.
Run vale on the source:
```
vale _dev/build/docs/README.md --output JSON
```
If additional *.md files exist under _dev/build/docs/, include them too.
Detect template-comment ranges: pre-scan the source file with a non-greedy DOTALL match for \{\{\s*/\*.*?\*/\s*\}\}. For each match, record (start_line, end_line) by counting newlines before the match start and end.
Filter findings: suppress any vale finding whose Line falls within any (start_line, end_line) range. Those lines are stripped by elastic-package build and their findings are false positives. Report only findings outside those ranges, grouped by file, with: Line, Match, Severity, Check, and Message.
Draft proposals for each reported finding:
- Action.Name == "replace" → mechanical substitution using Action.Params[0].
- Action.Name == "remove" → delete the Match span.
- No action params (for example Elastic.Semicolons, Elastic.DontUse, Elastic.Ellipses) → draft a prose rewrite of the sentence using context.
Confirm before editing: present all proposals together and ask the user which to apply (all / subset / none). Apply only confirmed edits via the Edit tool. Never edit files under packages/*/docs/ — only _dev/build/docs/ sources.

If Phase 1 finds no actionable issues, skip the confirmation step and proceed to Phase 2.

Phase 2 — Build and re-lint the rendered output

Build the package from the package root:
```
elastic-package build
```
Run vale on the rendered README:
```
vale packages/<pkg>/docs/README.md --output JSON
```
Extend to other docs/**/*.md if present. No template-comment filtering is needed — comments are stripped by the build.
Report and propose fixes exactly as in Phase 1 steps 6–7. If a Phase 2 finding maps to a source line, edit _dev/build/docs/ only.
Re-run elastic-package build after any source edits so the user can confirm the rendered output is clean.

Review checklist

Before reporting the task complete, verify:

vale and elastic-package were both confirmed available (or the user was sent to the relevant install guide).
Every finding inside a {{/* */}} block was suppressed in Phase 1.
No edits were written to any path under packages/*/docs/.
Every edit was confirmed by the user — nothing was silently auto-applied.
elastic-package build completed without error.
vale packages/<pkg>/docs/README.md (Phase 2) reported no findings.