cap-developer

What I do

Provide correct, lean, idiomatic guidance for CAP development — from project setup and CDS modeling through declarative annotations and programmatic event handlers.

This SKILL.md is a router. Each topic lives in its own reference file so it can be loaded and cross-referenced on its own. Read only the file(s) the task needs.

Reference map

Topic	File	Load when
Domain model + service projections	`references/cds-modeling.md`	Modeling entities/aspects/associations, or exposing them via projections
Declarative annotations (validation, constraints, auth)	`references/declarative.md`	Adding validation, mandatory/readonly/computed values, `@restrict` / `@requires`
Custom event handlers	`references/custom-logic.md`	Only when annotations can't express the rule; before/on/after logic
Sample / seed data	`references/sample-data.md`	Generating test data with the CLI
Node.js runtime specifics	`references/nodejs.md`	The project is a CAP Node.js app
Java runtime specifics	`references/java.md`	The project is a CAP Java app

Runtime Choice

When in a new project, use the globally installed

@sap/cds-dk

(cli:

cds

). Defer the language choice until necessary. This choice is only necessary once code is added or the app is deployed.

When only working with cds models, you can simply start with

cds w

without needing to define a runtime.

Documentation source

Before guessing at APIs or annotations — and before changing an existing project's model — consult authoritative CAP documentation. Use whichever source is available; never guess URLs or invent APIs:

CAP MCP server (preferred when present). Use it to:
- Search CAP documentation before guessing at APIs or annotations
- Read the effective CDS model of an existing project before adding or changing anything
capire LLM docs (fallback when no MCP server is configured). The official docs expose LLM-friendly entry points — use these instead of ad-hoc web searches:
- ```
https://cap.cloud.sap/docs/llms.txt
```
  — a curated index of every documentation page; start here to locate the right topic.
- ```
https://cap.cloud.sap/docs/llms-full.txt
```
  — the full documentation concatenated into one file, for when you need the complete text.
- ```
https://cap.cloud.sap/docs/sitemap.md
```
  — the semantic sitemap of all pages.
- Any page is available as markdown by appending
```
.md
```
  to its URL (e.g.
```
https://cap.cloud.sap/docs/get-started/bookshop.md
```
  ) or by sending an
```
Accept: text/markdown
```
  header. Follow links from
```
llms.txt
```
  /
```
sitemap.md
```
  to the exact page rather than guessing a path.
- Inspect the effective CDS model without the MCP server via
```
cds compile <path>
```
  (e.g.
```
cds compile srv --to edmx
```
  ).

Never use CAP docs as a Fiori/SAPUI5 reference. They contain useful information about how CAP integrates with Fiori/SAPUI5 but are not a complete reference for those frameworks.

Caveat on release notes and version tables: documentation sourced from release notes or version recommendation tables may be outdated — they reflect what was true at the time of that release, not necessarily today. Always cross-check version-specific claims (e.g. "recommended Node.js version") against live sources like

cds version

npm view

, or the current Getting Started page rather than trusting a snapshot from a past release note.

Project setup rules

Start a new project with:

cds init <name>        # creates a subdirectory; omit <name> to init in cwd
cd <name>
cds watch              # start the dev loop (works without a runtime for pure modeling)

When the runtime is known upfront, pass

--java

--nodejs

cds init

(see the runtime-specific reference files for details).

Never run
```
cds add sample
```
— it scaffolds a full demo app into the project.
Use
```
cds add tiny-sample
```
only if the user explicitly wants a minimal starter model.
Use
```
cds add <feature>
```
(e.g.
```
hana
```
,
```
xsuaa
```
,
```
approuter
```
,
```
mta
```
) to add features incrementally and only when needed (e.g. when deployment is requested).

Working order

Model the domain →
```
references/cds-modeling.md
```
Expose services via projections →
```
references/cds-modeling.md
```
Add constraints declaratively first →
```
references/declarative.md
```
Write handlers only where annotations fall short →
```
references/custom-logic.md
```
(+ the runtime file
```
references/nodejs.md
```
or
```
references/java.md
```
)
Generate sample data →
```
references/sample-data.md
```

Don't

Write handlers for things the generic service provider already handles
Hardcode tenant IDs, system IDs, or credentials anywhere
Put user-facing strings inline — use
```
_i18n/
```
bundles
Run
```
cds add sample
```

Runtime-specific don'ts (e.g.

await

inside

cds.on('served', ...)

in Node) live in the respective reference file.