AI coding agents already know CAP. They can generate CDS models, write service handlers, and wire up deployments without much hand-holding. But “knows the framework” and “follows current best practices reliably” are different things. Models default to patterns they saw most often in training — which may be outdated, subtly wrong, or simply not the way your team does things.
Skills are how you close that gap. They're lightweight, on-demand instruction sets that reinforce best practices, teach post-cutoff features, and establish tested workflows for complex tasks. This post describes a skills workspace pattern we built for SAP's Cloud Application Programming Model (CAP). The architecture is framework-agnostic — you could apply it to any domain where you want to fine-tune what an agent already knows.
The Problem
CAP is a full-stack framework for building enterprise applications on SAP BTP. It uses CDS as its modeling language, runs on Node.js or Java, and provides declarative patterns for authorization, multitenancy, messaging, and more. Modern LLMs already know CAP well — it's well-represented in training data, and agents can produce working CDS models, service handlers, and deployment configs out of the box.
So why bother with skills at all? Three reasons:
1. Best practices drift. The model knows *a* way to do things, but not always the *current* best way. CAP evolves — new annotations, patterns evolve, the CLI gains features. For example, input validation often used to require custom `before` handlers with imperative checks. Now CAP supports declarative constraints (`@assert` with CXL `case when` expressions) that push validation down to the database — no handler code needed. Without reinforcement, agents still generate the old imperative pattern because that's what dominated their training data.
2. Post-cutoff features. Models have a knowledge cutoff. If CAP shipped features like declarative constraints or status transition flows after that date, the agent simply doesn't know about them. Skills bridge the gap.
3. Workflow orchestration. Knowing the APIs is different from knowing the *sequence*. CAP's “grow as you go” philosophy means you start minimal (`cds init`, `cds watch`) and incrementally add capabilities with `cds add` as needs arise — HANA, authentication, multitenancy, deployment manifests. A skill encodes this progression: start with the domain model, validate locally, add persistence and auth only when needed. Without this guidance, agents tend to front-load complexity — generating MTA descriptors and XSUAA configs for a project that's still in the prototyping phase.
4. One path, not all paths. Documentation shows every option. Skills show the *one way that works well*. An agent faced with five valid approaches will hesitate, mix patterns, or pick based on token frequency in training data. A skill eliminates that ambiguity — it says “do it this way” and the agent executes confidently. Opinionated beats comprehensive when you want reliable output.
The goal isn't to teach agents CAP from scratch. It's to sharpen what they already know, correct subtle mistakes, introduce new capabilities, and provide reliable step-by-step workflows for complex tasks.
The Solution: Skills
A skill is a markdown file (`SKILL.md`) with structured instructions that an agent loads on demand. Think of it less as “teaching” and more as “briefing” — you're giving the agent the latest playbook for a specific task, reinforcing what it should do and correcting where its training-era knowledge has gone stale.
A skill contains:
1. Frontmatter — name, description (used for trigger matching), author, license
2. What I do — a concise statement of purpose
3. MCP Server references — which tools to use and when
4. Steps — the actual workflow, with code examples, rules, and guardrails
Here's the anatomy of a skill:
---
name: cap-node-developer
description: Expert guidance for building and extending CAP Node.js applications...
---
## What I do
Provide correct, lean, idiomatic guidance for CAP Node.js development.
## MCP Server
Always use the CAP MCP server to:
- Search documentation before guessing at APIs
- Read the effective CDS model before changing anything
## Steps
### 1. Project Initialization
When starting a new project, run:
cds init --nodejs
Rules:
- Never run `cds add sample` — it scaffolds a full demo app
- Use `cds add tiny-sample` only if explicitly requested
... Skills are small (1,000–6,000 tokens each) and loaded only when the task matches. The agent's skill description acts as a trigger — if the user says “replace my customer entity with S/4 Business Partners,” the agent matches that against the `cap-add-remote-service` skill description and loads the instructions. The token cost is minimal: comparable to a single documentation page, but far more actionable.
—
The Workspace Architecture
The workspace ties everything together using git submodules and symlinks:
“`
skills-workspace/
cap-skills/ # git submodule → source of truth for all CAP skills
skills/
cap-node-developer/
SKILL.md
cap-agent/
SKILL.md
…
anthropics-skills/ # git submodule → reference skills (e.g. skill-creator)
skills/
skill-creator/
.opencode/skills/ # symlinks for OpenCode agent discovery
cap-node-developer → ../../cap-skills/skills/cap-node-developer/
skill-creator → ../../anthropics-skills/skills/skill-creator
.claude/skills/ # symlinks for Claude Code discovery
cap-node-developer → ../../cap-skills/skills/cap-node-developer/
…
.agents/skills/ # symlinks for other agents
…
“`
Key design decisions
Single source of truth. Skills are authored in `cap-skills/skills/
Agent-agnostic discovery. Different AI coding tools look for skills in different directories. By symlinking into all three (`.opencode/`, `.claude/`, `.agents/`), the same skill works with OpenCode, Claude Code, or any future tool that follows these conventions.
Submodules for composition. The workspace composes skills from multiple sources. CAP-specific skills come from one repo; the meta `skill-creator` skill (used to author new skills) comes from Anthropic's open-source skills repo. Each can be versioned and updated independently.
Ephemeral workspaces. Directories matching `*-workspace/` are gitignored. These are scratch spaces for running skill evaluations — testing that a skill produces correct output on sample tasks. They can be blown away at any time.
The Skill Catalog
The workspace currently holds a number CAP skills plus the meta skill-creator. They cover the full lifecycle — from project setup and CDS modeling through multitenancy, messaging, remote service integration, and even building LLM agents inside CAP apps.
A few examples:
– cap-node-developer / cap-java-developer — Core development guidance, reinforcing current idioms for handlers, queries, and annotations
– cap-mtx — The multitenancy workflow end-to-end: sidecar setup, local testing, deployment to CF and Kyma
– cap-cds-review — A structured model review with severity-rated findings, triggered proactively when the agent notices modeling issues
– cap-agent— Building agentic AI features inside CAP apps using LangChain and SAP AI Core
Each skill weighs in at 1,000–6,000 tokens. Only the matched skill is loaded per task, so the overhead per interaction is minimal. The full catalog isn't public yet — stay tuned.
—
How It Works in Practice
A developer opens their terminal and asks:
> “Upgrade my CAP app to the latest version.”
With the `cap-app-upgrade` skill loaded, the agent follows a tested workflow:
1. Runs `cds version` to detect the current state
2. Checks latest published versions for all CAP packages in the project
3. Classifies the upgrade (patch, minor, or major) and presents a summary
4. For major upgrades, fetches the actual release notes and walks through migration items
5. Runs the upgrade, then validates with `cds watch` and `npm test`
6. Checks whether a database redeployment is needed (schema changes happen even in minor releases)
The skill also knows version-specific gotchas: that cds 9 requires Node.js 20+, that `@cap-js/sqlite` moved to v2, that `req.params` changed structure. These are the details an agent can't know if they shipped after its training cutoff — and exactly the kind of thing that causes a “successful” upgrade to break at runtime.
With cds 10 around the corner, we're looking at ways to improve the upgrade experience even further — stay tuned.
—
The Skill Lifecycle: From Need to Iteration
The `skill-creator` skill is a meta skill for authoring skills. But it's just one piece of a broader workflow that looks like this:
1. Identify the need. You're working in a project and notice the agent doing something suboptimal — maybe it's scaffolding auth config during prototyping, or using a deprecated API pattern. That's your signal: there's a skill missing, or an existing one needs updating.
2. Author the skill. Using the skill-creator, you draft a `SKILL.md`. You pull in references — CAP documentation, specific guides, release notes — and distill them into an opinionated workflow. The skill doesn't need to cover everything, just the one path that works well.
3. Write evals. You define sample tasks that the skill should handle correctly. These become your regression tests — run the agent with and without the skill, compare output quality.
4. Check and iterate. Run the evals, look at where the skill underperforms or overreaches, tighten the instructions. Repeat until the skill reliably produces the output you'd expect from an expert.
5. Learn from real usage. This is the part that makes skills a living artifact. At the end of a working session in a real project, I ask the agent to summarize what went well and what didn't — what it had to retry, where it made wrong assumptions, what it learned along the way. Those session learnings feed back into the skill: a new guardrail, a clarified step, a gotcha that only surfaces in practice.
This last step is what separates skills from static documentation. Documentation is written once and decays. Skills improve through use — every real project session is an opportunity to capture what the agent got wrong and encode the correction permanently.
Lessons Learned
Skills are refinement, not remediation. Agents already know CAP. Skills don't teach from zero — they correct subtle drift, introduce post-cutoff features, and enforce ordering. If you write a skill assuming the agent knows nothing, you'll waste tokens on basics and miss the nuances that actually matter.
Keep skills small and focused. A 5,700-token skill (like `cap-mtx`) is at the upper limit. If a skill needs to cover too much ground, split it. The agent can load multiple skills when needed.
Descriptions are triggers. The skill description isn't documentation — it's a classifier input. Write it for the matching algorithm: include synonyms, common phrasings, and explicit “use when” guidance.
MCP servers complement skills. Skills provide workflow and guardrails; MCP servers provide live data (documentation search, model introspection). The combination is more powerful than either alone. A skill that says “always search docs before generating annotations” prevents the agent from relying on potentially stale training knowledge.
Symlinks beat copies. Early versions duplicated skill files across discovery directories. This led to drift. Symlinks enforce a single source of truth and make `git diff` meaningful.
Evaluation is non-negotiable. Without the `*-workspace/` eval pattern, you're guessing whether a skill actually helps. The skill-creator's eval workflow runs the agent against sample tasks with and without the skill, then compares output quality. This is the only reliable way to know if your 3,000 tokens of instructions are worth the context budget.
Getting Started
If you want to set up a similar workspace for your own framework:
1. **Create a skills repo** with one directory per skill, each containing a `SKILL.md`
2. **Set up discovery symlinks** for whatever agents your team uses
3. **Write a workspace README** documenting the conventions (this is critical — agents read it too)
4. **Start with one skill** covering your framework's most common “getting started” mistakes
The workspace pattern works because it meets agents where they are — as files in a repo that follow a convention. No plugins, no API integrations, no vendor lock-in. Just markdown and symlinks.
—
Conclusion
AI coding agents don't need to be taught CAP — they already know it. What they need is the same thing a senior developer needs when joining a new team: knowledge of current conventions, awareness of recent changes, and tested playbooks for complex tasks.
Skills provide exactly this. They're cheap to write (a few hours each), cheap to load (1–6K tokens), and portable across agents. The workspace pattern keeps them organized, versioned, and discoverable.
The real insight is that skills aren't documentation — they're *opinionated workflows*. They don't say “here's everything about messaging.” They say “here's how to add messaging correctly, in this order, validating at each step.” That procedural specificity is what turns a capable-but-generic agent into one that follows your team's standards reliably.
The skills library itself is not released yet, but this is what I am working on at the moment and hope to release the first skills soon. I'll update this post, once released.
Creating a workspace in which to create and improve skills has proven helpful to me, so I hope this is useful for you, too.
Please comment / like / provide feedback for improvement!
