Make prepare-providers-documentation skill rewrite changelog entries for quality

[shahar1]

The AI-driven prepare-providers-documentation skill instructed the release manager to copy each commit subject verbatim into the changelog ("Subjects must be the original commit subject ... Don't paraphrase"). In practice that produced low-quality entries that reviewers had to fix by hand during the 2026-06-16 provider wave:

• uninformative wording (Add missing template_fields to FooOperator, fix the ftp tls),
• Conventional-Commit / scope prefixes (fix:, docs:, refactor:, fix(test_wasb.py):),
• lowercase starts and non-imperative mood (made ... to run, Renaming ...),
• raw dependency/dependabot phrasing instead of the actual version (Bump aiohttp regarding dependabot warning),
• test-file references in user-facing notes,
• non-user-facing CI / JS build-tooling bumps surfaced in visible sections,
• providers released with no user-facing change.

This replaces the "don't paraphrase" rule with explicit entry-wording rules (capitalized, imperative, no prefixes, specific, dependency bumps pinned to the version read from pyproject.toml, Airflow-core compatibility notes), a "what is not user-facing → hidden block" section (CI/workflow-only changes, release-tooling bookkeeping, JS build/dev tooling, comment-only changes, internal renames), and an instruction to drop a provider to doc-only (no release) when nothing user-facing remains.

Classification itself is now done deterministically by the classify-provider-changes breeze command (added in #68215), so this guidance is layered on top of the classifier's output: the classifier picks the code; the skill still owns the entry text and visibility (which misc-classified bumps belong in the hidden block).

Per review (thanks @eladkal): a runtime dependency bump is user-facing — and stays a visible entry with its version — even when the trigger was a CI failure, a dependabot alert, or a CVE / security advisory (common for fab / edge3). Only workflow-only and dev/build-tooling changes are hidden. Release-tooling bookkeeping commits (Prepare providers release ...) are always internal and hidden.

Documentation/tooling-only change to the skill; no runtime Airflow code is affected.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 4.8)

Generated-by: Claude Code (Opus 4.8) following the guidelines

[nailo2c]

LGTM 😄

[SameerMesiah97]

I must admit that I am not familiar with using SKILLs to tune these Agentic systems (is that the correct classification?) so I am not sure how to ascertain the sensitivity of these tools to differences in prompt structure and wording (though I have noticed being as specific as possible improves the quality of response so I like that you have named the tools to be used).

There is one concern that I have about having AI re-write changelog entries. Isn't there a risk that encouraging the model to rewrite subjects rather than staying close to the original increases the chance of hallucinating behaviour? Maybe it is better to have a slightly rough but accurate entry than a polished one that invents details. I imagine rough entries are easier to spot and manually correct vs trying to ascertain whether an entry is factually correct during a busy release cycle.

[shahar1]

I must admit that I am not familiar with using SKILLs to tune these Agentic systems (is that the correct classification?) so I am not sure how to ascertain the sensitivity of these tools to differences in prompt structure and wording (though I have noticed being as specific as possible improves the quality of response so I like that you have named the tools to be used).

There is one concern that I have about having AI re-write changelog entries. Isn't there a risk that encouraging the model to rewrite subjects rather than staying close to the original increases the chance of hallucinating behaviour? Maybe it is better to have a slightly rough but accurate entry than a polished one that invents details. I imagine rough entries are easier to spot and manually correct vs trying to ascertain whether an entry is factually correct during a busy release cycle.

Good call, tried to refine the instruction so it would also ground it using the diff - when having it in context, it should hallucinate less.
I hope that it's better now :)

[SameerMesiah97]

I must admit that I am not familiar with using SKILLs to tune these Agentic systems (is that the correct classification?) so I am not sure how to ascertain the sensitivity of these tools to differences in prompt structure and wording (though I have noticed being as specific as possible improves the quality of response so I like that you have named the tools to be used).
There is one concern that I have about having AI re-write changelog entries. Isn't there a risk that encouraging the model to rewrite subjects rather than staying close to the original increases the chance of hallucinating behaviour? Maybe it is better to have a slightly rough but accurate entry than a polished one that invents details. I imagine rough entries are easier to spot and manually correct vs trying to ascertain whether an entry is factually correct during a busy release cycle.

Good call, tried to refine the instruction so it would also ground it using the diff - when having it in context, it should hallucinate less. I hope that it's better now :)

Yes. I agree with the refinement.