prepare-providers-documentation

Replace the manual commit-by-commit classification step in `breeze release-management prepare-provider-documentation` with AI-driven classification. For each provider with pending changes, analyze every PR (batched into one sub-agent per provider, not one per PR), pay special attention to potentially breaking changes by inspecting the actual diff, scope multi-provider PRs to the current provider's slice, ask the release manager when uncertain, and apply version bumps + changelog entries. Use during the regular provider release cycle as an alternative to the interactive breeze prompts.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

77%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A thorough, highly actionable release-engineering workflow with excellent sequencing and validation gates, but it is very long for a single SKILL.md and inlines large reference-style material (sub-agent prompt, breaking-change checklist, changelog rules) that would benefit from being split into bundle files.

Suggestions

Move the sub-agent briefing prompt template and the breaking-change checklist into a references/ file (e.g. references/classification.md) and link to it from Phase 3, reducing the main body's token load.

Consolidate the several overlapping warning blocks about doc-only markers and within-wave renames into a single concise 'gotchas' section; the worked examples can be trimmed to one representative case each.

Extract the changelog format rules and entry-rewrite exceptions in Phase 4b into references/changelog-format.md, keeping only the skeleton and the bump table inline.

Dimension	Reasoning	Score
Conciseness	The body is information-dense with genuine project-specific knowledge, but at ~1130 lines it carries noticeable padding — repeated warning blocks, multiple worked examples, and a long breaking-change checklist that could be tightened or moved out — fitting 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than the lean 4 anchor.	3 / 5
Actionability	Provides fully executable guidance throughout: concrete breeze/git/gh commands, exact JSON and RST skeletons, a copy-paste sub-agent briefing prompt, and a precise pipe-delimited output row format covering the common cases.	5 / 5
Workflow Clarity	Five clearly sequenced phases (plus incremental phases) with explicit validation in Phase 5 — prek run, idempotent reapply check, and check_changelog_entries.py --fix with a defect table — and feedback loops (validate -> fix -> re-validate); the batch/destructive cap does not apply because validation is present.	5 / 5
Progressive Disclosure	Sectioning is good and repo-path references are signaled, but the skill is a monolithic ~1130-line file with no bundle files; the sub-agent prompt template, breaking-change checklist, and changelog format rules that clearly belong in separate reference files are inlined, matching the 3 anchor.	3 / 5
	Total	16 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A highly specific, third-person description that clearly states both the capability and the trigger context for a narrow release-engineering workflow. It is comprehensive on actions and unambiguous about when to invoke it, with only minor room to add a few more natural trigger synonyms.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'analyze every PR', 'inspecting the actual diff', 'scope multi-provider PRs to the current provider's slice', 'apply version bumps + changelog entries', 'batched into one sub-agent per provider' — with comprehensive coverage of the workflow, matching the 5 anchor.	5 / 5
Completeness	Explicitly answers both what (AI-driven classification, diff inspection, version bumps + changelog entries) and when ('Use during the regular provider release cycle as an alternative to the interactive breeze prompts'), with concrete trigger phrasing matching the 5 anchor.	5 / 5
Trigger Term Quality	Good keyword coverage including the exact 'breeze release-management prepare-provider-documentation' command, 'provider release cycle', 'interactive breeze prompts', 'version bumps', and 'changelog entries', but a few natural synonyms a release manager might say (e.g. 'release PR', 'incremental update') are absent, so it sits just below the 5 anchor.	4 / 5
Distinctiveness Conflict Risk	Tightly scoped to the breeze provider-release workflow with a clear niche and the exact command as a trigger, giving minimal overlap with other skills.	5 / 5
	Total	19 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (1130 lines); consider splitting into references/ and linking	Warning
referenced_paths_exist	Referenced path issues: 1 missing, 1 deeper-than-1-level	Warning

	Total	14 / 16 Passed

Repository: apache/airflow
Path: .agents/skills/prepare-providers-documentation/SKILL.md
Commit: caa8f28

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.