remove-deprecated-api
/remove-deprecated-api
AEM Cloud Service expert skill — migrate deprecated and removed Java APIs to comply with AEM as a Cloud Service enforcement policies. Detection is **plugin-driven, not table-driven**: the skill runs the AEM Analyser Maven Plugin (`com.adobe.aem:aemanalyser-maven-plugin`) at its latest published version against the project and parses the `region-deprecated-api` output — the same data Cloud Manager's pipeline uses. Each finding carries the plugin's own deprecation hint (typically a successor package parsed from the analyser message), which drives the fix. Use when auditing deprecated APIs, fixin
Assessment and security
- Files in this package
- 4
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/detect.sh
What it does and when to use it
AEM Cloud Service expert skill — migrate deprecated and removed Java APIs to comply with AEM as a Cloud Service enforcement policies. Detection is **plugin-driven, not table-driven**: the skill runs the AEM Analyser Maven Plugin (`com.adobe.aem:aemanalyser-maven-plugin`) at its latest published version against the project and parses the `region-deprecated-api` output — the same data Cloud Manager's pipeline uses. Each finding carries the plugin's own deprecation hint (typically a successor package parsed from the analyser message), which drives the fix. Use when auditing deprecated APIs, fixin
Triggers from the description
Original author description
AEM Cloud Service expert skill — migrate deprecated and removed Java APIs to comply with AEM as a Cloud Service enforcement policies. Detection is **plugin-driven, not table-driven**: the skill runs the AEM Analyser Maven Plugin (`com.adobe.aem:aemanalyser-maven-plugin`) at its latest published version against the project and parses the `region-deprecated-api` output — the same data Cloud Manager's pipeline uses. Each finding carries the plugin's own deprecation hint (typically a successor package parsed from the analyser message), which drives the fix. Use when auditing deprecated APIs, fixin
How it works
- Overview
- Classification — confirm this pattern applies
- Discovery — two-phase
- Resolution contract
- Review checklist
- Troubleshooting fingerprints
- Recipe pointer
SKILL.md preview
---
name: remove-deprecated-api
description: |
AEM Cloud Service expert skill — migrate deprecated and removed Java APIs to
comply with AEM as a Cloud Service enforcement policies. Detection is **plugin-driven,
not table-driven**: the skill runs the AEM Analyser Maven Plugin
(`com.adobe.aem:aemanalyser-maven-plugin`) at its latest published version against the
project and parses the `region-deprecated-api` output — the same data Cloud Manager's
pipeline uses. Each finding carries the plugin's own deprecation hint (typically a
successor package parsed from the analyser message), which drives the fix. Use when
auditing deprecated APIs, fixing Cloud Manager pipeline failures citing
`region-deprecated-api` / `api-regions-check` / `Import-Package not satisfied`, or
proactively modernizing AEM projects before enforcement deadlines.
license: Apache-2.0
---
# Remove Deprecated API — AEM as a Cloud Service
> This pattern is executed by the code-assessment runbook — follow
> [`../references/runbook.md`](../references/runbook.md) for the outer flow (preflight →
> plan → apply → verify, run log). This skill supplies the plugin-driven detection and
> the hint-driven fix recipe the runbook applies.
## Overview
Adobe curates the list of deprecated / removed AEM APIs inside the AEM SDK's
`api-regions` metadata; Cloud Manager's `region-deprecated-api` analyser task consumes
that JSON at build time. The **AEM Analyser Maven Plugin**
(`com.adobe.aem:aemanalyser-maven-plugin`) runs the same task locally against the
project's built bundles. This skill uses the plugin as its detection engine — no
curated tables, no static lists, no drift.
For each deprecated package the plugin reports, its log line contains a **hint**: the
`deprecated.msg` field from the SDK metadata, which typically names a successor
package (e.g. *"Please use `org.apache.sling.xss` instead"*). Fixes are derived from
that hint at plan time. When the hint names no successor, the recipe consults the
Adobe **Experience League** API-removal guidance as a documented fallback.
## Classification — confirm this pattern applies
- Any `*.java`, `pom.xml`, or OSGi config file the AEM Analyser Maven Plugin reports
under `region-deprecated-api` (i.e. any `Usage of deprecated ... found` log line
produced by `mvn verify` against the project).
- Cloud Manager code-quality pipeline failures citing `region-deprecated-api`,
`api-regions-check`, `Import-Package not satisfied`, or `bundle-unversioned-packages`
violations.
The plugin only reports **past-due** deprecations by default (entries whose
`for-removal` date has already elapsed). Future-dated deprecations are not touched;
re-running the skill after each removal date passes picks them up automatically — the
list is live.
## Discovery — two-phase
The detector lives in the shared Java analyzer (`scripts/analyzer/detectors/RemoveDeprecatedApi.java`),
same shape as every other pattern's detector — but its rules are **loaded at run time**
from a preflight-produced cache, not hardcoded.
### Phase 1 — preflight (populates the rules cache)
```bash
bash plugins/aem/cloud-service/skills/code-assessment/remove-deprecated-api/scripts/detect.sh <project-root>
```
`detect.sh`:
1. Resolves the latest `com.adobe.aem:aemanalyser-maven-plugin` and the latest
`com.adobe.aem:aem-sdk-api` releases from Maven Central (`maven-metadata.xml`); each
can be pinned with `--pin-plugin <version>` / `--pin-sdk <version>`. The freshest
SDK is used by default because Cloud Manager itself runs the analyser against the
latest SDK — matching that behaviour surfaces every deprecation the pipeline will
flag. If the project's `pom.xml` pins an older SDK via `<sdkVersion>X.Y.Z</sdkVersion>`
or `<useDependencyVersions>true</useDependencyVersions>` inside the analyser plugin
config, `detect.sh` overrides at the CLI (`-DsdkVersion=<latest>` and
`-DsdkUseDependency=false`) so the fresh set is used just for the preflight — no
pom edit. Pass `--respect-pom-sdk` to honour the pom's pin instead.
2. Invokes the analyser by its fully-qualified
`com.adobe.aem:aemanalyser-maven-plugin:<version>:project-analyse` coordinates, so the
resolved version runs whether or not the project declares the plugin — **the pom is
never modified** (no patch, no backup, no restore). Command shape:
`mvn package com.adobe.aem:aemanalyser-maven-plugin:<version>:project-analyse …` — the
`package` phase (override with `--goal`) builds the module artifacts that
`project-analyse` inspects. Log path: `/tmp/aem-analyser.log` (override with `--log <path>`).
3. Parses `Usage of deprecated package found : <pkg> : <hint> Deprecated since <since> For removal : <date>`
and `Usage of deprecated library found : <lib>, package(s) : <start>...<end> : <hint>` lines.
4. **Writes the rules cache TSV** — `<package>\t<hint>\t<for_removal>` per line — at
`$AEM_DEPRECATED_API_RULES` (env override) or
`$TMPDIR/aem-code-assessment/deprecated-api-rules.tsv` (default).
5. Emits a JSON summary on stdout (findings + meta) for callers that don't chain
through `analyze.sh`.
### Phase 2 — analyzer (consumes the cache, emits findings)
```bash
bash plugins/aem/cloud-service/skills/code-assessment/scripts/analyze.sh <workspace-root>
```
The Java `RemoveDeprecatedApi` detector reads the rules TSV, matches each rule's
package against every `import` in the corpus (longest-prefix match), applies today's
past-due gating as a defence-in-depth, and emits findings in the standard
`{pattern,file,line,snippet}` shape with an added `hint` field carrying the analyser
message.
**Findings shape** — the standard runbook shape plus an optional `hint`:
```json
{
"findings": [
{
"pattern": "remove-deprecated-api",
"file": "core/src/main/java/com/example/MyService.java",
"line": 5,
"snippet": "org.apache.log4j.Logger",
"hint": "The log4j 1.x libraries are deprecated. Please use org.slf4j instead."
}
],
"warnings": []
}
```
**If the cache is missing** — `detect.sh` was not run, or was run offline and failed —
the detector emits a single warning:
```
deprecated-api-rules-missing: expected TSV at <path> — run remove-deprecated-api/scripts/detect.sh preflight first
```
and produces no findings for this pattern. Other detectors continue unaffected.
Scope: workspace roots only. Exclude `code-assessment/` skill files.
## Resolution contract
**`hint-driven`** — every fix derives from the analyser's `hint` field for that finding.
The recipe (`recipe.md` Step 3) parses the hint for a successor-package phrase
(*"Please use X instead"*, *"Use X instead"*, *"X should be used"*) and applies the
edit. When the hint names no successor, the recipe falls back to Adobe Experience
League's API-removal guidance page via `WebFetch`.
**Verification** — before applying, the successor must be resolvable on the project's
classpath. If it is not, either add the required Maven dependency (with user consent)
or record the finding as manual-action-required.
**Manual-only items** (cannot be auto-fixed; document in report, do not attempt edits):
- Deep integration cases where hint says "not supported in AEM as a Cloud Service"
with no successor named on Experience League (e.g. `org.apache.felix.webconsole`,
parts of `com.drew`).
- Guava usage beyond simple `Lists.newArrayList()` / `ImmutableList.of()` — caching,
event bus, complex data structures — where replacement requires design decisions.
- Reflection or dynamic loading against the deprecated type — the scanner cannot see
it and the fix is not mechanical.
## Review checklist
- [ ] Latest `aemanalyser-maven-plugin` resolved from Maven Central
- [ ] Initial build passed before any transformations (`mvn compile`)
- [ ] Analyser log parsed; findings carry a non-empty `hint` where the SDK provides one
- [ ] Each finding's successor package (from hint or Experience League) verified on the
classpath before applying
- [ ] Step 3 edits applied surgically (imports rewritten, deps updated, OSGi configs
deleted where the plugin reports them as unmodifiable)
- [ ] Post-edit build checked; residual compilation errors routed to AI-fix phase
- [ ] Each AI-assisted fix marked with `// Fixed by AEM Modernizer AI` above the change
- [ ] Final build passes and the analyser — re-invoked via the fully-qualified
`project-analyse` goal — now reports zero past-due deprecations
- [ ] Manual-action items documented in the report
## Troubleshooting fingerprints
| Symptom | Likely cause | Action |
|---|---|---|
| `detect.sh` fails at plugin resolution step | Plugin not in local Maven cache | Pass `--pin-plugin <version>` with a locally available version |
| The build fails before the analyser goal runs | Baseline compile failure in the `package` phase | Fix the baseline build first (per runbook), then re-run detection |
| Hint is empty for a finding | SDK deprecation message is descriptive only, or the finding came from `library` grouping without a msg | Consult Experience League for the successor; if still absent, record as manual-only |
| `Import-Package not satisfied` on rerun | Successor package not on the module's classpath | Add the required Maven dependency (with user consent) or pick a JDK stdlib alternative |
| Analyser reports a package with no `import` match in-workspace | Deprecated API pulled in transitively by a third-party bundle | Cannot fix in customer code; report as third-party dependency upgrade needed |
## Recipe pointer
Read [`recipe.md`](recipe.md) fully before applying. The recipe covers the plugin
setup + preflight scan, the hint parsing rules, the Experience League fallback flow,
the AI-fix loop for compilation errors introduced by rewrites, and the report format.
Files in this package (4)
- README.md 2 KB
- SKILL.md 10 KB
- recipe.md 26 KB
- scripts/detect.sh 14 KB
Versions
The database has no other skills named remove-deprecated-api.
Database snapshot: 13.11.2026 · package version d5c06147308d (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100workflow-model-design
Design and create AEM Workflow models on AEM as a Cloud Service. Use when creating workflow models via the Workflow Model Editor or content package XML, defining step types (PROCESS, PARTICIPANT, DYNAMIC_PARTICIPANT, OR_SPLIT, AND_SPLIT), configuring step properties, declaring… - 100outdated-dependencies
AEM Cloud Service expert skill — upgrade outdated Maven dependencies in pom.xml, both literal <version> and same-pom ${property} shapes. Use for \"update my aem-sdk-api\", \"upgrade mockito\", or scanning a project for stale dependency versions. Discovery can find <dependency>… - 100aem-component
Find all source files, AEM pages and dialog fields for an AEM component. Use for 'where is component X?', 'what files for hero?', 'find component'. - 100xwiki-fix-deprecation
Replace every call to a deprecated XWiki Java API with its replacement across xwiki-commons, xwiki-rendering and xwiki-platform — Java code and tests, but also Velocity templates, wiki pages (XAR), Groovy and JavaScript — then, once nothing calls it any more, retire the API to… - 100aem-fe-verify
Visually verify a component's rendering on local AEM (wcmmode=disabled) against Figma or requirements, fixing gaps in a loop. Use for 'verify frontend', 'visual verify', 'compare AEM with figma'. Not for dialog checks (aem-verify) or full story QA (aem-qa). - 95research-deprecation-usage
Audits how often deprecated CDS exports are actively used in customer codebases using Sourcegraph MCP search tools. Use this skill whenever asked to assess removal readiness for deprecated CDS APIs, investigate the blast radius of removing a deprecated component or hook, check…