Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view

Large diffs are not rendered by default.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

52 changes: 52 additions & 0 deletions .github/workflows/agent_skill_references.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
name: Regenerate agent skill references

# PROCESS
#
# 1. Runs on every push to develop that touches the docs, the examples or the generator
# 2. Regenerates .agents/skills/*/references from the docs
# 3. Opens a PR with the result when anything changed; duplicates with the same title are closed by the action
#
# This keeps contributors out of it: a docs PR changes docs, the references catch up after the merge.

on:
push:
branches:
- develop
paths:
- "docs/**"
- "examples/**"
- "scripts/build_agent_skill_references.py"
workflow_dispatch: {}

env:
TEMP_BRANCH_PREFIX: "ci-agent-skill"
PULL_REQUEST_TITLE: "chore(docs): regenerate the agent skill references"
FILES_TO_COMMIT: ".agents/skills/building-lambda-functions-with-powertools-python/references"

permissions:
contents: read

jobs:
regenerate:
if: github.repository == 'aws-powertools/powertools-lambda-python'
concurrency:
group: agent-skill-references
runs-on: ubuntu-latest
permissions:
contents: write # create temporary branch with the references
pull-requests: write # create PR
steps:
- name: Checkout repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
- name: Regenerate references
run: python3 scripts/build_agent_skill_references.py
- name: Create PR
id: create-pr
uses: ./.github/actions/create-pr
with:
files: ${{ env.FILES_TO_COMMIT }}
temp_branch_prefix: ${{ env.TEMP_BRANCH_PREFIX }}
pull_request_title: ${{ env.PULL_REQUEST_TITLE }}
github_token: ${{ secrets.GITHUB_TOKEN }}
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ make mypy # static typing, must pass
uv run pytest tests/unit tests/functional/<utility> # fast loop for one utility
make test # full unit + functional + performance, what CI runs
make pr # everything CI checks, run it before opening the PR
make agent-skill # regenerate .agents/skills/*/references after changing docs/ or examples/ (pre-commit does it too)
make agent-skill # optional: regenerate .agents/skills/*/references after changing docs/; pre-commit does it, and CI does it after merge
```

Do not run the full suite with `pytest -n auto`; collection differs between workers and it fails for reasons unrelated to your change.
Expand Down Expand Up @@ -58,6 +58,6 @@ Do not run the full suite with `pytest -n auto`; collection differs between work
| Sample events | `tests/events/` |
| Docs and examples | `docs/<area>/<utility>.md`, `examples/<utility>/src/` |
| Project premises | `docs/adr/` |
| Agent skill for library users | `.agents/skills/` (the `references/` folder is generated from `docs/`; do not edit it or use it as a source, change `docs/` and run `scripts/build_agent_skill_references.py`) |
| Agent skill for library users | `.agents/skills/` (the `references/` folder is generated from `docs/` by `scripts/build_agent_skill_references.py`, and regenerated by CI after every docs merge; do not edit it or use it as a source, change `docs/`) |
| Layer build | `layer_v3/` |
| Maintainer process | [MAINTAINERS.md](MAINTAINERS.md), [docs/maintainers.md](docs/maintainers.md) |
38 changes: 36 additions & 2 deletions scripts/build_agent_skill_references.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,11 @@
Each reference is a documentation page with the mkdocs-only syntax removed and the
``--8<--`` snippet includes resolved, so coding agents read the same content and the
same tested examples the website shows. Run without arguments to regenerate, or with
``--check`` to fail when the committed references are out of date (used by the tests).
``--check`` to report whether the committed references are out of date.
Contributors do not need to run this: the pre-commit hook regenerates on docs changes for
those who have it installed, and a workflow regenerates on every push to ``develop`` that
touches the docs, opening a PR with the result.
"""

from __future__ import annotations
Expand Down Expand Up @@ -61,6 +65,12 @@
ICON = re.compile(r":(?:material|octicons|fontawesome|simple)-[\w-]+:(?:\{[^}]*\})?")
HTML_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
ATTR_LIST = re.compile(r"^\{\s*\..*\}\s*$")
LAYER_ARN = re.compile(r"layer:AWSLambdaPowertoolsPythonV3-")
LAYER_ARN_VERSION = re.compile(r"(layer:AWSLambdaPowertoolsPythonV3-[A-Za-z0-9_{}-]+):\d+")
LAYER_ARN_NOTE = (
"Layer ARNs per region, runtime and architecture are listed on the installation page: "
f"{DOCS_URL}getting-started/install/. The version suffix changes with every release, so always copy it from there."
)


def resolve_includes(text: str) -> str:
Expand Down Expand Up @@ -125,6 +135,30 @@ def drop_sections(text: str) -> str:
return "\n".join(out) + "\n"


def strip_layer_arns(text: str) -> str:
"""Replace the per-region layer ARN tables with a pointer to the docs and mask the version suffix.
Thirty ARNs that change every release are churn, not knowledge; the version in the examples is
masked so an agent never hardcodes a stale one.
"""
out: list[str] = []
table: list[str] = []

def flush() -> None:
if table:
out.extend([LAYER_ARN_NOTE] if any(LAYER_ARN.search(row) for row in table) else table)
table.clear()

for line in text.splitlines():
if line.startswith("|"):
table.append(line)
continue
flush()
out.append(line)
flush()
return LAYER_ARN_VERSION.sub(r"\1:<version>", "\n".join(out) + "\n")


def clean(text: str) -> str:
text = FRONT_MATTER.sub("", text)
text = HTML_COMMENT.sub("", text)
Expand Down Expand Up @@ -154,7 +188,7 @@ def build_reference(name: str, pages: list[str]) -> str:
while previous != text:
previous, text = text, flatten_blocks(text)
text = drop_sections(text)
parts.append(clean(text))
parts.append(clean(strip_layer_arns(text)))
return "\n".join(parts)


Expand Down
22 changes: 0 additions & 22 deletions tests/functional/test_agent_skill_references.py

This file was deleted.

Loading