external-client

Generates layered SDK-style integration packages for external HTTP, gRPC, and message broker services.

Updated Jun 25, 2026
One-click install
npx skills add https://github.com/oriddd/ai-toolkit --skill external-client-oriddd
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: external-client
Source: https://github.com/oriddd/ai-toolkit/tree/main/copilot/public/skills/external-client
Command: npx skills add https://github.com/oriddd/ai-toolkit --skill external-client-oriddd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Integrating external services often leaks transport details (WebClient, Mono, remote DTOs) into business code, making callers hard to read, test, and evolve. This Skill wraps every downstream dependency in a self-contained client sub-package so callers see one domain-friendly service facade. ## Core Features & Use Cases - Pattern Selection Guidance: A human-in-the-loop decision tree chooses between a simple RestClient wrapper (1-4 endpoints), a lite client (5-9 endpoints), or the full five-layer SDK pattern (10+ endpoints or complex query DSLs). - Canonical Five-Layer Structure: Generates Service facade, CoreService orchestrator, thin Client transport, RequestBuilder/FilterMapBuilder, ResponseParser/ResponseVerifier, Config, and Constants classes. - Resilience & Error Translation: Applies Resilience4j circuit breakers and retries, and translates non-2xx responses into domain exceptions before they escape the client package. - Use Case: When adding a new Elasticsearch or Kafka dependency to a Spring Boot service, use this Skill to scaffold the complete client/<dep>/ package with tests, properties, and health-check wiring. ## Quick Start Apply the external-client skill to generate a client integration package for the new downstream service I need to call.

Frequently Asked Questions about external-client

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I wrap an external REST API in a Spring Boot service?

Create a client/<dep>/ sub-package with a domain-facing Service facade, a thin WebClient transport class, and request/response handlers. Callers import only the Service and never see WebClient, Mono, or remote DTO types.

When should I use a simple RestClient wrapper versus a full layered client package?

Use a simple 3-file wrapper for 1-4 simple CRUD endpoints with plain JSON mapping. Choose the full five-layer pattern when you have 10+ endpoints, complex query DSLs, multi-step protocols, or heavy DTO transformation.

How do I handle WebClient errors and non-2xx responses in Spring?

Use exchangeToMono with a private handleResponse method to read the error body and status, then throw a domain exception before it escapes the client package. Never let WebClientResponseException leak to callers.

Should I retry failed calls to external services with Resilience4j?

Retry only idempotent operations like GET requests or count-only POSTs, using Resilience4j annotations on the client method. The fallback must throw a domain exception rather than returning a silent empty value.

What are the limitations of keeping everything in one client package?

The client package suits pure transport integrations only. Once it exceeds roughly 10 classes or accumulates fetchers, analyzers, or schedulers, promote those responsibilities to repository, mapper, analyzer, and scheduler packages.