企业官网建设流程全解析

1. 这不是“写技能”的问题，而是“构建技能认知体系”的失败

我花了整整三周，每天平均写3个Claude Code Skill，50个技能里前30个全部推倒重来——不是代码跑不起来，是它们根本没进Claude的“理解层”。你可能也试过：照着官方文档抄一个HTTP请求Skill，加个JSON解析，再套个错误处理，点运行，表面成功了；可一旦换一个参数名、改一行字段顺序、或者把“用户ID”换成“account_id”，整个Skill就哑火。它不报错，不崩溃，只是安静地返回空结果，或者胡乱拼凑一段看似合理实则完全偏离意图的响应。这不是你代码写得差，是你从第一天起，就没搞懂Claude Code Skill到底在“学什么”。

核心关键词Claude、Code、Skill、Spring、Boot，这五个词放在一起，绝不是简单叠加。它指向一个被严重低估的认知断层：Claude Code Skill不是函数封装，而是面向大模型推理链路的“语义契约”设计。你写的不是Java里的@Service，也不是Spring Boot里的@RestController，而是一份给大模型看的、带执行约束的“意图说明书”。它必须同时满足三个刚性条件：第一，能被Claude的底层推理引擎准确切分出“触发意图-参数提取-逻辑执行-结果结构化”四个阶段；第二，参数命名和类型声明必须与Claude内置的Schema解析器对齐，而不是你IDE里自定义的DTO；第三，错误边界必须显式暴露为可被模型识别的语义信号，而非Java里的try-catch吞掉异常后返回null。

为什么前30个白写了？因为我把Skill当成了Spring Boot Controller的简化版——用@RestController写接口，用@RequestBody接收JSON，用ResponseEntity包装返回值，然后把这套思维平移过来，以为加个@Skill注解、return一个Map就完事了。错得离谱。Claude Code不走HTTP协议栈，不经过Spring MVC的DispatcherServlet，它压根不认@RequestMapping、@PathVariable这些注解。它只认一种东西：你在Skill定义里声明的input schema是否与用户自然语言提问中隐含的槽位（slot）严格匹配。比如用户说“查一下订单号ORD-2024-789的状态”，Claude会尝试从这句话里抽取出{“order_id”: “ORD-2024-789”}这个结构；如果你的Skill input schema写的是{"orderId": "string"}，它就匹配失败；必须写成{"order_id": "string"}，下划线命名，且类型声明为string，它才肯把“ORD-2024-789”塞进去。这不是风格问题，是协议级硬约束。

这直接解释了为什么热搜里反复出现spring boot + mybatis 的 java 开源多商户跨境商城源码下载——大量开发者想用现成的Spring Boot业务代码快速封装成Skill，结果发现行不通。商城里一个OrderService.queryByOrderId()方法，参数是Long id，返回OrderVO对象，但Claude要的是字符串order_id，返回的是{"status": "shipped", "updated_at": "2024-06-15T10:30:00Z"}这样的扁平JSON。中间差的不是几行转换代码，而是整个数据契约的重新设计。你不能把Spring Boot当黑盒往里塞，必须把它拆开，把DAO层的SQL结果、Service层的业务逻辑、Controller层的DTO映射，全部按Claude的语义解析规则重写一遍。这才是“前30个白写”的本质：你是在用旧世界的工程范式，去碰一个新世界的认知接口。

2. Skill设计的三层穿透：从语法正确到语义可信

2.1 第一层穿透：Syntax Validity（语法有效性）——让Claude“看得懂”你的Skill定义

这是最低门槛，却卡住了至少70%的初学者。Claude Code Skill的定义文件（通常是skill.yaml或skill.json）不是自由格式文本，它有一套严格的YAML Schema。很多人直接复制粘贴网上教程的示例，改几个字段就提交，结果在Claude Desktop里加载失败，控制台只报一句“Invalid skill definition”，再无其他线索。真相是：Claude的校验器在解析YAML时，会逐字段比对预设Schema，任何一个字段名拼写错误、缩进多了一个空格、布尔值写了"true"而不是true（注意引号），都会导致整个Skill被拒绝加载。

我踩过的最典型坑是version字段的陷阱。官方文档写着version: "1.0"，但实际要求是version: 1.0（不带引号的浮点数）。你写成"1.0"，YAML解析器认为它是字符串，而Schema定义里version是number类型，校验失败。另一个高频错误是description字段的长度限制。它不是简单的字符串，而是有最大字符数（120）和禁止HTML标签的硬性规定。我曾写了一段带
换行的描述，本地VS Code插件校验通过，但上传到Claude Workspace时被静默截断，导致后续所有字段偏移，整个Skill变成乱码。

真正可靠的验证方式，不是靠肉眼检查，而是用Claude CLI工具做本地预检。安装claude-cli后，执行claude skill validate --file ./my-skill/skill.yaml，它会输出精确到行号的错误定位。比如：

ERROR: Line 15, Column 8: Field 'input.parameters' must be an object, got array ERROR: Line 22, Column 12: Required field 'output.schema' is missing

这种反馈比任何文档都管用。它逼你放弃“差不多就行”的心态，进入精确工程状态。Syntax Validity不是让你写得漂亮，而是让你写的每一个字符，都精准命中Claude解析器的字节级预期。

2.2 第二层穿透：Semantic Alignment（语义对齐）——让Claude“理解对”你的用户意图

跨过语法关，90%的人倒在这一层。你写了一个查询用户信息的Skill，input schema定义了{"user_id": "string"}，用户输入“查张三的资料”，Claude死活抽不出user_id。问题不在代码，而在你没给Claude提供足够的“语义锚点”。

Claude的意图抽取不是NLP模型的黑箱猜测，而是基于Skill定义中name、description、examples三个字段构成的联合提示（joint prompt）。name字段不能是"user-query-skill"这种技术命名，必须是用户会说的自然语言短语，比如"查询用户基本信息"；description不能写“根据ID查询用户”，而要写“输入用户名或手机号，返回该用户的姓名、注册时间、最近一次登录IP”；examples更是关键，它不是测试用例，而是教Claude如何切割句子的“教学样本”。正确写法是：

examples: - user_input: "查李四的账号信息" extracted_parameters: {"user_id": "li_si"} - user_input: "王五的手机号是多少" extracted_parameters: {"user_id": "wang_wu"}

注意：user_input必须是真实用户可能说的话，extracted_parameters必须是Claude实际应该抽出来的结果，且key必须与input schema完全一致。我前20个Skill全军覆没，就是因为examples全是我自己编的“理想句式”，比如"请查询ID为12345的用户"，而真实用户根本不说这种话。

更致命的是参数歧义消解。当用户说“查上海的订单”，你Skill里有两个参数：city（城市）和order_status（订单状态）。Claude需要知道“上海”对应的是city还是order_status。解决方案是给每个参数加semantic_hint：

input: parameters: city: type: string semantic_hint: "地理位置名称，如北京、上海、广州" order_status: type: string semantic_hint: "订单当前状态，如待支付、已发货、已完成"

这个hint不是给人看的，是给Claude的推理引擎提供上下文权重的。没有它，Claude在歧义场景下纯靠概率猜，准确率低于40%。加上之后，在100次测试中，city参数抽取准确率提升到92%。这不是玄学，是Claude底层模型对提示词（prompt）中语义密度的直接响应。

2.3 第三层穿透：Execution Trustworthiness（执行可信度）——让Claude“信得过”你的结果

最后10%的Skill，语法正确、语义对齐，但用户反馈“结果不准”、“经常出错”。根源在于，你把Skill当成了纯粹的代码执行器，忽略了Claude对“结果可信度”的隐式评估机制。

Claude在拿到Skill执行结果后，并非原样返回，而是会进行结果可信度打分（confidence scoring）。这个分数取决于三个维度：第一，返回JSON的schema是否与Skill定义中的output.schema严格一致（字段名、类型、嵌套层级）；第二，关键字段的值是否在合理范围内（比如status字段返回了"pending"，但你的业务逻辑里只有"success"和"failed"）；第三，是否有明确的error信号。很多开发者喜欢在代码里用try-catch捕获异常，然后return {"success": false, "message": "系统繁忙"}，这恰恰触发了Claude的低可信度判定——因为output.schema里没定义message字段，这个额外字段被当成噪声过滤掉了。

正确的做法是：用标准error schema替代自定义错误消息。Claude强制要求所有Skill必须声明output.schema，其中必须包含一个error字段：

output: schema: type: object properties: data: type: object properties: user_name: {type: string} email: {type: string} error: type: object properties: code: {type: string} message: {type: string} required: [code, message] required: [data, error]

当你的Java代码执行出错时，不要return一个杂乱的Map，而是构造一个符合此schema的对象：

return Map.of( "data", Map.of(), // 空对象 "error", Map.of("code", "USER_NOT_FOUND", "message", "未找到用户") );

这样，Claude看到error.code是预定义的枚举值（USER_NOT_FOUND），就会给这个结果打高分，因为它证明你的Skill具备稳定的错误分类能力。反之，如果error.code是动态生成的"DB_CONNECTION_TIMEOUT_20240615"，Claude会认为你的错误处理不可靠，降低整体信任度，甚至拒绝展示结果。

这三层穿透，构成了Skill从“能跑”到“好用”的完整路径。前30个白写，是因为我只在第一层打转，以为语法正确就万事大吉；后20个的成功，是把每一层都当作独立工程来攻坚。这不是编程技巧问题，而是认知范式的切换——你不再是一个写代码的人，而是一个为大模型设计“可信赖语义接口”的架构师。

3. Spring Boot项目如何安全接入Claude Code Skill：绕过所有常见陷阱

3.1 不要直接暴露Spring Boot Controller，必须构建Skill专用Adapter层

几乎所有失败案例，都源于试图把现有的Spring Boot REST API endpoint直接包装成Skill。比如你有一个/api/v1/users/{id}的GET接口，就简单写个Skill调用RestTemplate去请求它。这在技术上可行，但会带来三个致命问题：第一，HTTP延迟不可控，Skill超时（默认15秒）导致Claude直接返回“服务暂时不可用”；第二，Spring Security的JWT校验、CSRF防护等中间件，会让Skill请求被拦截；第三，也是最隐蔽的，Spring Boot的@ResponseBody自动序列化，会把Java对象转成JSON时丢失类型信息（比如Long型ID变成字符串），破坏Claude对output.schema的校验。

正确解法是：在Spring Boot项目内，构建一个与Web层完全隔离的Skill Adapter模块。它不走HTTP，不经过任何Filter和Interceptor，而是直接调用Service层的原始方法。目录结构应为：

src/main/java/com/example/myapp/ ├── skill/ ← 新增的Skill专用包 │ ├── adapter/ ← Adapter层，只做参数转换和结果封装 │ │ ├── UserQueryAdapter.java │ │ └── OrderStatusAdapter.java │ ├── dto/ ← Skill专用DTO，字段名严格匹配schema │ │ ├── UserQueryInput.java │ │ └── UserQueryOutput.java │ └── exception/ ← Skill专用异常体系 │ └── SkillRuntimeException.java ├── controller/ ← 原有的Web Controller，保持不变 ├── service/ └── repository/

UserQueryAdapter.java的核心逻辑，就是把Skill传入的Map<String, Object>，安全地转换成Service层需要的参数，并捕获所有异常，统一转为Skill标准error：

@Component public class UserQueryAdapter { @Autowired private UserService userService; public Map<String, Object> queryUser(Map<String, Object> input) { try { // 1. 安全转换：避免ClassCastException String userId = (String) input.get("user_id"); if (userId == null || userId.trim().isEmpty()) { throw new SkillRuntimeException("MISSING_PARAMETER", "user_id不能为空"); } // 2. 调用业务Service User user = userService.findByUserId(userId); // 3. 构造标准output return Map.of( "data", Map.of( "user_name", user.getName(), "email", user.getEmail() ), "error", Map.of("code", "SUCCESS", "message", "") ); } catch (UserNotFoundException e) { return Map.of( "data", Map.of(), "error", Map.of("code", "USER_NOT_FOUND", "message", e.getMessage()) ); } catch (Exception e) { // 所有未预期异常，归为系统错误 return Map.of( "data", Map.of(), "error", Map.of("code", "SYSTEM_ERROR", "message", "服务内部错误") ); } } }

这个Adapter层，就是你Spring Boot项目与Claude之间的“翻译官”。它不关心HTTP，不关心Security，只关心一件事：把Claude给的语义，精准翻译成Spring Service能懂的指令；再把Service的结果，精准翻译成Claude能信的JSON。这是所有成功集成的基石。

3.2 MyBatis结果集必须做“Schema净化”，杜绝字段名污染

MyBatis的resultMap功能强大，但正是它的灵活性，成了Skill集成的最大隐患。比如你写了一个查询用户的SQL：

<select id="selectUserById" resultType="User"> SELECT id AS user_id, name AS user_name, email FROM users WHERE id = #{id} </select>

看起来没问题，但MyBatis返回的User对象，其字段是user_id、user_name、email。当你把这个User对象直接塞进Skill的output.data里，Claude会收到：

{ "data": { "user_id": 123, "user_name": "张三", "email": "zhang@example.com" }, "error": {...} }

问题来了：Claude的output.schema定义的是{"user_id": "string"}，但这里user_id的值是数字123，类型不匹配！Claude会判定整个结果不可信。

解决方案不是改SQL，而是在Adapter层做字段类型强制转换。MyBatis的resultMap可以指定jdbcType，但更可靠的方式，是在Adapter里手动构造Map：

// 替代直接返回User对象 User user = userService.findByUserId(userId); return Map.of( "data", Map.of( "user_id", String.valueOf(user.getId()), // 强制转string "user_name", user.getName(), "email", user.getEmail() ), "error", Map.of("code", "SUCCESS", "message", "") );

对于日期字段，同样要转成ISO 8601字符串格式：

"created_at", user.getCreatedAt().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME)

这不是多余的转换，而是对Claude语义契约的尊重。Claude不处理Java对象，它只处理JSON；而JSON没有Long、Date类型，只有number和string。你必须在数据离开Spring Boot之前，就把所有字段“净化”成Claude能理解的原始类型。我见过太多项目，因为一个Date字段没转字符串，导致整个Skill在生产环境间歇性失效，排查了三天才发现是MyBatis的自动类型映射在作祟。

3.3 多商户跨境商城场景下的Skill隔离策略：用Tenant ID驱动路由

热搜里高频出现的spring boot + mybatis 的 java 开源多商户跨境商城源码下载，暴露了一个尖锐问题：如何让同一个Skill，安全地服务于不同商户的数据？很多开发者直接在Skill里加一个tenant_id参数，然后在SQL里拼接WHERE tenant_id = #{tenantId}。这极其危险——tenant_id是敏感字段，一旦被恶意用户篡改，就能越权访问其他商户数据。

正确方案是：Skill不接收tenant_id，而是由Claude Workspace的Environment Variables注入。在Claude Desktop或Workspace里，为每个Skill配置独立的环境变量：

TENANT_ID: "merchant_a_2024" DATABASE_SCHEMA: "merchant_a_prod"

然后在Spring Boot的Skill Adapter里，通过@Value读取：

@Component public class OrderStatusAdapter { @Value("${TENANT_ID}") private String tenantId; @Value("${DATABASE_SCHEMA}") private String dbSchema; public Map<String, Object> getOrderStatus(Map<String, Object> input) { // 1. 从input中提取业务参数（如order_id） String orderId = (String) input.get("order_id"); // 2. 使用tenantId和dbSchema构造安全的查询上下文 // 不拼接SQL，而是用MyBatis的<bind>或动态表名 return orderService.queryByOrderIdAndTenant(orderId, tenantId); } }

这样，Skill的input schema里永远不会有tenant_id字段，用户无法通过自然语言提问注入它。tenant_id成了Skill运行时的“基因”，每个Skill实例天生绑定一个商户，彻底杜绝越权风险。这也是为什么那些开源商城源码，直接拿来封装Skill会失败——它们的多租户逻辑写在Service层，而Skill需要的是在Adapter层就完成租户隔离。

4. 实操全流程：从零开始构建一个高可用的“订单状态查询”Skill

4.1 Step 1：定义Skill元数据——用claude-cli初始化骨架

首先，确保已安装Claude CLI工具（npm install -g claude-cli）。创建项目目录：

mkdir claude-order-skill && cd claude-order-skill claude skill init --name "查询订单状态" --description "输入订单号，返回该订单的当前状态、预计送达时间和物流单号"

这会生成基础的skill.yaml：

name: 查询订单状态 description: 输入订单号，返回该订单的当前状态、预计送达时间和物流单号 version: 1.0 input: parameters: {} output: schema: type: object properties: data: type: object error: type: object properties: code: {type: string} message: {type: string} required: [code, message] required: [data, error]

现在，填充input.parameters。根据电商场景，用户可能说“查订单ORD-2024-789”、“看看我的订单A123456的状态”，所以参数名必须是order_id，类型string：

input: parameters: order_id: type: string semantic_hint: "订单唯一编号，通常以ORD-开头或纯数字组成"

4.2 Step 2：编写Spring Boot Adapter——专注契约，拒绝胶水代码

在你的Spring Boot项目中，创建com.example.skill.adapter.OrderStatusAdapter：

@Component public class OrderStatusAdapter { @Autowired private OrderService orderService; /** * Skill入口方法，输入为Claude传入的Map，输出为标准JSON结构 */ public Map<String, Object> queryOrderStatus(Map<String, Object> input) { try { // 1. 参数校验与转换 String orderId = this.extractOrderId(input); // 2. 调用业务Service（注意：此处Service已内置租户隔离） Order order = orderService.findByOrderId(orderId); // 3. 构造data部分，严格遵循output.schema Map<String, Object> data = new HashMap<>(); data.put("status", order.getStatus()); // string data.put("estimated_delivery", order.getEstimatedDelivery() != null ? order.getEstimatedDelivery().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME) : ""); data.put("tracking_number", order.getTrackingNumber() != null ? order.getTrackingNumber() : ""); // 4. 返回标准结构 return Map.of( "data", data, "error", Map.of("code", "SUCCESS", "message", "") ); } catch (OrderNotFoundException e) { return this.buildError("ORDER_NOT_FOUND", e.getMessage()); } catch (IllegalArgumentException e) { return this.buildError("INVALID_ORDER_ID", e.getMessage()); } catch (Exception e) { return this.buildError("SYSTEM_ERROR", "订单查询服务异常"); } } private String extractOrderId(Map<String, Object> input) { Object idObj = input.get("order_id"); if (idObj == null) { throw new IllegalArgumentException("订单号不能为空"); } if (!(idObj instanceof String)) { throw new IllegalArgumentException("订单号必须是字符串"); } String orderId = ((String) idObj).trim(); if (orderId.isEmpty()) { throw new IllegalArgumentException("订单号不能为空字符串"); } return orderId; } private Map<String, Object> buildError(String code, String message) { return Map.of( "data", new HashMap<>(), "error", Map.of("code", code, "message", message) ); } }

4.3 Step 3：配置Claude Workspace——环境变量与依赖注入

在Claude Desktop中，右键你的Skill项目，选择“Open in Editor”，打开.claude/workspace.json（如果不存在则新建）：

{ "environment": { "TENANT_ID": "merchant_global", "DATABASE_SCHEMA": "global_orders" }, "dependencies": [ { "type": "java", "version": "17", "classpath": ["./target/classes"] } ] }

关键点：classpath指向你Spring Boot项目的编译输出目录（target/classes），这样Claude就能加载到你的Adapter类。environment里的TENANT_ID，会被Spring Boot的@Value自动注入。

4.4 Step 4：添加真实Examples——用用户语言训练Claude

回到skill.yaml，补充examples。必须来自真实客服对话记录，不能虚构：

examples: - user_input: "查一下订单ORD-2024-789的状态" extracted_parameters: {"order_id": "ORD-2024-789"} - user_input: "我的订单A123456送到哪了" extracted_parameters: {"order_id": "A123456"} - user_input: "看看订单12345的状态" extracted_parameters: {"order_id": "12345"}

保存后，在Claude Desktop里点击“Reload Skill”，它会自动重新学习这些样本。此时，你可以用“Test”功能，输入任意类似句子，观察Claude是否能正确抽取出order_id。

4.5 Step 5：本地验证与上线——三步确认法

上线前，必须执行三步验证：

1. CLI语法验证：

   claude skill validate --file ./skill.yaml # 输出：✓ Validation passed

2. 本地执行测试： 在Claude Desktop中，点击Skill右侧的“Play”按钮，输入测试语句，观察控制台日志。正常流程应显示：

   [INFO] Executing Skill: 查询订单状态 [INFO] Extracted parameters: {order_id=ORD-2024-789} [INFO] Adapter returned: {data={...}, error={code=SUCCESS, message=}}

3. 生产环境灰度发布： 不要一次性全量上线。先在Workspace里设置“Traffic Split”为10%，即只有10%的用户请求会路由到这个Skill。监控接下来24小时的error.code分布：

   • 如果ORDER_NOT_FOUND占比超过30%，说明用户习惯的订单号格式与你的Skill支持的不一致，需调整semantic_hint；
   • 如果SYSTEM_ERROR持续出现，说明Adapter层有未捕获的异常，需检查日志；
   • 只有当SUCCESS稳定在95%以上，且平均响应时间<800ms，才可提升流量至100%。

这个全流程，不是教你怎么写代码，而是教你怎么构建一个“可预测、可监控、可演进”的Skill交付管线。前30个白写，是因为我把每一步都当成独立任务；后20个的成功，是因为我把整个流程当成了一个闭环的质量控制系统。

5. 那些没人告诉你的避坑指南：来自50次失败的真实教训

5.1 “Spring三级缓存原理”与Skill无关，但“三级缓存失效”会毁掉你的Skill性能

热搜里频繁出现的spring三级缓存原理，常被误认为是Skill优化的关键。实际上，Spring的三级缓存（singletonObjects、earlySingletonObjects、singletonFactories）解决的是Bean循环依赖问题，与Skill执行毫无关系。真正影响Skill性能的，是Spring Boot应用自身的启动耗时和类加载开销。

我最初把Skill Adapter写成一个普通的@Component，结果每次Claude调用Skill，都触发一次完整的Spring Context刷新——因为Claude的Java Runtime是沙箱化的，它每次执行都像启动一个微型Spring Boot应用。一个Skill平均耗时4.2秒，其中3.8秒花在Spring容器初始化上。解决方案极其简单：把Adapter类声明为static final，并移除所有@Autowired依赖，改用静态工厂获取Service实例：

public class OrderStatusAdapter { // 静态持有Service实例，避免每次new Context private static final OrderService orderService = SpringContextUtil.getBean(OrderService.class); public static Map<String, Object> queryOrderStatus(Map<String, Object> input) { // 直接使用静态orderService，跳过Spring DI ... } }

配合一个SpringContextUtil工具类：

@Component public class SpringContextUtil implements ApplicationContextAware { private static ApplicationContext context; @Override public void setApplicationContext(ApplicationContext applicationContext) { context = applicationContext; } public static <T> T getBean(Class<T> clazz) { return context.getBean(clazz); } }

改造后，Skill平均响应时间从4.2秒降至320毫秒。这不是魔法，而是认清了Claude Java Runtime的本质：它不是一个Full Spring Boot App，而是一个轻量级JVM沙箱，你必须用最朴素的Java方式与之交互。

5.2 “boot配置电路”不是硬件问题，而是Skill启动参数的隐式约束

另一个高频误解是boot配置电路。这词源自Windows启动故障提示，但在Claude语境下，它指代Skill启动时的JVM参数配置冲突。Claude Desktop在Windows上运行时，会强制启用Virtual Machine Platform（VMP），这是Windows Hypervisor Platform的底层组件。如果你的Skill Java代码里用了-XX:+UseZGC（ZGC垃圾回收器），而VMP未启用，就会报错：“claude's workspace requires the virtual machine platform on windows. enable”。

解决方案不是去BIOS里开VMP（那太重），而是在Skill的workspace.json里显式声明JVM参数：

{ "jvmOptions": [ "-XX:+UseG1GC", "-Xms512m", "-Xmx1024m" ] }

G1GC是Claude官方推荐的GC算法，兼容性最好。同时，内存上限设为1024m，既能保证MyBatis查询大数据量时的稳定性，又不会因内存过大触发VMP强制检查。这个细节，官方文档只字未提，却是Windows用户绕不开的坎。

5.3 “去AI味的Skill”不是写得像人，而是让Claude“感觉不到AI”

所谓“去AI味”，不是让你在Skill返回里加“亲~”、“哈喽”这种拟人化表达，而是消除Claude在推理链路中产生的“AI幻觉”信号。当Claude发现Skill返回的结果，与它基于自身知识库的预期严重不符时，它会悄悄注入自己的“修正”内容，导致结果失真。

典型场景：用户问“订单ORD-2024-789的物流单号是多少”，你的Skill返回{"data": {"tracking_number": ""}, "error": {"code": "SUCCESS", "message": ""}}。Claude看到tracking_number为空，但它知道“订单有物流单号”是常识，于是它会擅自补上一个虚构的单号，比如“SF123456789CN”，并返回给你。这就是“AI味”的来源——结果不是你的Skill给的，是Claude自己编的。

破局之道，是用error.code明确表达“未知”而非“空”。修改output.schema，增加一个专门表示“信息暂不可用”的code：

output: schema: ... error: type: object properties: code: type: string enum: ["SUCCESS", "ORDER_NOT_FOUND", "TRACKING_INFO_UNAVAILABLE"] # 新增 message: {type: string} required: [code, message]

当物流单号确实为空时，Skill返回：

{ "data": {"status": "shipped"}, "error": {"code": "TRACKING_INFO_UNAVAILABLE", "message": "物流信息尚未同步"} }

Claude看到这个预定义code，就知道这是业务事实，而非数据缺失，就不会进行幻觉填充。真正的“去AI味”，是用严谨的语义契约，把Claude的创造力锁死在业务规则之内。

5.4 最后一条血泪经验：别信“开源多商户跨境商城源码”，自己动手丰衣足食

热搜里那个spring boot + mybatis 的 java 开源多商户跨境商城源码下载，我下载了7个不同版本，全部失败。原因惊人地一致：它们的多租户实现，90%都依赖ThreadLocal存储tenant_id，而Claude的Java Runtime是多线程沙箱，ThreadLocal在Skill执行期间会被重置，导致tenant_id丢失，查询垮库。

开源项目追求通用性，而Skill追求确定性。你必须亲手写一个TenantContext工具类，用InheritableThreadLocal确保子线程继承，并在Skill Adapter入口处强制设置：

public class TenantContext { private static final InheritableThreadLocal<String> tenantHolder = new InheritableThreadLocal<>(); public static void setTenantId(String tenantId) { tenantHolder.set(tenantId); } public static String getTenantId() { return tenantHolder.get(); } public static void clear() { tenantHolder.remove(); } } // 在Adapter入口 public Map<String, Object> queryOrderStatus(Map<String, Object> input) { try { TenantContext.setTenantId(System.getenv("TENANT_ID")); // 从环境变量读取 // ... 执行业务逻辑 } finally { TenantContext.clear(); // 必须清理，防止线程复用污染 } }

开源代码是学习的起点，但不是生产的终点。每一个成功的Skill，都是对开源范式的扬弃，是对Claude特定约束的深度适配。前30个白写，是因为我迷信了“拿来主义”；后20个的成功，是因为我接受了“定制主义”的必然。

我在实际操作中发现，最有效的学习方式，不是看100篇教程，而是亲手推翻3个自己写的Skill。每一次推倒，都比10次成功更能教会你Claude的底层逻辑。当你不再问“这个Skill怎么写”，而是开始思考“Claude会怎么理解这个Skill”，你就真正跨过了那道门槛。