agentleFS
Sign inStart free
williamcorrea23williamcorrea23/sap-router-skill/.agents/skills/cap-upgrade/SKILL.md

cap-upgrade

Skill1 starsChanged 4 months agoMITView on GitHub

Upgrade a CAP project to the latest CDS version. Drives the `cds upgrade` CLI for CDS 10+ (pattern detection, false-positive filtering, fix categorisation) and handles manual upgrades for earlier versions (major jumps like 7→8, 8→9 as well as minor/patch updates). Use when a developer needs to upgrade CDS in a CAP project, already has a `cds upgrade` report, or wants to move to a newer CDS version.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before starting any workflow, detect the current CDS major version:

    line 56
  2. Very specific:

    Run cds upgrade --fix from scratch:

    line 75
  3. Very specific:

    Run cds upgrade --fix (Step 1) – upgrades dependencies AND scans

    line 78
  4. Distinctive:

    Read and interpret output (Steps 2–5)

    line 79
  5. Very specific:

    Detection: Check if UPGRADE_REPORT.md or findings.json exists in the project root.

    line 91
  6. Very specific:

    Run cds upgrade to scan for remaining migration items.

    line 105
  7. Distinctive:

    Do not load both: Only the file matching the detected scenario is relevant.

    line 133
  8. Distinctive:

    After loading, follow that file's instructions from the beginning.

    line 134

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

What I do

I drive the cds upgrade CLI, interpret its findings, and walk the developer through each migration item with concrete fix instructions and links to the official CAP migration documentation on capire.

What cds upgrade does

cds upgrade is a deterministic command-line tool shipped with @sap/cds-dk. It is the foundation this skill works on top of.

With --fix it:

  • Updates CDS-related dependencies in package.json to the target version
  • Runs npm install
  • Rebuilds the project with the new compiler
  • Sets compatibility flags that preserve previous behaviour where applicable

Without flags it scans only — no changes to project sources or dependencies (the report files below are still written).

With --dry nothing is written to disk at all — all output goes to stdout.

In every mode it scans the project for breaking-change patterns and produces:

  • findings.json — structured per-rule matches with file positions, guidance, severity, compat flags, OpenRewrite recipes, and coverage signals
  • UPGRADE_REPORT.md — human-readable report grouping findings by scope
  • UPGRADE_OVERVIEW.md — short summary with scan numbers and quick wins

What this skill adds

The CLI's outputs are dense — many rules, many matches per rule, many of which may be false positives in any given codebase. This skill:

  • Filters false positives using per-rule guidance and generic FP rules
  • Reads source files to verify ambiguous matches
  • Searches for occurrences the patterns may have missed
  • Categorises each finding by fix type (deterministic, OpenRewrite, manual)
  • Offers to apply deterministic fixes directly

Version routing

Before starting any workflow, detect the current CDS major version:

cds version

Parse the @sap/cds line (e.g. @sap/cds: 9.8.0). Extract the major number.

Current majorTargetWorkflow
< 9Ask the developer: "What target version? (9 or 10)"If target < 10 → Manual upgrade path (appendix). If target = 10 → multi-major: upgrade to 9 first (manual path), then run cds upgrade for 9→10.
910 (default)Main workflow (Steps 0–6 below)
1010 (re-check)Mode C (see Trigger modes below)

Trigger modes

Mode A – Fresh run

The developer asks to upgrade (e.g. "migrate my project", "run cds upgrade"). Run cds upgrade --fix from scratch:

  1. Verify preconditions (Step 0)
  2. Run cds upgrade --fix (Step 1) – upgrades dependencies AND scans
  3. Read and interpret output (Steps 2–5)
  4. Apply manual fixes, review compat flags (Step 6)

Mode B – Existing report

The developer already ran cds upgrade and has UPGRADE_REPORT.md and/or findings.json in the project root. This is the common case when:

  • The developer ran the tool first and now wants help interpreting findings
  • A teammate, IDE integration, or CI job produced the report
  • A previous session ended after Step 1 and is being resumed

Detection: Check if UPGRADE_REPORT.md or findings.json exists in the project root. If present, check whether any source file tracked by the project has been modified after .cdsupgrade.json was written. If no relevant changes occurred, reuse the existing report. Otherwise, suggest re-running cds upgrade.

Skip to Step 2 (Read the report).

Mode C – Already on target (re-check)

The project already upgraded to CDS 10 but may have:

  • Unresolved findings from a previous run
  • Compat flags set by --fix that should eventually be removed
  • New migration rules added in a cds-dk patch

Run cds upgrade to scan for remaining migration items. If UPGRADE_REPORT.md or findings.json already exist and are recent (Mode B detection applies), skip directly to Step 2.

Out of scope

This skill assumes a developer-type environment where cds upgrade can run (globally installed cds-dk with upgrade support, or via npx @sap/cds-dk@latest) and agent capabilities are present. It does not cover:

  • NO-AI mode – if the developer runs cds upgrade without an AI agent, UPGRADE_REPORT.md is the human deliverable. The skill is unnecessary.
  • CI / headless – findings.json can be consumed by a custom pipeline (e.g. SARIF conversion for IDE Problems Panel). The skill is invoked only when an agent walks a developer through findings interactively.

Load the relevant workflow

Based on the version routing above, load exactly one of the following files from this skill's directory and follow its instructions:

ScenarioFile to load
Mode A, B, or C (target is CDS 10, or already on 10)workflow-cds10.md
Manual upgrade path (target < 10, or first leg of multi-major)manual-upgrade.md

Do not load both. Only the file matching the detected scenario is relevant. After loading, follow that file's instructions from the beginning.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free