new-analyzer
Scaffold a new AWS service analyzer - src/aws_analyzer/<service>.py with the five-section layout, the shared helpers imported from _kit and its Analyzer and View built on _kit's base classes, a first
SKILL.md.claude/skills/new-analyzer/SKILL.md
GitHubNew analyzer
Request: $ARGUMENTS. The first word is the module name (snake_case, and a valid Python identifier, because
users will import it). The rest, if given, says what users need from it.
A new analyzer is a new module of the package with the same shape as src/aws_analyzer/s3.py and
src/aws_analyzer/dynamodb.py.
Read CLAUDE.md's "Hard constraints" and "Architecture of an analyzer file" first. Everything below follows them.
dynamodb.py is the smallest analyzer, so model the new one on it; bedrock_kb.py and its tests show how to test a service moto doesn't cover (botocore Stubber on injected clients).
1. Research the service (before writing code)
Clients and read-only operations. List the operations of each boto3 client the analyzer will use. For Knowledge Bases these are
bedrock-agent(configuration) andbedrock-agent-runtime(retrieval):.venv/bin/python -c "import botocore.session as s; m = s.get_session().get_service_model('bedrock-agent'); print(sorted(m.operation_names))"Only Get / List / Describe / Head / Search / Retrieve style calls. Nothing that writes, starts a job or ingests data.
moto support. Look for the client in
.venv/bin/python -c "from moto.backend_index import backend_url_patterns as b; print([n for n, _ in b])". Where moto doesn't cover a client or an operation, the tests usebotocore.stub.Stubberormonkeypatchinstead. Say which in the plan.Costs. Work out what the service bills that users would want estimated. That becomes a
<SERVICE>_PRICEStable of us-east-1 list prices, and callers can override it withprices=.IAM. List the permission each operation needs.
2. Agree on the first commands
Propose three to five View commands and confirm them with the user before building. The one-argument call of the first command has to be useful. A typical set:
- an overview of everything in the region, with the warnings, like
tables()/overview() - a detail report for one resource, with findings and the call to copy for the next step, like
table_info()/bucket_info() - one or two commands that look at the data itself (for Knowledge Bases: data sources and sync status, and a test retrieval that shows the chunks returned with their scores and sources)
For each command, give its name, what the user decides from it, its cards, and its findings.
3. Create src/aws_analyzer/<service>.py
Pick the names first:
- the classes:
<Service>Analyzer/<Service>View(for exampleBedrockKBAnalyzer/BedrockKBView) - a short CSS root class, the file's
_ROOT(taken:s3a,ddb,kba,kbc,smk,osv,lmb) - the price table:
<SERVICE>_PRICES
Then build the file:
- Module docstring. Same shape as the others: what it is, "Part of aws-analyzer:
pip install aws-analyzer, thenfrom aws_analyzer import <Service>View", the requirements, the two layers, and a quick start that shows the commands. - Imports.
from __future__ import annotations, then only the stdlib,boto3,botocoreand the package's own_kitat the top (never another analyzer). Anything optional is imported inside functions through_require. - The five banners, exactly in this form:
# 1. Helpers: ...,# 2. Data models (what <Service>Analyzer returns),# 3. Pure analysis (no AWS calls - ...),# 4. <Service>Analyzer - pure logic layer ...,# 5. <Service>View - notebook UI layer ..., each between# ===...lines. - Shared helpers. Import what's in
src/aws_analyzer/_kit/(human_size,_plural,_require,_esc,_why,_Hint, the render blocks_Title,_Cards,_Table, ... and_call,_signature,_render_text,_report_html,_base_css, ...) the waydynamodb.pydoes, only the names the file uses: never copy them,rules.pyfails on a copy. At the start of section 5, set the service's look the waydynamodb.pydoes:_ROOT,_CSS = _base_css(_ROOT)(or_base_css(_ROOT, _EXTRA_CSS)with the rules for its own blocks, each starting with.<root>),_BADGE, and_render_html(blocks, max_rows)calling_report_htmlwith the three. A block type of its own registers how it's drawn with@_draws(_Block, "html")and@_draws(_Block, "text")(CLAUDE.md, "How the View layer works"). Nothing else is copied: the analyzer and the View get the rest from their base classes (steps 5 and 6). - The analyzer. Subclass
_BaseAnalyzer(from ._kit.analyzer import _BaseAnalyzer) and set_LIST_PRICES = <SERVICE>_PRICES. The constructor matches the others:(session=None, *, region=None, profile=None, client=None, prices=None), and starts withsuper().__init__(session, region=region, profile=profile, prices=prices), which setsself.session, the clients' retry settingsself._configandself.prices. Clients are made lazily, each with the service name spelled out (self.session.client("<service>", config=self._config), sorules.pysees its calls), and a missing region turns into a readableValueError(seeDynamoDBAnalyzer.client). The base'sregion,_paginate,_map(setself.max_workers) and_cached_client(setself._clientsandself._lock) are there to use. Record config sections the caller can't read inerrors. Long reads takelimit=andprogress=. - The View. Subclass
_BaseView(from ._kit.view import _BaseView, _friendly_errors):__init__(core=None, *, mode="auto", max_rows=50, progress="auto")callssuper().__init__(mode=mode, max_rows=max_rows, progress=progress)and then setsself.core: <Service>Analyzer = core or <Service>Analyzer(). The class sets_render_html = staticmethod(_render_html),_GROUPS(commands by task, for help()) and_START(the first two or three calls to try);_show,_progress,help()and_price_basiscome from the base. Every command is decorated with@_friendly_errors, and its docstring's first paragraph is its help() text. Give the View an_explain(code, message)that says what the service's common AWS errors mean and what to do (a not-found names the command that lists what exists; seeLambdaView._explain). Set the file's_BADGE(the chip before each report title) and CSS root class.
Build each command the way /add-command does: the data model, then the pure function and its findings, then
the analyzer method, then the View method.
A window to click through (an explorer, like KBExplorer or LambdaExplorer) comes later, if at all, and is built
on src/aws_analyzer/_kit/window.py (CLAUDE.md, "The windows' kit"): subclass _Explorer (call its __init__
first, set _PREFIX, _THREADS and _reword, build with _tab_bar and _frame, read AWS with _later), make its
fields _Pickers and its lines _row_buttons, and guard its commands with @_window_errors. Take what it shares
with the other windows from there, never from another window's file.
4. Tests: tests/test_<service>.py
Use the same layout as tests/test_dynamodb.py: # ---- helpers (pure functions), # ---- AWS (moto) with
an aws fixture around mock_aws() plus seeded fixtures, and # ---- UI with ui in mode="text" and the
run(capsys, fn, ...) helper. Cover at least one failure path that shows a note instead of a traceback.
tests/conftest.py already puts src/ on sys.path (tests import from aws_analyzer import <service>) and sets
fake credentials. If moto supports the
service, add its extra to the moto[...] line in requirements-dev.txt and pip install -r requirements-dev.txt.
CI needs no changes: it lints, imports and tests every src/aws_analyzer/*.py. Check that the loop in
.github/workflows/ci.yml still globs.
The PyPI package ships every module in src/aws_analyzer/; wire the new one into src/aws_analyzer/__init__.py:
its name in _MODULES (tests/test_package.py fails without it), and the Analyzer and View classes in __all__,
_EXPORTS and the TYPE_CHECKING imports. If the service's API is newer than the boto3>= floor in pyproject.toml, raise the floor
to the first boto3 release that has every operation the file calls, and put any new optional package in an extra.
5. Docs
README.md:- Add a row to the "Services" table (what it shows you, the file and its guide) and a link to the new section in the links under the title.
- Add a
## <Service>section with the same parts as the DynamoDB one: a one-line intro with the file and guide, a screenshot, quick start, the commands tables (one per_GROUPSgroup), and under "Reference" the folded "Getting the data", cost notes, and IAM permissions. - Update the Development paragraph if it names the guides.
docs/<service>.md: a new guide. Copydocs/dynamodb.md's structure (front matter, hero, headings with explicit ids, figures, callouts, troubleshooting entries, therefcommand table), and cover set up in SageMaker, a five-minute tour, a section per area, using the data in Python, cost, permissions, troubleshooting and a command reference. Leave out screenshots you can't make yet (see/demo --html).docs/images/aws/<service>.svg: the service's 64 px icon from AWS's Architecture Icons package (https://aws.amazon.com/architecture/icons/), unchanged; the home page's line, the guide's eyebrow and README's Services table and section show it.docs/index.md: add a line for the new guide to the.svclist (its icon, name, module and two or three questions a data scientist would ask that it answers), and add the guide tonavinmkdocs.yml. Check it withmkdocs build --strict(pip install -r requirements-docs.txt).CHANGELOG.md: a bullet under## [Unreleased]→### Addednaming the service, its file and View, and its first commands.CLAUDE.md: update the list of analyzers, the price tables, the moto extras (or the Stubber note, as for Bedrock) and anything service-specific a future session needs.
6. Demo data and verification
- Add
seed_<service>()and an entry inSEEDERSin.claude/skills/demo/demo.py, if moto supports the service. - Run
/check.rules.pymust report 0 errors, and every IAM warning is fixed in the README. - Run
/demo <service>on each command and read the output against the product rules.
Report the files created, the commands with their help() lines, a demo excerpt, the IAM permissions, and what is still missing (screenshots, commands left for later). Don't commit unless asked.