Add CLAUDE.md and Claude Skills to Kyma Environment Broker Repository

[PK85]

Background & Context

Claude Code works best when a repository contains a CLAUDE.md file that describes the project structure, conventions, and common workflows, and when custom skills are available for repo-specific tasks. Without these, developers using Claude Code in the Kyma Environment Broker (KEB) repository get generic assistance that misses repo-specific context.

This ticket covers the initial setup and defines how these configurations will be maintained going forward.

---

User Story

As a KEB developer, I want the repository to have a CLAUDE.md and a set of Claude skills, so that Claude Code provides context-aware assistance aligned with our project conventions, workflows, and architecture.

---

What Needs to Be Done

CLAUDE.md

A CLAUDE.md file at the repository root should include:

• Project overview — what KEB does, its role in the Kyma ecosystem
• Repository structure — key directories and what lives in each (cmd/, internal/, resources/, testing/, etc.)
• Development workflow — how to build, run tests locally, run linting
• Coding conventions — naming patterns, error handling style, how new steps/handlers are registered
• Common gotchas — things that trip up new contributors (e.g. config struct registration, whitelist file pattern, how provisioning steps are chained)
• Key abstractions — a short glossary of domain terms (Instance, Operation, Runtime CR, Plan, etc.)

Skills

The repository should build a skill set based on what developers actually reach for. Good candidates include workflow automation (e.g. pr-review, commit), code generation (e.g. scaffolding a new provisioning step), and repo-specific navigation helpers. The initial set should be small and validated — it is better to have two skills that work well than ten that are rarely used.

Skills are stored in .claude/skills/ at the repository root.

Maintenance Process

• CLAUDE.md is treated as living documentation: any PR that changes project structure, adds a new pattern, or modifies the build/test workflow must update CLAUDE.md as part of the same PR.
• Skills are versioned alongside the code. If a workflow changes, the relevant skill is updated in the same PR.
• A PR checklist item reminds contributors to check whether CLAUDE.md or skills need updating.

---

Acceptance Criteria

• AC1 — CLAUDE.md — A CLAUDE.md exists at the root of the KEB repository covering: project overview, directory structure, build/test commands, coding conventions, common gotchas, and domain glossary.
• AC2 — Skills — A small set of skills is implemented as good starting points, determined by the team based on what tasks they most frequently perform (e.g. pr-review, commit, step scaffolding), and validated locally with Claude Code.
• AC3 — Maintenance convention — A note in CLAUDE.md (or CONTRIBUTING.md) explains that both CLAUDE.md and skills must be kept up to date with code changes, and describes where skills are stored.
• AC4 — PR review — The PR is reviewed by at least one team member who uses Claude Code, confirming the setup provides useful assistance for a typical development task.

---

Out of Scope

• Setting up Claude Code organization-level configuration
• Automating skill discovery across all Kyma repositories
• Training or fine-tuning models

---

Definition of Done

• CLAUDE.md merged to main
• Skills directory (.claude/skills/) merged to main
• Maintenance convention documented
• At least one developer has validated the setup end-to-end with Claude Code