write-changelog-entry

Use when asked to add, revise, or review a changelog or release-notes entry in this repo. Inspect the existing changelog section style and the relevant PR, issue, and commit context first, then write a focused entry in the correct release section without overstating docs, tests, or chores unless they are the primary user-facing change.

Quality

88%

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%

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

The body is highly actionable with a clear sequenced workflow and an end-of-task verification checklist, and it assumes Claude's competence. Its main weaknesses are repeated restatements of the same docs/tests/chore rule (conciseness) and a fully inline structure with no progressive disclosure to offload the pattern examples.

Suggestions

Consolidate the repeated docs/tests/chores guidance (currently restated on lines 73, 91, 94, 95, and 96) into a single canonical rule in "Repo-specific guidance" and reference it from the workflow step.

Move the "Good patterns" example entries into a references file (e.g. references/changelog-examples.md) and link to it from the body, so the main SKILL.md stays a lean overview and progressive disclosure can reach 3.

Tighten the overlap between "Target file selection" and "Root vs Flutter package changelog", which re-explain the same audience split twice; merge the audience guidance into one section.

Dimension	Reasoning	Score
Conciseness	Assumes Claude's competence (no explanation of what a changelog is) and is mostly lean, but the "don't overstate docs/tests/chores" guidance is restated ~5 times (lines 73, 91, 94, 95, 96), which is unnecessary repetition that could be tightened into one rule. Not a 1 because it is not padded with concepts Claude already knows; not a 3 because of the redundancy.	2 / 3
Actionability	Concrete, copy-paste-ready guidance throughout: exact bucket headings ("### New features" etc.), real good-pattern examples ("Add `scrollable` to `NavigationRail` for overflowed destinations ([#1923](...), [#6356](...)) by @login."), and precise attribution/linking rules. Instruction-only but highly actionable, so absence of runnable code is not penalized.	3 / 3
Workflow Clarity	A clear numbered 5-step Workflow (inspect section → inspect source of truth → extract change → write items → add links/attribution) followed by an explicit "## Checks" validation checklist ("Before finishing, verify:..."). Changelog editing is not a destructive/batch op requiring a fix-retry loop, and verification steps are present, so no cap applies.	3 / 3
Progressive Disclosure	No bundle files exist and the skill is a single ~125-line file with well-organized sections (good navigation via headings), but there is no progressive disclosure via references — all detail (good patterns, examples, repo-specific guidance) is inline. Not a 1 (not a monolithic wall of text; well sectioned), not a 3 (no one-level-deep references splitting detail out, and the file is over the 50-line simple-skill exemption).	2 / 3
	Total	10 / 12 Passed

Description

100%

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 strong, well-scoped description: it states concrete actions, includes an explicit "Use when" trigger with natural vocabulary, answers both what and when, and is clearly distinct from other skills. No changes needed.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "add, revise, or review a changelog or release-notes entry", "Inspect the existing changelog section style and the relevant PR, issue, and commit context", and "write a focused entry in the correct release section" — matching the score-3 anchor for multiple specific concrete actions.	3 / 3
Completeness	Explicitly answers both: what ("Inspect... then write a focused entry in the correct release section without overstating docs, tests, or chores") and when ("Use when asked to add, revise, or review a changelog or release-notes entry"), with a clear "Use when" trigger clause.	3 / 3
Trigger Term Quality	Natural terms a user would say — "changelog", "release-notes entry", "add", "revise", "review" — are well covered; a user asking to "add a changelog entry" or "write release notes" would land here. Not a 2 because it goes beyond a single keyword to a natural phrasing.	3 / 3
Distinctiveness Conflict Risk	Narrow niche scoped to changelog/release-notes entries in this repo, with a distinctive qualifier ("without overstating docs, tests, or chores unless they are the primary user-facing change") making it unlikely to trigger for unrelated skills.	3 / 3
	Total	12 / 12 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 8 suspicious	Warning

	Total	15 / 16 Passed

Repository: flet-dev/flet
Path: .agents/skills/write-changelog-entry/SKILL.md
Commit: db0df8e

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.