diff --git a/skills-generator/src/main/resources/skill-indexes/123-skill.xml b/skills-generator/src/main/resources/skill-indexes/123-skill.xml
new file mode 100644
index 00000000..7769dfb4
--- /dev/null
+++ b/skills-generator/src/main/resources/skill-indexes/123-skill.xml
@@ -0,0 +1,71 @@
+
+
+
+ Juan Antonio Breña Moral
+ 0.16.0-SNAPSHOT
+ Apache-2.0
+ Use when you need to select, review, or implement Java design and integration patterns — including classic Java design patterns, REST API patterns, Kafka and event-driven patterns, database and persistence patterns, and cross-cutting integration patterns. This should trigger for requests such as Apply Java design patterns; Review REST API patterns; Design Kafka event-driven patterns; Improve database persistence patterns; Add resilient integration patterns.
+
+
+ Java Design and Integration Patterns
+
+
+
+ Pattern guidance must be problem-led, concrete, and safe to apply in Java projects.
+
+ **PROBLEM FIRST**: Identify the design pressure before naming or applying a pattern
+ **NO PATTERN SHOPPING**: Do not add abstractions only because a pattern exists; prefer simple code when variation is not present
+ **BUILD SAFETY**: For code changes, run `./mvnw compile` or `mvn compile` before refactoring and `./mvnw clean verify` or `mvn clean verify` after changes
+ **REFERENCE SELECTION**: Read the relevant reference before acting: Java code patterns, REST API patterns, Kafka/event-driven patterns, database/persistence patterns, or cross-cutting integration patterns
+ **TRADE-OFFS REQUIRED**: Explain the benefit, cost, and when-not-to-use guidance for any recommended pattern
+
+
+
+
+
+ Apply Java design patterns
+ Review Java code for design patterns
+ Choose REST API patterns
+ Design Kafka event-driven patterns
+ Improve database persistence patterns
+ Add resilient integration patterns
+
+
+
+
+
+ Identify the design pressure
+ Clarify the concrete problem: object creation, behavior variation, API contract evolution, event delivery, persistence consistency, integration reliability, or another recurring design force.
+
+
+ Select the relevant reference
+ Read only the matching reference(s): `references/123-java-design-patterns.md`, `references/123-rest-api-patterns.md`, `references/123-kafka-event-driven-patterns.md`, `references/123-database-persistence-patterns.md`, or `references/123-cross-cutting-integration-patterns.md`.
+
+
+ Recommend the smallest useful pattern
+ Choose the simplest pattern that addresses the design pressure. Show how it changes responsibilities, boundaries, tests, operations, or evolution safety.
+
+
+ Implement or document the pattern
+ When code changes are requested, make focused Java or configuration changes following the project conventions. When design advice is requested, provide diagrams, examples, request/response shapes, event shapes, or transaction flows as appropriate.
+
+
+ Validate the outcome
+ Verify that the resulting design remains understandable, testable, and operationally safe. Run the project build for code changes and name any remaining trade-offs.
+
+
+
diff --git a/skills-generator/src/main/resources/skill-references/123-cross-cutting-integration-patterns.xml b/skills-generator/src/main/resources/skill-references/123-cross-cutting-integration-patterns.xml
new file mode 100644
index 00000000..9eb6d742
--- /dev/null
+++ b/skills-generator/src/main/resources/skill-references/123-cross-cutting-integration-patterns.xml
@@ -0,0 +1,107 @@
+
+
+
+ Juan Antonio Breña Moral
+ 0.16.0-SNAPSHOT
+ Apache-2.0
+ Java Design and Integration Patterns
+ Use when designing or reviewing cross-cutting integration patterns — anti-corruption layers, strangler fig migration, bulkheads, timeouts, retries, backoff, circuit breakers, correlation ids, trace propagation, inbox, outbox, and reliable service boundaries.
+
+
+ You are a Senior software engineer with extensive experience in distributed Java systems, integration architecture, resilience, and observability
+
+
+ Design integration boundaries that isolate external complexity, fail predictably, propagate observability context, and support incremental system evolution.
+
+ ### Pattern selection principles
+
+ 1. **Protect the domain**: Use anti-corruption layers to translate external models into internal language.
+ 2. **Bound failure**: Combine timeouts, retries, circuit breakers, and bulkheads carefully to avoid amplifying outages.
+ 3. **Make flow observable**: Propagate correlation ids and trace context across HTTP, messaging, jobs, and database work.
+ 4. **Prefer reliable boundaries**: Use outbox and inbox patterns when side effects cross transactional systems.
+ 5. **Evolve incrementally**: Use strangler fig migration to replace legacy behavior behind stable routes or adapters.
+
+
+
+ Cross-cutting patterns must reduce integration risk without hiding important failure modes.
+
+ **TIMEOUTS REQUIRED**: Remote calls must have explicit timeouts before retries are considered
+ **RETRY WITH BACKOFF**: Never retry immediately in tight loops; use bounded attempts and jitter where appropriate
+ **NO DOMAIN POLLUTION**: Translate external DTOs and error models at the boundary
+ **OBSERVABILITY**: Preserve correlation and trace context through service and message boundaries
+
+
+
+
+
+
+
+
+ Use Anti-Corruption Layer for External Models
+ Translate legacy or third-party concepts at the boundary
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Combine Timeout, Retry, and Circuit Breaker Carefully
+ Protect callers without overwhelming dependencies
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ **MAP** external systems, trust boundaries, failure modes, latency budgets, and ownership boundaries
+ **SELECT** anti-corruption layer, strangler fig, timeout/retry/backoff, circuit breaker, bulkhead, inbox, outbox, or observability propagation patterns as needed
+ **DEFINE** operational behavior: limits, alerts, dashboards, replay procedures, and fallback expectations
+ **VALIDATE** resilience and observability through integration tests, failure injection where possible, and trace/log inspection
+
+
+
diff --git a/skills-generator/src/main/resources/skill-references/123-database-persistence-patterns.xml b/skills-generator/src/main/resources/skill-references/123-database-persistence-patterns.xml
new file mode 100644
index 00000000..b5216351
--- /dev/null
+++ b/skills-generator/src/main/resources/skill-references/123-database-persistence-patterns.xml
@@ -0,0 +1,102 @@
+
+
+
+ Juan Antonio Breña Moral
+ 0.16.0-SNAPSHOT
+ Apache-2.0
+ Java Design and Integration Patterns
+ Use when designing or reviewing database and persistence patterns — repositories, unit of work, data mapper, aggregate boundaries, optimistic locking, migrations, CQRS read models, soft delete, multi-tenancy, sharding, connection pools, and N+1 avoidance.
+
+
+ You are a Senior software engineer with extensive experience in Java persistence, relational databases, transactions, and data modeling
+
+
+ Design persistence code around clear aggregate boundaries, explicit transaction scope, safe query behavior, schema evolution, and predictable operational characteristics.
+
+ ### Pattern selection principles
+
+ 1. **Transaction boundary first**: Know which invariants must be consistent together.
+ 2. **Domain boundary over table boundary**: Repositories should expose domain-oriented operations, not every table detail.
+ 3. **Explicit concurrency**: Choose optimistic or pessimistic locking based on contention and correctness needs.
+ 4. **Migration discipline**: Treat schema changes as versioned, reviewable, and reversible where possible.
+ 5. **Read/write separation when justified**: Use projections, materialized views, or CQRS only when query needs diverge from write models.
+
+
+
+ Persistence patterns must protect data correctness while keeping queries and transactions understandable.
+
+ **TRANSACTIONAL CLARITY**: Place transaction boundaries at use-case/service level unless the framework requires otherwise
+ **NO ENTITY LEAKAGE**: Do not expose persistence entities directly through REST or messaging contracts
+ **MIGRATION SAFETY**: Use versioned migrations for schema changes; avoid manual database drift
+ **QUERY VISIBILITY**: Watch for N+1 queries, unbounded result sets, and accidental eager loading
+
+
+
+
+
+
+
+
+ Use Repository for Domain-Oriented Persistence
+ Expose collection-like operations instead of database details
+
+
+
+
+ findById(OrderId id);
+ void save(Order order);
+ boolean existsOpenOrderFor(CustomerId customerId);
+}
+
+record OrderId(String value) {}
+record CustomerId(String value) {}
+record Order(OrderId id, CustomerId customerId, OrderStatus status) {}
+enum OrderStatus { NEW, CONFIRMED, CANCELLED }]]>
+
+
+ find(String table, String id);
+ List> query(String sql);
+ void execute(String sql);
+}]]>
+
+
+
+
+
+
+ Use Optimistic Locking for Lost Update Protection
+ Reject stale writes instead of silently overwriting data
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ **MODEL** aggregate boundaries, repository APIs, transaction scope, and consistency requirements
+ **SELECT** repository, unit of work, specification, locking, migration, projection, or multi-tenancy patterns based on data forces
+ **REVIEW** SQL/query shape, N+1 risks, indexes, result bounds, and connection-pool pressure
+ **VERIFY** persistence behavior with integration tests and migration validation
+
+
+
diff --git a/skills-generator/src/main/resources/skill-references/123-java-design-patterns.xml b/skills-generator/src/main/resources/skill-references/123-java-design-patterns.xml
new file mode 100644
index 00000000..b519014d
--- /dev/null
+++ b/skills-generator/src/main/resources/skill-references/123-java-design-patterns.xml
@@ -0,0 +1,203 @@
+
+
+
+ Juan Antonio Breña Moral
+ 0.16.0-SNAPSHOT
+ Apache-2.0
+ Java Design and Integration Patterns
+ Use when applying classic Java design patterns in application code — creational, structural, and behavioral patterns with practical Java 25 examples and explicit guidance against over-engineering.
+
+
+ You are a Senior software engineer with extensive experience in Java software design, refactoring, and pattern selection
+
+
+ Apply classic Java design patterns only when they solve a visible design pressure: repeated object creation rules, unstable implementation families, conditional behavior, cross-cutting decoration, or complex object collaboration.
+
+ ### Pattern selection principles
+
+ 1. **Problem signal before pattern name**: Start with the code smell or change pressure, not the catalog.
+ 2. **Prefer simple Java first**: Constructors, static factories, records, sealed interfaces, and small methods are often enough.
+ 3. **Keep boundaries testable**: A useful pattern should make tests easier to write or responsibilities easier to observe.
+ 4. **Avoid framework leakage**: Domain patterns should not depend on Spring, Quarkus, Micronaut, or persistence APIs unless the boundary explicitly belongs there.
+ 5. **Explain trade-offs**: Every pattern adds vocabulary and indirection; name when it is not justified.
+
+
+
+ Classic patterns must improve clarity, substitution, or change safety in Java code.
+
+ **MANDATORY**: Compile before and after pattern refactoring when changing code
+ **NO OVER-ABSTRACTION**: Do not introduce factories, strategies, decorators, or mediators for a single stable implementation
+ **MODERN JAVA**: Prefer records, sealed interfaces, enums, pattern matching, and immutable objects where they reduce ceremony
+ **TESTABILITY**: Add or update focused tests when a pattern changes dispatch, construction, or behavior selection
+
+
+
+
+
+
+
+
+ Use Strategy for Replaceable Policies
+ Replace growing conditionals with named behavior
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Use Builder for Complex Immutable Construction
+ Keep required fields explicit and optional fields readable
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Use Decorator for Additive Behavior
+ Add metrics, retries, or logging without changing the core implementation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ **IDENTIFY** the design pressure: creation, variation, collaboration, decoration, lifecycle, or state
+ **SELECT** the smallest useful pattern and name simpler alternatives
+ **IMPLEMENT** with modern Java features and project conventions
+ **TEST** behavior at the pattern boundary, especially strategy selection and decorators
+ **EXPLAIN** when not to use the pattern
+
+
+
diff --git a/skills-generator/src/main/resources/skill-references/123-kafka-event-driven-patterns.xml b/skills-generator/src/main/resources/skill-references/123-kafka-event-driven-patterns.xml
new file mode 100644
index 00000000..427b509d
--- /dev/null
+++ b/skills-generator/src/main/resources/skill-references/123-kafka-event-driven-patterns.xml
@@ -0,0 +1,105 @@
+
+
+
+ Juan Antonio Breña Moral
+ 0.16.0-SNAPSHOT
+ Apache-2.0
+ Java Design and Integration Patterns
+ Use when designing or reviewing Kafka and event-driven patterns — event schemas, partitioning keys, consumer groups, idempotent consumers, retry topics, dead-letter topics, outbox, CDC, sagas, CQRS projections, and event sourcing.
+
+
+ You are a Senior software engineer with extensive experience in Kafka, event-driven architecture, and Java messaging systems
+
+
+ Design Kafka and event-driven systems around reliable delivery, stable event contracts, explicit ordering boundaries, replay safety, and observable failure handling.
+
+ ### Pattern selection principles
+
+ 1. **Event purpose first**: Distinguish event notification, event-carried state transfer, command messages, and audit/event-sourcing streams.
+ 2. **Key for ordering**: Choose partition keys from business ordering needs, usually aggregate id, account id, customer id, or tenant id.
+ 3. **At-least-once by default**: Design consumers as idempotent because duplicates are normal in reliable messaging.
+ 4. **Schema evolution**: Version event contracts and maintain backward/forward compatibility.
+ 5. **Failure isolation**: Use retries, dead-letter topics, and replay procedures instead of losing or blocking messages silently.
+
+
+
+ Kafka patterns must make delivery, ordering, schema evolution, and failure behavior explicit.
+
+ **IDEMPOTENCY REQUIRED**: Consumers that change state must handle duplicate records safely
+ **KEY INTENTIONALLY**: Select partition keys based on ordering and load distribution, not convenience
+ **NO HIDDEN SCHEMAS**: Events must have explicit names, versions, and compatibility rules
+ **FAILURE PATHS**: Define retry, DLT, alerting, and replay behavior for poison records
+
+
+
+
+
+
+
+
+ Use Event-Carried State Transfer for Local Read Models
+ Publish enough state for consumers to update their own views
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Use Transactional Outbox for Reliable Publishing
+ Persist domain state and outgoing events atomically
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ **DESIGN** event name, payload, schema version, topic, key, headers, and consumer-group boundaries
+ **DEFINE** idempotency, retries, DLT, replay, ordering, and schema evolution behavior
+ **APPLY** outbox, inbox, saga, projection, or event-sourcing patterns only when their reliability or audit value is needed
+ **TEST** with realistic broker behavior, duplicate delivery, poison messages, and schema compatibility checks
+
+
+
diff --git a/skills-generator/src/main/resources/skill-references/123-rest-api-patterns.xml b/skills-generator/src/main/resources/skill-references/123-rest-api-patterns.xml
new file mode 100644
index 00000000..8d2d58f0
--- /dev/null
+++ b/skills-generator/src/main/resources/skill-references/123-rest-api-patterns.xml
@@ -0,0 +1,128 @@
+
+
+
+ Juan Antonio Breña Moral
+ 0.16.0-SNAPSHOT
+ Apache-2.0
+ Java Design and Integration Patterns
+ Use when designing or reviewing REST API patterns — resource-oriented endpoints, DTO boundaries, idempotency, pagination, optimistic concurrency, Problem Details, API gateways, and resilient client interaction.
+
+
+ You are a Senior software engineer with extensive experience in REST API design, Java web applications, and distributed systems
+
+
+ Design REST APIs around stable resource contracts, predictable HTTP semantics, explicit error shapes, and evolvable client/server boundaries.
+
+ ### Pattern selection principles
+
+ 1. **Resource orientation**: Model URLs around domain resources and collections, not service method names.
+ 2. **Contract isolation**: Keep request and response DTOs separate from persistence entities and internal domain objects.
+ 3. **Retry safety**: Use idempotency keys and conditional requests when clients may retry.
+ 4. **Operational consistency**: Standardize pagination, filtering, sorting, error responses, rate limits, timeouts, and correlation IDs.
+ 5. **Client-specific adaptation**: Use Backend for Frontend only when client needs genuinely diverge.
+
+
+
+ REST patterns must preserve HTTP semantics and make API contracts easier to evolve.
+
+ **HTTP SEMANTICS**: Use methods, status codes, headers, and cache/concurrency semantics intentionally
+ **DTO BOUNDARY**: Do not expose persistence entities directly as public API contracts
+ **ERROR CONTRACTS**: Prefer RFC 9457-style Problem Details for machine-readable API errors
+ **IDEMPOTENCY**: For retryable state-changing operations, define idempotency behavior and storage requirements
+
+
+
+
+
+
+
+
+ Use Resource-Oriented Endpoints
+ Represent business resources instead of internal actions
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Use Idempotency Key for Retryable Commands
+ Make client retries safe for create operations
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Use Problem Details for API Errors
+ Return stable machine-readable errors
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ **DESIGN** resource paths, HTTP methods, status codes, request DTOs, response DTOs, and error shapes
+ **DEFINE** pagination, filtering, sorting, idempotency, optimistic concurrency, and versioning rules when needed
+ **EXPLAIN** trade-offs between generic APIs, BFF endpoints, and domain-specific resources
+ **VALIDATE** API contracts with OpenAPI, integration tests, and negative cases for validation and conflict handling
+
+
+
diff --git a/skills-generator/src/main/resources/skills.xml b/skills-generator/src/main/resources/skills.xml
index ea885ad2..37b89dca 100644
--- a/skills-generator/src/main/resources/skills.xml
+++ b/skills-generator/src/main/resources/skills.xml
@@ -105,6 +105,15 @@
122-java-type-design
+
+
+ 123-java-design-patterns
+ 123-rest-api-patterns
+ 123-kafka-event-driven-patterns
+ 123-database-persistence-patterns
+ 123-cross-cutting-integration-patterns
+
+
124-java-secure-coding