Terminal
Terminal/Skill
Checks Elastic integration package manifests and changelogs against the package spec, including format versions, variables and version bumps.
By Elastic
Works with
npx skills add elastic/integration-skills --skill package-specThe rules and patterns defined in this skill and its reference files are the authoritative source of truth. When examining existing integrations in the elastic/integrations repository for reference, you may encounter patterns that conflict with what is specified here -- many integrations contain legacy patterns that predate current standards. Always follow this skill over patterns observed in other integrations. If a reference integration uses a deprecated or prohibited pattern, do not copy it.
Use this skill when tasks include:
manifest.yml at root or data stream levelchangelog.yml entriesvar_groups or provider_permissions (schema and floors)elastic-package lint or elastic-package check errors on manifests or changelogsformat_version is needed for a package's featurescreate-integration)input-configurations -> references/federated-identity-aws.md)ingest-pipelines)ecs-field-mappings)cel-programs)review-integration skill's references/transform-guide.md)For package directory layout and required files, see create-integration -> references/package-layout.md. For elastic-package CLI commands and troubleshooting, see elastic-package-cli. For enabling Federated Identity (Cloud Connectors) on an AWS integration, see input-configurations -> references/federated-identity-aws.md.
The format_version field in manifest.yml declares which elastic/package-spec version the package conforms to. The current default for new packages is "3.4.2".
Use the minimum version that supports the features the package actually uses, not the latest available spec version. Bumping without needing new features:
Only bump when the package uses a feature introduced in a newer spec version:
| Feature | Minimum format_version |
|---|---|
| Basic package structure | 1.0.0 |
| Input-level variables | 2.0.0 |
elasticsearch.privileges | 2.3.0 |
routing_rules.yml support | 2.9.0 |
lifecycle field | 3.0.0 |
Secret variables (secret: true) | 3.0.0 |
elasticsearch.source_mode | 3.0.3 |
var_groups | 3.6.1 |
provider_permissions (Federated Identity IAM declarations) | 3.6.4 |
Justified exception — Federated Identity: packages that declare provider_permissions (and typically var_groups) must use format_version: "3.6.4". That bump activates 3.6.0+ pipeline validators; land pipeline hygiene first if lint surfaces pre-existing violations. See references/var-groups-and-provider-permissions.md and input-configurations -> references/federated-identity-aws.md.
See references/format-version-features.md for the full feature-to-version table including recent spec additions (3.6.0+), and references/manifest-rules.md for the review procedure.
The current default constraint is "^8.19.0 || ^9.1.0". This is set in the root manifest.yml only -- data stream manifests must NOT set their own conditions.
When an integration uses features that require a newer agent (e.g., CEL functions introduced in v9.3.0), the constraint must be adjusted accordingly. For systematic version verification of CEL features, see the review-integration skill's version check references.
Justified exception — Federated Identity / use_cloud_connectors: set conditions.kibana.version to "^9.6.0" and conditions.agent.version to "^9.4.0" (or higher). If the current Kibana constraint still covers a line that ^9.6.0 would drop, do not bump silently — escalate per Floors and hygiene in input-configurations -> references/federated-identity-aws.md.
Fleet variables exist at four levels:
manifest.yml top-level vars:manifest.yml under policy_templates[].vars:manifest.yml under policy_templates[].inputs[].vars:data_stream/*/manifest.yml under streams[].vars:A variable declared in an inner scope must not reuse the name of a variable in an outer scope. This is variable shadowing and is rejected by elastic-package validation.
See references/manifest-rules.md -> Variable shadowing for full rules, examples, and common patterns.
Every Handlebars {{var}} must be declared in a manifest -- undeclared variables silently resolve to empty strings. Handlebars helpers ({{#if}}, {{#each}}, {{#unless}}, {{#contains}}) and built-in variables ({{data_stream.type}}, {{data_stream.dataset}}, {{data_stream.namespace}}, {{output}}) are exempt.
Routing rules require dynamic flags -- when a data stream uses routing_rules.yml, the data stream manifest must declare elasticsearch.dynamic_dataset: true and elasticsearch.dynamic_namespace: true.
Use proper YAML nesting, not dotted keys -- elasticsearch.dynamic_dataset as a literal key name creates a single flat key, not a nested object. Use nested elasticsearch: -> dynamic_dataset: structure.
A green lint does not prove an input exists -- the input name is an
unvalidated string everywhere it appears: policy_templates[].inputs[].type
and the data stream's streams[].input in an integration package,
policy_templates[].input in an input package. Do not confuse it with the
enum-backed data stream type, which in an integration package is a
different field with the same name. See references/manifest-rules.md ->
Input names are not validated.
See references/manifest-rules.md for complete rules, correct/incorrect examples, and the review checklist.
changelog.yml is a version-grouped array; newer versions go on top:
- version: "1.2.0"
changes:
- description: Added example parsing for edge-case payloads.
type: enhancement
link: https://github.com/elastic/integrations/pull/12345
Each entry requires description, type, and link. Valid types: enhancement, bugfix, breaking-change.
x.y.Z): bug fixes and low-risk fixesx.Y.z): new content -- new data streams, new fields, new featuresX.y.z): breaking changes -- field type changes or removals on existing integrations, ECS mapping conflicts, required config/auth changes that break existing policies, data stream restructuring, default behavior changes that alter collected or normalized dataInternal metadata-only changes that do not alter what ships to users need no version bump and no changelog entry: owner.github reassignment, CODEOWNERS updates, CI/dev-tooling files outside the built package. Reviewers must not flag the absence of a bump for such diffs.
Related bump conventions from elastic/integrations practice (see review-integration/references/repo-conventions.md for the dated details):
owner.type changes ARE published package metadata -- minor bump.group: manifest field -- patch bump + changelog entry.requires: dependency bumps arrive with their own patch bump and changelog entry; never ask a human to redo or justify them.kibana.version constraint updates are NOT breaking changes.type calibration (for reviewers)Flag an entry's type only when the diff or the entry's own description shows an observable compatibility or behavior change: dropped stack support, dataset/field rename or removal, field type change, default-behavior change, policy-breaking config moves. Re-bucketing between bugfix and enhancement, or splitting/merging entries, is editorial judgment for the author -- not a review finding.
Edit changelog.yml directly, or use elastic-package changelog add (see elastic-package-cli skill for command flags and --next patch|minor|major usage).
link field -- the link must be the pull request URL of the PR that introduces the change (https://github.com/elastic/integrations/pull/<n>), not an issue URL. elastic-package lint only validates that the number is a positive integer and rejects pull/0; use a real PR number or pull/99999 as a development placeholder and replace before merge. Review tooling recognizes placeholder shapes (a repeated digit such as 1 or 9999, zeros, 99999, 12345) and CI fails any number other than the PR's own, so both keep flagging a placeholder until it is replaced -- that is expected pre-merge behavior, not noiseSee references/changelog-patterns.md for detailed patterns, breaking-change checklist, and CI examples.
The changelog link field must point to the PR that introduces the change, but the
real PR number is only known once a PR has actually been opened -- everything up to
that point necessarily uses the pull/99999 placeholder from the pitfall above. This
step is easy to skip because it happens after the rest of the package work is done,
outside the usual build/test loop.
Once the PR exists on GitHub:
gh pr create output or the PR URL).changelog.yml, replace every placeholder link
(https://github.com/elastic/integrations/pull/99999) with
https://github.com/elastic/integrations/pull/<real-number>.elastic-package lint to confirm the link now validates.The elastic/package-spec repository is the upstream authority for package structure, manifest schema, and validation rules. The spec/changelog.yml in that repo documents which features were added in each spec version.
Key points from the package-spec versioning model:
format_version in root manifest.ymlformat_version: x.y.z must be valid against specs in the range [x.y.z, X.0.0) where X = x + 1See references/format-version-features.md for the curated feature-to-version table.
| File | Contains |
|---|---|
references/manifest-rules.md | Full rules for format_version selection, variable shadowing, Handlebars variable declarations, routing rules, YAML structure, and severity-tagged review checklist |
references/changelog-patterns.md | Changelog entry patterns, semver rules, breaking-change checklist, CI examples |
references/format-version-features.md | Feature-to-version table sourced from elastic/package-spec, including recent spec additions |
references/var-groups-and-provider-permissions.md | Schema for var_groups and provider_permissions, floors, validators; handoff to Federated Identity procedure |