Skip to content

Maintenance: stop asking contributors to regenerate the agent skill references #8806

Description

@leandrodamascena

Since #8745 the agent skill references in .agents/skills/.../references/ are generated from docs/ and a test in CI fails when the committed files are out of date. The idea was to never let them drift. In practice it moved the cost to the wrong people.

What happened this week:

  • The release workflow bumps the layer version in the docs (chore(ci): layer docs update) through a bot PR that does not run pre-commit. After 3.40.0 every reference with a layer ARN was one version behind, and every PR that updated its branch from develop started failing test_agent_skill_references for a change it did not make (fix(logger): empty or unparsable POWERTOOLS_DEV no longer crashes Logger #8783).
  • Four of the ten PRs in the 3.41.0 milestone touch docs and all four fail the same test, because the author did not run pre-commit or regenerated against an older develop. None of them knew the file existed.

That is a barrier for people fixing a sentence in the docs, and the fix is on our side.

What I want to change:

  1. Remove the test from the PR workflow. A docs PR changes docs, nothing else.
  2. Add a workflow on push to develop, filtered to docs/** and examples/**, that runs scripts/build_agent_skill_references.py and commits the result if anything changed. References catch up minutes after a merge, including the release bot's PR.
  3. Keep the pre-commit hook for those who have it installed; it just stops being required.
  4. Make the generator drop the layer ARN tables and the version number from the references. For an agent, one line pointing to the installation page is more useful than thirty ARNs that change every release, and it removes 300 lines of churn per release.

Until this lands I will push the regeneration commit on the affected PRs myself so nobody has to deal with it.

Activity

  1. added this to the 3.41.0 milestone on Nov 14, 2026
  2. powertools-for-aws-oss-automation commented on Nov 14, 2026

    @powertools-for-aws-oss-automation

    Warning

    This issue is now closed. Please be mindful that future comments are hard for our team to see.
    If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
    If you wish to keep having a conversation with other community members under this issue feel free to do so.

  3. github-actions commented on Nov 18, 2026

    @github-actions
    Contributor

    This is now released under 3.41.0 version!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

documentationImprovements or additions to documentationtech-debtTechnical Debt tasks

Type

No type

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions