# SkillOverflow

![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg) ![Skills](https://img.shields.io/badge/skills-41-blue) ![SAP](https://img.shields.io/badge/SAP-CAP%20%7C%20Fiori%20%7C%20BTP%20%7C%20UI5-brightgreen)

A library of AI agent skills for SAP development. Skills are markdown instruction files that AI coding agents (Claude Code, GitHub Copilot, OpenCode) load automatically when you work on relevant tasks — encoding SAP best practices so every developer gets consistent, high-quality AI assistance without having to prompt for it.

---

## Quickstart — one time per developer, not per project

Skills are installed **globally** into your home folder — not inside any project.
Customer repos stay clean. Every project you open gets the skills automatically.

```bash
# 1. Clone skillOverflow once into your home folder
git clone https://github.com/DanKromp/skillOverflow.git ~/skillOverflow

# 2. Run setup — choose which AI tools you use
bash ~/skillOverflow/setup.sh
```

The interactive setup asks which tools you use and only creates what you need:

```
Which AI tools do you use?
  ↑↓ move  space toggle  enter confirm  a select all

  ▶ [x] Claude Code           → ~/.claude/skills/
    [ ] GitHub Copilot        → ~/.copilot/skills/
    [ ] OpenCode              → ~/.config/opencode/skills/
    [ ] Other agents-spec     → ~/.agents/skills/
```

Or skip the prompt with flags:
```bash
bash ~/skillOverflow/setup.sh --claude           # Claude Code only
bash ~/skillOverflow/setup.sh --copilot          # GitHub Copilot only
bash ~/skillOverflow/setup.sh --claude --copilot # both
bash ~/skillOverflow/setup.sh --all              # all tools
```

Only want certain skill categories? Right after the tool picker, the interactive setup
also asks which skill categories you want — all selected by default, so just
deselect what you don't need:

```
Which skill categories do you want?
  ↑↓ move  space toggle  enter confirm  a all  n none

  ▶ [x] CAP         — Cloud Application Programming Model
    [x] Fiori       — Fiori Elements & UI development
    [x] BTP         — Business Technology Platform services
    [x] UI5         — SAPUI5 controls, binding, testing
    ...
```

Or skip the prompt and set the categories directly:
```bash
# Only install the CAP, Fiori, UI5 and BTP categories
bash ~/skillOverflow/setup.sh --claude --categories=cap,fiori,ui5,btp
```
Valid categories: `cap`, `fiori`, `btp`, `ui5`, `abap`, `integration`, `hana`, `meta`.
Narrowing the set prunes categories you removed; `--update` keeps the categories you chose.

Then restart VS Code — skills are active in every project immediately.

---

## Skill categories

All skills live flat under [`skills/<skill-slug>/`](skills/) (required by the AI Skills
Library) and declare their category via the `metadata.category` field in `SKILL.md`.

| Category | Skills | Description |
|---|---|---|
| `cap` | 22 skills | SAP Cloud Application Programming Model |
| `fiori` | 5 skills | SAP Fiori Elements & UI development |
| `btp` | 3 skills | SAP Business Technology Platform services |
| `ui5` | 4 skills | SAPUI5 controls, binding, testing |
| `abap` | 1 skill | ABAP RESTful Application Programming Model |
| `integration` | 1 skill | SAP Integration Suite / Cloud Integration |
| `hana` | 1 skill | SAP HANA Cloud native / HDI development |
| `meta` | 4 skills | Skill lifecycle — create, review, deprecate |

**Total: 41 skills | 41 evals**

---

### CAP skills

| Skill | Activates when working on… |
|---|---|
| `cds-modeling` | CDS entities, aspects, associations, projections |
| `service-handlers` | before/on/after handlers, actions, functions, cds.ql |
| `security-auth` | @requires, @restrict, XSUAA, IAS, row-level authorization |
| `btp-deployment` | mta.yaml, cds build, Cloud Foundry, Kyma, HDI containers |
| `ci-cd` | GitHub Actions pipelines, SAP CI/CD service, deployment automation |
| `fiori-draft` | @odata.draft.enabled, draft lifecycle, Fiori draft messages |
| `cap-llm-plugin` | SAP AI SDK, RAG, embeddings, HANA Vector Engine, AI Core |
| `code-review` | CAP code quality checks, anti-pattern detection, structured review |
| `error-handling` | req.reject/warn/error, HTTP codes, i18n messages, field targets |
| `testing` | cds.test, Vitest (recommended), integration tests, mocking, auth testing |
| `messaging` | SAP Event Mesh, CloudEvents, emit/on patterns, outbox |
| `multitenancy` | @sap/cds-mtxs, tenant provisioning, HDI per tenant |
| `remote-services` | S/4HANA OData, BTP Connectivity, Destination, cds.connect.to |
| `performance` | N+1 queries, SELECT projections, streaming, HANA optimization |
| `localization` | localized elements, i18n bundles, _texts tables, CSV format |
| `cap-plugins` | change-tracking, audit-logging, attachments, notifications |
| `observability-telemetry` | cds.log, @cap-js/telemetry, Cloud Logging, OpenTelemetry |
| `cds9-migration` | Upgrading to CDS 9, deprecated APIs, breaking changes |
| `cds10-migration` | Upgrading to CDS 10, Node.js 22+, bypass drafts, service results, Vitest |
| `status-transitions` | @flow annotations, state machines, status workflows |
| `cap-java` | CAP Java Spring Boot, EventHandler, @Before/@On/@After, CqnService, Maven |
| `cap-mcp-server` | SAP MCP Server, UI5/Fiori MCP tooling, AI agent integration |

### Fiori skills

| Skill | Activates when working on… |
|---|---|
| `fiori-elements-floorplans` | Floorplan selection, manifest.json, List Report, Object Page, ALP |
| `fiori-annotations` | UI.LineItem, UI.Facets, UI.FieldGroup, Criticality, ValueList |
| `fiori-flexible-programming` | Building blocks, extension points, controller extensions |
| `fiori-navigation` | Routing, intent-based navigation, FCL, Launchpad targets |
| `fiori-tools` | Application Generator, Page Editor, Guided Development |

### BTP skills

| Skill | Activates when working on… |
|---|---|
| `btp-service-bindings` | VCAP_SERVICES, cds bind, hybrid testing, Kyma ServiceBinding |
| `btp-destinations` | OAuth2ClientCredentials, OAuth2JWTBearer, principal propagation, Cloud Connector |
| `btp-workzone` | SAP Build Work Zone, HTML5 deployment, content providers, Managed App Router |

### UI5 skills

| Skill | Activates when working on… |
|---|---|
| `ui5-data-binding` | OData V4 model, list binding, context binding, $batch, side effects |
| `ui5-custom-controls` | Control.extend(), renderer apiVersion 2, lifecycle hooks |
| `ui5-i18n` | Resource model, i18n.properties, UI5Date, DateFormat, NumberFormat |
| `ui5-testing` | wdi5, WebdriverIO, OPA5, page objects, QUnit, UIVeri5 migration |

### ABAP skills

| Skill | Activates when working on… |
|---|---|
| `abap-rap` | ABAP RAP, BDEF, managed/unmanaged, draft, validations, determinations, actions |

### Integration skills

| Skill | Activates when working on… |
|---|---|
| `integration-suite` | Cloud Integration iFlows, adapters, mapping, Groovy, security material, MPL |

### HANA skills

| Skill | Activates when working on… |
|---|---|
| `hana-cloud-native` | HDI containers, .hdbtable, calculation views, SQLScript, .hdbrole, hdi-deploy |

### Meta skills

| Skill | Activates when working on… |
|---|---|
| `skill-creator` | Identifying the need for a new skill, full lifecycle overview |
| `skill-contributor` | **Creating** a new skill — automates README, evals, checklist, PR draft |
| `skill-reviewer` | **Reviewing** a skill PR — structured quality checklist |
| `skill-deprecator` | **Removing** outdated skills, model re-evaluation after updates |

---

## How skills work

```
Your prompt
    ↓
Agent reads all skill descriptions (fast — name + description only)
    ↓
Matching skill(s) load into context automatically
    ↓
Agent follows the instructions when generating code
```

You don't ask for skills by name — just describe your task naturally:

- *"Add a Products entity with currency"* → `cds-modeling`
- *"Review this service handler"* → `code-review`
- *"Set up a BTP destination with OAuth"* → `btp-destinations`
- *"Write E2E tests for our UI5 app"* → `ui5-testing`
- *"I want to add a new skill"* → `skill-contributor`

### If a skill doesn't load

Auto-matching is **best-effort, not guaranteed** — the agent decides when a skill is
relevant, so occasionally one won't fire. That's by design, because SkillOverflow has
**three layers**, and the reliable ones always have your back:

1. **Instruction files** — loaded **every session, guaranteed.** The critical rules
   (`cuid, managed`, `@requires` + `@restrict`, no `BasicAuthentication`, …) always apply,
   even when no skill matches.
2. **Slash commands** — `/cap-model`, `/cap-review`, `/cap-security` **force-load** their
   skill on demand. Use these when you want a specific skill for certain.
3. **Auto-loaded skills** — the convenience layer that fires when your prompt matches.

So if a skill doesn't auto-load: rephrase with concrete terms (e.g. `@restrict`, `mta.yaml`,
`bindList`), or invoke the matching slash command. You never lose the baseline rules.

---

## Supported tools

| Tool | Skills folder | Instruction file | Set up with |
|---|---|---|---|
| Claude Code | `~/.claude/skills/` | `~/.claude/CLAUDE.md` | `--claude` |
| GitHub Copilot | `~/.copilot/skills/` | `~/.copilot/copilot-instructions.md` | `--copilot` |
| OpenCode | `~/.config/opencode/skills/` | `~/.config/opencode/AGENTS.md` | `--opencode` |
| Any agents-spec | `~/.agents/skills/` | `~/.agents/AGENTS.md` | `--agents` |

**Skills** are loaded when your prompt matches — the instruction file is loaded **every session, guaranteed**. Together they ensure the agent always follows SAP best practices.

---

## Updating skills

```bash
cd ~/skillOverflow && git pull && bash setup.sh --update
```

`--update` detects which tools you already have installed and refreshes only those.

---

## Command reference

```bash
bash setup.sh            # interactive tool picker
bash setup.sh --all      # install for all tools (Claude, Copilot, OpenCode, agents)
bash setup.sh --categories=cap,fiori,ui5  # install only skills in selected categories
bash setup.sh --update   # refresh an existing installation
bash setup.sh --status   # show what is installed and whether symlinks are healthy
bash setup.sh --list     # list all available skills by category
bash setup.sh --uninstall # remove all SkillOverflow symlinks and managed blocks
bash setup.sh --version  # print the version
bash setup.sh --help     # full usage
```

> Stuck? Run `bash setup.sh --status` and share the output in the support channel — it reports broken symlinks and missing instruction blocks.

---

## Specialized agents

Specialized sub-agents for complex SAP tasks:

| Agent | Skill | What it does |
|---|---|---|
| `cds-modeler` | `cds-modeling` | Design or review a complete CDS data model from a business description |
| `security-reviewer` | `security-auth` | Full authorization audit — @requires, @restrict, xs-security.json |
| `handler-reviewer` | `service-handlers` | Structured code review with severity labels and concrete fixes |
| `cap-model-explorer` | `cap-mcp-server` | Explore CAP entities/services/actions using MCP before proposing changes |
| `ui5-api-explorer` | `ui5-data-binding` | Discover UI5 APIs and provide version-aware implementation guidance |
| `fiori-annotation-navigator` | `fiori-annotations` | Map UX requirements to correct Fiori annotation snippets |
| `fiori-mcp-troubleshooter` | `fiori-tools` | Diagnose Fiori MCP configuration and tool availability issues |

Ask your agent: `"Use the cds-modeler agent to design a data model for [domain]"`

## Slash commands

Three commands for the most common tasks:

| Command | What it does |
|---|---|
| `/cap-review` | Full CAP code review with severity labels |
| `/cap-security` | Authorization security audit |
| `/cap-model` | Design a CDS data model from a description |

---

## Learn More

**First time here?** Start with:
1. ✅ Run setup.sh (all done!)
2. 🗺️ Read the [Skill Dependency Map](docs/skill-map.md) — understand which skills work together
3. 💡 Check [Specialized Agent Commands](commands/README.md) — learn `/cap-model`, `/cap-security`, `/cap-review`
4. 🧪 Run tests: `bash ~/skillOverflow/tests/smoke-test.sh` (verify installation)

**For teams:**
- [skill-map.md](docs/skill-map.md) — Visual guide to skill relationships and common workflows
- [commands/README.md](commands/README.md) — How to set up VS Code shortcuts for `/cap-model`, `/cap-security`, `/cap-review`
- [CONTRIBUTING.md](CONTRIBUTING.md) — How to add or update skills

---

## Pre-Commit Hooks

Prevent broken commits with automatic validation:

```bash
# One-time setup
git config core.hooksPath .githooks
chmod +x .githooks/pre-commit
```

The pre-commit hook runs smoke tests automatically before each commit. See [.githooks/README.md](.githooks/README.md) for details.

---

## Security

Report security vulnerabilities responsibly — see [SECURITY.md](SECURITY.md) for the disclosure process.

SkillOverflow has **zero runtime dependencies** — it's pure Bash and Markdown with no external packages.

---

## Contributing

Use the `skill-contributor` meta skill — ask your agent:

```
I want to add a new skill for [topic]. Walk me through it.
```

All contribution steps are automated. See `CONTRIBUTING.md` for the full guide.

To contribute, work directly in `~/skillOverflow/`:
```bash
cd ~/skillOverflow
git checkout -b skill/my-new-skill
# make changes
git push origin skill/my-new-skill
# open PR on GitHub
```

---

## Versioning

```bash
# Pin to a specific version
cd ~/skillOverflow && git checkout v1.0.0

# Back to latest
cd ~/skillOverflow && git checkout main && git pull
```

---

## License

Apache License 2.0 — Copyright (c) 2026 [Daniel Krompaß](https://github.com/DanKromp)

See [LICENSE](LICENSE) for the full text. Free to use, fork, and contribute.