Stop Embedding Business Logic in Prompts: An Enterprise Guide to Spring AI Alibaba Skills

Why AI Projects Often Die at the Architecture Boundary

In the past two years many teams built AI applications by first creating a runnable Prompt demo, then gradually stuffing refund, logistics, recommendation, and complaint logic into the same Prompt. This works for validation but becomes a problem when business domains evolve, concurrency rises, risk scenarios increase, model‑call costs are scrutinized, and SLAs are required.

The real issue is that the system hands over responsibilities that should belong to the application layer to the Prompt, turning it into a "super Prompt" that is hard to maintain.

Real Incident: Super Prompt Slowing an E‑commerce Customer Service

A marketing event caused the customer‑service system to show latency spikes (P99 6‑8 s) and higher error rates. Initial checks showed no network or model errors; the fastest‑growing metric was the input token count (2000‑4000 tokens) and average processing time. The root cause was a six‑month‑old super Prompt that had evolved from simple constraints to a mixed‑purpose runtime handling intent, tool selection, rule explanation, exception handling, and response generation.

Why a Super Prompt Collides with Production Requirements

Inference complexity and business complexity become tightly coupled, forcing every request to read the entire context before deciding which branch to execute.

Rule conflicts grow as more business domains are added, leading to unpredictable outputs.

Testing boundaries become fuzzy: unit tests cannot assert specific business rules, integration tests depend on unstable model outputs, and performance tests cannot isolate whether latency comes from routing, business logic, or the model.

Team collaboration degrades because the same Prompt file is edited by product, operations, developers, and algorithm engineers without clear ownership.

Spring AI Alibaba Skills: The Engineering Remedy

Spring AI Alibaba Skills addresses three core problems:

Ability boundary splitting – each business capability (refund, logistics, recommendation, FAQ, etc.) becomes an independent Skill.

Execution responsibility recovery – responsibilities such as permission checks, idempotency, timeout, fallback, risk mitigation, and state changes are moved back to Java/Spring.

Standardized governance entry – Skills expose structured results, enabling per‑Skill monitoring, rate‑limiting, gray‑release, and unified auditing.

Three‑Layer Architecture

Application Control Layer : handles authentication, tenant isolation, traceId generation, timeout control, rule pre‑checks, audit logging, and feature flags.

Skill Execution Layer : each Skill runs in a clearly defined context, returns a SkillResult that distinguishes SUCCESS, BUSINESS_REJECTED, NEED_MORE_INFO, RETRYABLE_ERROR, and FATAL_ERROR.

Reply Aggregation Layer : assembles the final user‑facing response, using templates for deterministic results and falling back to LLM generation only when necessary.

Production‑Ready Code Highlights

Routing with Auditable Decision Reason

public record SkillRoute(String skillName, String routeType, double score, String reason, boolean fallback) {
    public static SkillRoute byRule(String skillName, String reason) {
        return new SkillRoute(skillName, "RULE", 1.0D, reason, false);
    }
    public static SkillRoute byEmbedding(String skillName, double score) {
        return new SkillRoute(skillName, "EMBEDDING", score, "semantic-match", false);
    }
    public static SkillRoute fallback(String reason) {
        return new SkillRoute("fallback-skill", "FALLBACK", 0D, reason, true);
    }
}

Router Implementation

@Component
public class SkillRouteEngine {
    private static final double MIN_CONFIDENCE = 0.85D;
    private final RuleIntentMatcher ruleIntentMatcher;
    private final EmbeddingSkillMatcher embeddingSkillMatcher;

    public SkillRoute route(ChatRequest request) {
        Optional<SkillRoute> strongRoute = ruleIntentMatcher.match(request.message());
        if (strongRoute.isPresent()) {
            return strongRoute.get();
        }
        List<ScoredSkill> ranked = embeddingSkillMatcher.rank(request.message());
        if (ranked.isEmpty()) {
            return SkillRoute.fallback("no-skill-ranked");
        }
        ScoredSkill best = ranked.get(0);
        if (best.score() < MIN_CONFIDENCE) {
            return SkillRoute.fallback("low-confidence-" + best.score());
        }
        return SkillRoute.byEmbedding(best.skillName(), best.score());
    }
}

SkillResult Definition

public enum SkillStatus { SUCCESS, BUSINESS_REJECTED, NEED_MORE_INFO, RETRYABLE_ERROR, FATAL_ERROR }

public record SkillResult(SkillStatus status, String code, String message, Map<String, Object> payload, boolean directReply) {
    public static SkillResult success(Map<String, Object> payload) {
        return new SkillResult(SkillStatus.SUCCESS, "OK", "success", payload, false);
    }
    public static SkillResult needMoreInfo(String message) {
        return new SkillResult(SkillStatus.NEED_MORE_INFO, "NEED_MORE_INFO", message, Map.of(), true);
    }
    public static SkillResult businessRejected(String code, String message) {
        return new SkillResult(SkillStatus.BUSINESS_REJECTED, code, message, Map.of(), true);
    }
    public static SkillResult retryable(String code, String message) {
        return new SkillResult(SkillStatus.RETRYABLE_ERROR, code, message, Map.of(), true);
    }
}

Refund Skill Example (Idempotency & State‑Machine Checks)

@Component
public class RefundSkill {
    private final OrderService orderService;
    private final RefundApplicationService refundApplicationService;

    public SkillResult execute(RefundCommand command) {
        OrderSnapshot order = orderService.load(command.userId(), command.orderId());
        if (order == null) {
            return SkillResult.businessRejected("ORDER_NOT_FOUND", "未查询到有效订单");
        }
        if (!order.refundable()) {
            return SkillResult.businessRejected("ORDER_NOT_REFUNDABLE", order.rejectReason());
        }
        RefundApplyResult result = refundApplicationService.apply(
                command.requestId(), command.userId(), command.orderId(), command.reason());
        if (result.duplicated()) {
            return SkillResult.success(Map.of("refundId", result.refundId(), "duplicated", true, "status", "PROCESSING"));
        }
        return SkillResult.success(Map.of("refundId", result.refundId(), "duplicated", false, "status", "CREATED"));
    }
}

Reply Assembler

public class ReplyAssembler {
    public String assemble(ChatRequest request, SkillResult result) {
        if (result.directReply()) {
            return result.message();
        }
        return switch (result.status()) {
            case SUCCESS -> renderSuccessByTemplate(result.payload());
            case NEED_MORE_INFO, BUSINESS_REJECTED -> result.message();
            case RETRYABLE_ERROR -> "当前服务繁忙，请稍后重试或联系人工客服。";
            case FATAL_ERROR -> "当前无法处理该请求，已为你转人工处理。";
        };
    }
}

Key Engineering Practices

Thread‑Pool Isolation : separate pools per Skill type (high‑risk write, query, low‑risk recommendation) to prevent a slow recommendation from blocking refund processing.

Result Caching : cache idempotent queries such as logistics tracking, FAQ answers, and skill description vectors with tenant‑aware keys and proper TTL.

Asynchronous Processing : split long‑running actions (e.g., complaint ticket creation, satisfaction analysis) into a fast synchronous acknowledgement and background MQ‑driven workflows.

Rate Limiting & Circuit Breaking : configure per‑Skill max concurrency, timeout, and fallback strategies (e.g., fallback‑skill for refund, hot‑item list for recommendation).

Observability : collect per‑Skill metrics – request count, success rate, business‑reject rate, fallback rate, P50/P95/P99 latency, model token usage, external service latency – to pinpoint whether slowdown is in routing, business execution, or generation.

Auditing : separate operational logs (call chain, errors, circuit state) from business audit logs (who triggered what, which order changed, decision rationale) with sensitive data redaction.

Cost Governance : monitor model token cost, cache/database cost, downstream service cost, and operational overhead; avoid unnecessary token growth by keeping the final reply Prompt small.

Comparison with Alternative Approaches

Large Prompt : quick to prototype but quickly becomes untestable, ungovernable, and costly as business rules grow.

Function/Tool Calling : offers structured tool selection but still leaves governance, idempotency, and auditing to the developer.

Spring AI Alibaba Skills : adds explicit ability boundaries, strong Java‑side responsibility recovery, and seamless integration with Spring’s existing governance ecosystem, at the cost of higher architectural complexity.

When to Adopt Skills

Multiple business domains share a single AI entry point.

Write‑heavy or high‑risk operations (refund, complaint, order creation) require idempotency, permission checks, and state‑machine validation.

Auditing, SLA, and observability are mandatory.

Team is already using Java/Spring for core services.

For pure content generation, simple Q&A, or early‑stage prototypes, a large Prompt or function calling may be sufficient.

Pre‑Launch Checklist

All permission, idempotency, and state‑change logic resides in application code.

Router enforces rule‑first matching and safe fallback on low confidence.

High‑risk Skills have dedicated timeout, rate‑limit, and circuit‑breaker configs.

Skills return structured SkillResult, not free‑form text.

Business‑failure, retryable‑error, and system‑error are distinguished.

TraceId, skillName, and routeType are logged for rapid troubleshooting.

Unique constraints and state‑machine checks are enforced at the database level.

Templates are used for deterministic high‑risk replies; LLM generation is reserved for free‑form language.

Token cost, cache hit‑rate, and model pool capacity are evaluated.

Human fallback paths are defined.

Final Engineering Verdict

Embedding business logic into Prompts works for demos but becomes a black‑box runtime that cannot be measured, controlled, or reliably scaled. Spring AI Alibaba Skills moves the control plane back to the application, enabling clear responsibility boundaries, testability, observability, and cost control, turning AI from a risky experiment into a production‑grade system capability.