agentleFS
Sign inStart free
Microsoft AzureKnown publisherAzure/azure-service-operator/.agents/skills/create-release-notes/SKILL.md

create-release-notes

Skill916 starsChanged 7 days agoMITView on GitHub

Use when creating polished ASO release notes by automatically determining changes from git history since the last release tag.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use the release-note heading ### Breaking changes, before ### New resources and before ### Upcoming breaking changes when that section is …

    line 33
  2. Very specific:

    Use short PR or issue references like (#1234).

    line 36
  3. Very specific:

    Use the release-note heading ### Upcoming breaking changes, below ### Breaking changes when present and above ### New resources.

    line 41
  4. Very specific:

    Remove author attributions and full URLs.

    line 55
  5. Very specific:

    Remove author attributions, use short PR references (#1234)

    line 59
  6. Distinctive:

    Remove PRs that are not relevant to the release notes, such as:

    line 80
  7. Distinctive:

    Remove all "Code Structure Diagrams" entries.

    line 83
  8. Very specific:

    Always remove by @username in https://github.com/...

    line 84
  9. Distinctive:

    Use only these sections, in this order: Breaking changes (optional), Upcoming breaking changes (optional), New resources, Features, Bug …

    line 86
  10. Distinctive:

    Put current and upcoming breaking changes in their respective sections rather than duplicating them under Features or Bug fixes.

    line 87
  11. Distinctive:

    If in doubt, err on the side of including the entry - the human reviewer can always remove it if necessary but it's hard to add it back …

    line 88

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Create Release Notes

This skill creates polished, user-facing release notes for Azure Service Operator by automatically determining changes since the last release using git history.

Steps

  1. Generate the raw changelog by running the script from the repository root:
    scripts/v2/generate-raw-changelog.sh
    This determines the last release tag (latest v2.x.y) and outputs the commits (PRs) between that tag and HEAD.
  2. Categorize and format the raw changelog into polished release notes following the formatting rules below. Check the changelog and any release-planning issues or context supplied by the user for breaking changes in this release and upcoming breaking changes.
  3. For "New resources" entries, determine the correct Kubernetes group by checking which v2/api/$group folders changed:
    scripts/v2/generate-raw-changelog.sh --api-only
  4. Output the final release notes in raw (not rendered) markdown format.

Formatting Rules

Format the raw changelog into the sections below, in the order shown. Each section has specific transformation rules.

Breaking Changes Section

  • Use the release-note heading ### Breaking changes, before ### New resources and before ### Upcoming breaking changes when that section is present.
  • Include breaking changes that take effect in this release, such as removed resources, changed defaults, or new compatibility requirements.
  • Describe the user-visible impact and any required migration steps, workarounds, or configuration changes.
  • Use short PR or issue references like (#1234).
  • Omit this section entirely if there are no breaking changes in this release.

Upcoming Breaking Changes Section

  • Use the release-note heading ### Upcoming breaking changes, below ### Breaking changes when present and above ### New resources.
  • Include announced or proposed breaking changes that do not take effect in this release.
  • Clearly distinguish proposals from confirmed plans, and state that these changes are not part of this release. Include the target release only if it is known.
  • Describe how users can prepare or provide feedback, and link to the relevant planning issue or discussion.
  • Omit this section entirely if there are no upcoming breaking changes to announce.

New Resources Section

For entries about new resources or new API versions:

  • Refer to the resource by its Kubernetes group (the folder name under v2/api/), not marketing names (e.g. "machinelearningservices" not "AML")
  • To determine the group, check which v2/api/$group folder was changed in the PR
  • Format: * Add support for new {group} {ResourceName} resource (#{PR})
  • For new API versions: * Add support for new {group} API version {version} (#{PR})
  • Remove author attributions and full URLs; use short PR references like (#1234)

Features Section

  • Remove author attributions, use short PR references (#1234)
  • Rewrite to be user-focused (describe the benefit, not the implementation)
  • Prefix asoctl-specific items with asoctl:
  • Combine related PRs where it makes sense (e.g. multiple Helm chart config PRs)
  • Dependency update PRs can be summarized as "Updated numerous dependencies"

Bug Fixes Section

  • Rewrite each entry to start with "Fix bug where..." to describe the user-visible issue
  • Remove author attributions, use short PR references (#1234)
  • Prefix asoctl-specific items with asoctl:

Documentation Section

  • Clean up descriptions to be concise and user-friendly
  • Remove author attributions, use short PR references (#1234)

General Rules

  • Combine all dependabot and dependency PRs into a single "Updated dependencies" entry. Dependabot PRs have "Bump ..." as the start of their title and the commit is from dependabot[bot].
  • Remove PRs that are not relevant to the release notes, such as:
    • PRs that are only test recording changes.
    • PRs that only impact the generator. These changes are relevant to contributors but not ASO users.
  • Remove all "Code Structure Diagrams" entries.
  • Always remove by @username in https://github.com/... suffixes
  • Replace full PR URLs with short references: (#1234)
  • Use only these sections, in this order: Breaking changes (optional), Upcoming breaking changes (optional), New resources, Features, Bug fixes, Documentation. Dependency updates are a feature.
  • Put current and upcoming breaking changes in their respective sections rather than duplicating them under Features or Bug fixes.
  • If in doubt, err on the side of including the entry - the human reviewer can always remove it if necessary but it's hard to add it back later.
  • Group items logically within sections (e.g. asoctl items together at the end)
  • Output the final release notes in raw (not rendered) markdown format

Example Input

Last release: v2.18.0
Generating changelog for v2.18.0..05fc55aeb88cc6d4227373cf21522756ba61497d
05fc55aeb Move release notes prompt to skill (#5329)
37670a87a Bump github/codeql-action from 4.35.1 to 4.35.2 (#5327)
dced49ae1 Bump the k8s-go-deps group across 3 directories with 5 updates (#5325)
187e44d1c Fix small panic risk in certain secret writes (#5328)
fb66f70e5 Bump the go-deps group across 4 directories with 8 updates (#5326)
6a55daaf9 Add alias support for Private Link Service Connections (#5288)
2c75722a7 Add 10 new API Management CRDs for 2024-05-01: Gateway, Certificate, Logger, User, Group, ApiPolicy, ApiDiagnostic, and gateway sub-resources (#5301)
3bfbff895 Update Code Structure Diagrams (#5323)
ce0b424d3 Update API Docs (#5324)
0382e70e6 Enable smart deletion semantics for `authorization` group (#5289)
1f38efdb3 fix: re-enable Trivy installation after upstream breach resolution (#5319)
96f3ea411 Feature: Upgradable resources report - identify ASO resources with newer API versions available (#5211)
bacf39b94 Error if rename doesn't work (#5320)
54457ce41 Add Redis Enterprise database access policy assignment (#5290)
9efaeb4b4 Add support for Managed Instance for Apache Cassandra (#5175)
4959acea1 Bump the go-deps group across 3 directories with 13 updates (#5317)
c93f8cf21 Bump actions/github-script from 8.0.0 to 9.0.0 (#5314)
861df125d Fix additional directory (#5318)
601f3d437 Bump peter-evans/create-pull-request from 8.1.0 to 8.1.1 (#5315)
adbb05e51 Move API management to hybrid versioning (#5305)
b2fc4358e Pin GitHub actions (#5313)
663b1d129 Create ADR for properties that are sometimes secret and sometimes not (#5303)
20a61fffb Improve samples tester to work for refs in the same folder (#5310)
655fb5dff Improve CRD management performance (#5304)
e3c1c1e4f Fix go mod download cache permissions (#5309)
ba5d8568c Update Code Structure Diagrams (#5306)
5e17725b7 Update API Docs (#5307)
11d266446 Tweak skill for future success (#5302)
969dea4b6 Bump github/codeql-action from 4.33.0 to 4.35.1 (#5284)
c75dc050b Bump go.opentelemetry.io/otel/sdk from 1.40.0 to 1.43.0 in /v2 in the go-deps-sec group across 1 directory (#5300)
64394c2f9 Bump the k8s-go-deps group across 3 directories with 5 updates (#5268)
4bff0d6af Update Networking API version (#5295)
8480d238f Add testing skills for controllers and samples (#5273)
611f2126c Bump peterjgrainger/action-create-branch from 3.0.0 to 4.0.0 (#5297)
943357ae9 Update Code Structure Diagrams (#5293)
9d0dee90a Update API Docs (#5294)
69fd3dacd Bump docker/login-action from 4.0.0 to 4.1.0 (#5296)
bb131a0c2 Updates to 1es BICEP (#5291)
2279e99fd Extract separate Taskfile for mangle-test-json (#5281)
67c9bb1a9 Migrate MySQL resources to new versioning (#5278)
12bceedc4 Migrate synapse to hybrid versioning (#5286)
37685a2f6 Improve test replay using GET Barriers (#5102)
0fa07805c migrate web resources to hybrid versioning (#5272)
2a8a0d482 Fix subscription check guardrail (#5274)
e99db93d9 Update owners (#5280)
3cdf69814 Add skill name (#5279)
d04525d2b Update API Docs (#5276)
350cdd700 Add jobid parameter for 1ES Pool use (#5277)
49a9f18b1 Update Code Structure Diagrams (#5275)
bbb8bbd27 Address gosec alerts in mangle-test-json (#5260)
9cfe09ff6 Cache Go modules as a part of our devcontainer (#5267)
863d89261 Add Azure Communication Services support (v20230401) (#5263)
e88a45d1f Add skill for hybrid versioning (#5271)
b94b82327 Migrate appconfiguration to hybrid versioning (#5199)
4354b4bad Remove AKS preview version v1api20240402preview (#5261)
55c87a4ae Improve performance of CI (#5231)
17ac474db Update comments to dependabot compatible format (#5254)
cf20115ab Address gosec alerts in mangle-test-json (#5220)
b83af00d7 improve copilot instructions (#5262)
156fcb3f1 Update Code Structure Diagrams (#5265)
1cc3f2813 Update API Docs (#5266)
662f5582f Bump google.golang.org/grpc from 1.72.2 to 1.79.3 in /v2 in the go-deps-sec group across 1 directory (#5255)
1465b7600 Property conversion bugfixes (#5256)
86471ca32 Fix reconciliation blocking (#5224)
09efaaa61 Bump docker/login-action from 3.7.0 to 4.0.0 (#5247)
0565dac5b Bump devcontainers/go from 1.26 to 2-1.26 in /.devcontainer (#5245)
4e0ce1c00 Update Code Structure Diagrams (#5252)
848b4b7e1 Bump svenstaro/upload-release-action from 2.11.4 to 2.11.5 (#5249)
456f09c61 Bump actions/upload-artifact from 4.4.3 to 7.0.0 (#5250)
4913203b7 Bump peter-evans/create-pull-request from 7.0.11 to 8.1.0 (#5248)
cfd7ca54d Bump actions/github-script from 7.0.1 to 8.0.0 (#5246)
227474f71 Bump peter-evans/slash-command-dispatch from 4 to 5 (#5237)
7dd1a0ea7 Bump svenstaro/upload-release-action from 2.9.0 to 2.11.4 (#5239)
50f557c0c Add MySQL Flexible Server API versions v2024-12-30 and v2025-06-01-preview (#5173)
fe5f50401 Bump devcontainers/go from 1.25 to 2-1.26 in /.devcontainer (#5238)
af20ff979 Bump golang from 1.25 to 1.26 in /v2 (#5240)
950885551 Bump github/codeql-action from 4.32.4 to 4.33.0 (#5241)
4d7d080af Bump actions/create-github-app-token from 1 to 3 (#5242)
769c2b9cf Bump docker/build-push-action from 6 to 7 (#5243)
00dafadbe Extend dependabot to docker containers and github actions (#5235)
b27176b5c Update Code Structure Diagrams (#5233)
5f7766c88 Update API Docs (#5234)
74548287c Migrate alertsmanagement to hybrid versioning (#5221)
ad9c1d366 Improve handling of well-known names for Azure built-in role definitions (#5228)
98d2a4f09 Bump the k8s-go-deps group across 2 directories with 2 updates (#5222)
684901df1 Improve test recording redaction (#5229)
ea7837da7 Fix test logging  (#5227)
ecd3a2e5a fix delete-old-resourcegroups.sh flake (#5226)
7eb303024 split webhooks into multiple to avoid hitting max size (#5218)
cd58a03f3 Update Code Structure Diagrams (#5219)
fbc07a292 Update default max parallelism to 4 and add perf tests (#4822)
97dba19e4 Update our ADR on Azure differencing with latest discussions (#4962)
df7069655 Style Guide for docs (#5147)
615e2b9cd Reduce recording size (#5192)
3d79d8576 Add tasks to tidy recordings (#5214)
1e566f61f Bump go.opentelemetry.io/otel/sdk from 1.36.0 to 1.40.0 in /v2 in the go-deps-sec group across 1 directory (#5205)
f93ba20c3 Bump the k8s-go-deps group across 3 directories with 4 updates (#5206)
ce8cdb80f Disable trivy install (#5210)
919aa36f7 Update Code Structure Diagrams (#5204)
db44c2ede Add release notes for Azure Service Operator v2.18.0 (#5191)
ca72de605 Update docs for 2.18 (#5203)
556755cea Add Helm Chart (#5202)
05aac479f Update CoddQL Action version and pin with longer timeout (#5200)

Example output

This example has no current or upcoming breaking changes, so both optional sections are omitted.

## What's Changed

### New resources

- Add support for new communication CommunicationService resource (#5263)
- Add support for new dbformysql API versions v20241230 and v20250601preview (#5173)
- Add support for new documentdb CassandraCluster and CassandraDataCenter resources (#5175)
  - Note that currently ASO has no way to automatically obtain the ObjectId to match PrincipalId `a232010e-820c-4083-83bb-3ace5fc29d0b`, so you must run `az ad sp show --id a232010e-820c-4083-83bb-3ace5fc29d0b --query id -o tsv` to obtain that value for your subscription.  See [the sample](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/documentdb/cassandra/v20251015) for more details.
- Add support for new cache RedisEnterpriseDatabaseAccessPolicyAssignment resource (#5290)
- Add support for new apimanagement resources: Gateway, Certificate, Logger, User, Group, ApiPolicy, ApiDiagnostic, and gateway sub-resources (#5301)
- Add support for new network API version v20250301 (#5295)

### Features

- Add support for insights.actionGroup automationRunbookReciever and webhookReceiver to populate serviceUri from a secret (allowing safer use of URIs with embeded api-keys,
  passwords, or other secrets). (#5308)
- Update default max reconciliation parallelism to 4 for improved performance (#4822)
- Split webhooks into multiple to avoid hitting max CRD size limits (#5218)
- Improve CRD management performance (#5304)
- Enable smart deletion semantics for the authorization group (#5289)
- Add alias support for Private Link Service Connections on PrivateEndpoints (#5288)
- asoctl: Improve handling of well-known names for Azure built-in role definitions (#5228)

### Bug fixes

- Fix bug where reconciliation could block under certain conditions (#5224)
- Fix property conversion bugs (#5256)

### Documentation

- Add style guide for documentation (#5147)
- Update ADR on Azure differencing with latest discussions (#4962)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free