cap-mtx-scaffold

cap-mtx-scaffold

An AI agent skill for SAP CAP multitenancy scaffolding. cap-mtx-scaffold is a markdown instruction file that AI coding agents — Claude Code, GitHub Copilot, OpenCode, and any other tool that follows the emerging agents-spec skill convention — load automatically when you're setting up multitenancy in a CAP project, encoding a detect-first, execute-second scaffolding practice so every developer gets a consistent, correct local setup without having to remember the exact cds-dk incantations themselves.

It scaffolds the same way a careful developer would do it by hand — by running the real cds init/cds add commands — after first looking at what's actually installed and declared in your project. It never guesses a package version, never quietly upgrades a dependency, and never migrates you off a legacy toolkit without asking.

That distinction matters because multitenancy setup differs materially between the current @sap/cds-mtxs toolkit and the deprecated @sap/cds-mtx one, and an AI agent that hardcodes versions from its training data — or falls back to whatever cds-dk happens to be globally installed — can silently scaffold a project against the wrong toolchain. This skill exists to close that gap: detect first, then execute, using exactly what the project (or the user, for a new project) declares.

Quickstart

Skills are plain files an agent loads from a well-known folder — no build step, no install, just a file in the right place. Clone this repository once, then copy or symlink the skill into whichever agent(s) you use:

# 1. Clone this repository
git clone <this-repository-url>

# 2. Symlink the skill into your agent's skills folder (repeat per agent you use;
#    a symlink keeps it updatable with `git pull`, unlike a plain copy)
mkdir -p ~/.claude/skills
ln -s "$(pwd)/cap-mtx-scaffold/skills/cap-mtx-scaffold" ~/.claude/skills/cap-mtx-scaffold

Then, in any CAP project — existing or brand new — just ask naturally:

"set up multitenancy for this CAP project"
"scaffold a new multitenant CAP app"

Your agent loads SKILL.md automatically when the request matches, detects your environment first, and only then scaffolds.

Requirements: Node.js + npm, @sap/cds-dk (global install or resolvable via npx), git, and a bash-capable shell (Git Bash on Windows, any POSIX shell on macOS/Linux).

What It Does

The skill runs scripts/detect-env.sh first, then picks one of three flows based on what it finds — never the other way around:

1. Greenfield — no existing CAP project. Asks which @sap/cds major version to target (defaulting to the most recent version available on the machine, never invented) and runs cds init + cds add multitenancy + cds add <db-kind>.
2. Existing project, current @sap/cds-mtxs — reads the versions already declared in package.json and pins every cds-dk invocation to exactly those versions via npx --package=@sap/cds-dk@<version>. It never suggests, and cannot silently fall into, an upgrade.
3. Existing project, legacy @sap/cds-mtx (or a mix of legacy and current) — warns explicitly and stops for a decision, offering only two options: generate code compatible with the existing legacy setup, or point to SAP's official migration guide. It never migrates automatically, and never touches the project's existing multitenancy wiring.

Out of Scope

This skill only performs local scaffolding. It does not handle:

• Deployment to Cloud Foundry or Kyma (mta.yaml, manifest.yml, Helm charts)
• XSUAA/IAS configuration or any other BTP service binding
• SaaS Registry / subscription flow to real BTP tenants
• Automatic migration from legacy @sap/cds-mtx to @sap/cds-mtxs

Relationship to Other Skills

cap-mtx-scaffold focuses exclusively on the executable scaffolding step: detecting a project's CAP/multitenancy setup and running the official cds init/cds add commands to produce a working local project. It deliberately does not teach multitenancy concepts — for that, it complements skills such as multitenancy (by Daniel Krompaß) in the SAP AI Skills Library catalog, which covers MTX sidecar architecture, xs-security.json, tenant lifecycle hooks, Service Manager, and production deployment concerns conceptually, without running any commands itself.

In short: reach for cap-mtx-scaffold to get a multitenant CAP project running locally with cds watch; reach for multitenancy to understand the production concepts, security model, and deployment path that this skill deliberately leaves out of scope.

Testing

There is no automated test harness — verification is manual, by running the skill against fixture projects in a temporary directory outside this repo and checking the generated output and the agent's responses. See CLAUDE.md for the test scenarios and pass criteria.

Contributing

Contributions are welcome under the Apache License 2.0 (see LICENSE). If you intend to submit this skill to the SAP AI Skills Library catalog, note that it requires a Developer Certificate of Origin (DCO) sign-off and review via a "Register a New Skill" issue in SAP/ai-skills-library.

References

• CAP documentation (capire)
• SAP AI Skills Library

License

Apache License 2.0 — Copyright (c) 2026 Fernando Meregali Xavier

See LICENSE for the full text. Free to use, fork, and contribute.