[leandrodamascena]

Issue number: closes #8744

Summary

Changes

• .agents/skills/building-lambda-functions-with-powertools-python/SKILL.md: when to use the skill, the essential patterns (Logger/Tracer/Metrics on a handler, REST API with Event Handler, idempotent handler, partial batch failures, parameters and secrets, typed events and parsing), the rules from docs/adr that apply to people using the library, testing hints, and a table pointing to one reference per utility.
• references/: 27 files generated from the documentation pages by scripts/build_agent_skill_references.py. The generator resolves the --8<-- snippet includes so every example is inlined, flattens content tabs and admonitions into plain Markdown, drops the "Testing your code" and "FAQ" sections, and removes mkdocs-only syntax. tests/functional/test_agent_skill_references.py runs the generator in --check mode so the references cannot drift from the docs.
• No .claude/skills/ entry in this repository on purpose: the skill is for people using the library, and a contributor opening this repo with an agent should get AGENTS.md, not user-facing guidance. The skill says so in its description. Users get it through the plugin or npx skills add, which read .agents/skills/.
• The references are marked linguist-generated in .gitattributes (collapsed in GitHub diffs) and listed in a root .ignore so ripgrep and similar tools skip them; AGENTS.md says they are generated and that docs/ is the source.
• .claude-plugin/marketplace.json at the root and .agents/.claude-plugin/plugin.json, so claude plugin marketplace add aws-powertools/powertools-lambda-python and claude plugin install powertools-lambda-python@aws-powertools work from this repository.
• docs/getting-started/coding-agent-skills.md (in the nav after Installation) with the install steps for Claude Code, for agents following agentskills.io (npx skills add aws-powertools/powertools-lambda-python) and manually; one line in the README.
• .markdownlintignore excludes the generated references; .gitleaks.toml allowlists them, because sample event ids copied from the examples (an SQS SenderId) look like access keys to gitleaks.

Not in scope, as decided in the issue: nothing is bundled in the wheel or the Lambda layer, and no separate repository. The references add about 1.4 MB of Markdown to the repository, loaded by agents one utility at a time.

User experience

A user working with Claude Code, Codex, Cursor or Gemini CLI installs the skill once; from then on, when they ask for a Lambda handler with logging, idempotency, batch processing or API routing, the agent reads the current Powertools documentation and examples instead of relying on what it remembers, and follows the same rules we enforce in review.

Verification

• uv run python scripts/build_agent_skill_references.py --check passes, and a grep for leftover mkdocs syntax (--8<--, === ", !!!, ???, {target=, hl_lines) across the references returns nothing.
• tests/functional/test_agent_skill_references.py passes; ruff and mypy are clean on the generator and the test; pre-commit passes on every changed file.
• zensical build passes and the new page renders; markdownlint passes on SKILL.md, the docs page and the README.
• Both JSON manifests parse. I could not run claude plugin marketplace add against an unmerged branch, so the plugin install path is validated by structure (plugin root with skills/*/SKILL.md, as in the Pydantic skills marketplace), not by an end-to-end install; I'll do that once this is on develop.
• Written with an AI assistant; I ran everything above myself.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.00%. Comparing base (ec1bec2) to head (5886b18).
⚠️ Report is 2 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #8745   +/-   ##
========================================
  Coverage    97.00%   97.00%           
========================================
  Files          321      321           
  Lines        16415    16415           
  Branches      1482     1482           
========================================
  Hits         15924    15924           
  Misses         350      350           
  Partials       141      141           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.