SKILL接口对接实战指南：手写文档与高效集成教程

在多平台对接开发中，一个高频场景是：依据外部合作方提供的接口文档，将内部数据推送至对方平台。当对接方数量增加，重复编写适配代码不仅效率低下，代码质量也难以统一。解决方案是将这一流程标准化、自动化。

通过为AI助手编写一个定制化Skill，我们可以固化对接流程，显著提升生成代码的准确性与一致性。下文将详细拆解如何从零构建一个用于接口文档对接的Skill。

一、业务背景

需求核心明确：

• 核心任务是向指定外部平台发送数据，对方会提供详细的接口文档，开发工作即基于此文档完成数据对接。
• 痛点在于，下游平台往往不止一个。每个平台都有独立的接口规范与鉴权方式，若每次都手动编码，耗时且易错。

因此，目标是将这套对接流程提炼为可复用的Skill。这为AI生成代码提供了明确的“行动指南”，确保输出结果更精准、更符合工程规范。

二、Skill基本概念

在动手之前，需明确Skill的定义。

1. Claude官方定义

Skill是一组打包好的指令集。其核心价值在于“一次定义，持续生效”。你无需在每次对话中重复解释编码偏好、项目结构或特定流程，只需通过Skill定义一次，AI便能在后续相关任务中自动应用这些知识。

2. 文件结构

一个完整的Skill通常包含以下目录结构：

skill-name/
├── SKILL.md          # 必需 - 核心指令文件
├── scripts/          # 可选 - 可执行脚本
│   └── validate.py
├── references/       # 可选 - 参考文档
│   └── api-guide.md
└── assets/           # 可选 - 模板等资源文件
    └── template.md

当然，这并非铁律。对于简单的Skill，例如本次的接口对接，仅需一个SKILL.md文件即可。

3. 渐进式披露（核心设计原则）

这是设计Skill时的关键理念，旨在高效引导AI：

• 第一级（YAML frontmatter）：作为Skill的“摘要”，告知AI此Skill的用途及触发场景。
• 第二级（SKILL.md正文）：包含完整、详细的操作指令与指南，是Skill的核心内容。
• 第三级（链接文件）：Skill目录下捆绑的其他文件，如具体的API文档、代码模板等，供AI在需要时按需加载。

理解上述概念后，即可进入实战环节。

三、Skill实战——基础信息文件

在编写核心的SKILL.md前，需准备一个“配料表”——基础信息文件。它并非Skill的强制组成部分，但在接口对接场景下至关重要。

1. 概念

可将其理解为单次对接任务的“定制化配置清单”。Skill本身定义了通用的对接能力（“如何做”），而此基础信息文件则定义了本次对接的具体属性（“对谁做”、“使用何参数”）。

我们通常将其命名为generate.md，其中填充本次对接的所有关键信息。

2. generate.md 示例

该文件结构清晰，直接告知AI需关注的重点：

## 1. 基础信息
- 接口文档：xxx对外开放接口文档V1.1.pdf
- ReceiverId：1xxxx (每个对接平台的唯一标识)
- 类名：xxxService
- 车辆类型：单车
- config命名：xxx_config

## 2. 鉴权相关
- 签名算法：接口文档中第二部分
- 鉴权接口：[具体接口地址]

## 3. 接口对接 (来源Kafka实时数据消息)
- 3.3 推送订单数据 —— handleOrder

## 4. 接口对接 (来源定时任务)
- 3.4 定时推送定位数据 —— uploadLocation

## 5. 参考Service
- xxxService (一个已有的、风格类似的Service类，供AI参考)

其中，“参考Service”一项尤为重要。若项目中存在类似的对接实现，AI参考它来生成新代码，准确率将大幅提升。

四、Skill实战——SKILL.md

核心部分。SKILL.md是Skill的灵魂，需清晰、无歧义地指导AI完成任务。

1. front matter：定义触发条件

此部分必须定义，否则AI无法知晓何时使用此Skill。

---
name: interface-documentation
description: 当用户需要新增、生成或修改平台对接Service类，或要求根据接口文档和generate.md文件实现平台对接时，使用此skill。
---

2. 名称与适用场景

为Skill命名，并明确其边界。

# 接口文档对接 Skill

**适用场景：**
当用户的需求符合以下任一情况时，应使用本skill：
- 提到“平台对接”、“接口文档对接”、“生成对接类”
- 提到“根据接口文档生成接入代码”
- 提到 `generate.md` 文件
- 提到特定工程仓库中的平台对接实现

**不适用场景：**
如果只是普通的Ja va代码修改、测试修复或文档整理，与接口文档对接流程无关，则不要强行使用本skill。

3. 核心目标与输入输出

明确告知AI最终目标及所需“原材料”。

核心目标：根据模板文件与接口文档，生成一套完全符合现有工程规范的平台对接代码。关键在于：定位正确的入口与参考实现，沿用现有的代码模式（Service, Task, Plugin等），并严格依据接口文档组织数据报文。

输入：主要包括三部分： 1. 模板文件：即上文提到的generate.md，是首要依据。 2. 接口文档：以generate.md中指定的名称为准，可能是PDF、Word等格式，需先解析出关键字段与说明。 3. 接入基础信息：从模板文件中提取，包括ReceiverId、Service类名、车辆类型、配置项命名、鉴权方式、待对接接口列表以及参考Service。

输出：最终应产出一系列符合项目规范的代码文件，可能包括： - 在ReceiverEnum中新增枚举项 - 新的Service类、常量类(constant) - 新的定时任务类(task)、鉴权插件类(plugin) - 必要的枚举、参数、模型类 - 确保Spring/Dubbo/任务调度等基础注册代码完备 - 集成日志、车辆类型校验、坐标转换等标准逻辑

4. 行为指南：给AI一个明确的“行动清单”

这是确保生成结果可控的关键。需规定AI的执行步骤与优先级。

### 1. 先读模板，再读接口文档
优先从 `generate.md` 中读取所有定制化信息。如果模板与接口文档内容冲突，以接口文档的字段和协议为准，但必须在生成结果中明确说明冲突点。

### 2. 先找参考实现，再开始写代码
动笔前，先在代码仓库中搜索同类型、同风格的已有实现进行参考，特别是模板中明确指定的参考Service。这能最大程度保证代码风格统一。

### 3. 先补基础注册项
建议按以下顺序搭建代码骨架：
1. 在 `ReceiverEnum` 中新增receiver。
2. 创建Service类。
3. 创建Apollo配置变量。
4. 创建常量类。
先有结构，再填充细节。

### 4. 鉴权逻辑处理
- **签名算法**：严格按接口文档实现，复用项目现有工具，不发明新字段。
- **鉴权接口**：如需通过接口获取token，则实现 `ServiceTokenPlugin`，并复用现有的token获取、刷新、缓存模式。
- **注意**：如果模板未说明鉴权机制，不要擅自添加。

### 5. 实现实时数据对接
根据模板中“来源Kafka实时数据消息”的列表逐一实现。注意：
- 方法名通常以 `handle...` 开头。
- 方法体内逻辑顺序固定：先校验车辆类型（单车/电单），再进行数据转换和接口调用。

### 6. 实现定时任务对接
根据模板中“来源定时任务”的列表实现。推荐步骤：先创建Task类，再从数据库按规则查询数据，最后批量调用封装好的上传方法。

5. 评测标准与失败处理

最后，需为AI提供一套“检查清单”与“安全护栏”。

评测标准（完成后至少检查）： 1. Receiver枚举是否已注册。 2. Service类能否被Spring扫描到。 3. 定时任务是否已正确注册。 4. 单车/电单类型判断是否准确。 5. 上报字段是否严格匹配文档必填项。 6. 坐标转换是否符合要求。 7. 鉴权逻辑是否与文档一致。 8. 日志、缓存Key等是否符合项目风格。

失败处理（信息不足时）： 切忌“硬猜”。正确做法是： 1. 优先完成可确定的结构骨架。 2. 清晰标注出缺失或不确定的信息。 3. 只实现仓库和模板中能够确认的部分。 尤其在接口文档无法读取、签名规则缺失、字段定义不完整或参考实现差异过大时，切勿强行生成完整协议。

6. 一句话原则

用一句话总结整个Skill的核心精神：

**先按 `generate.md` 定边界，再按接口文档定字段，最后严格沿用项目现有 Service 风格落地实现。**

五、总结

通过这样一套手写的Skill，平台对接的代码生成准确度能从直接处理文档的50%-60%，提升至80%以上。剩余的20%可能涉及非常规的边界情况或复杂业务逻辑，但核心骨架与大部分样板代码均已正确生成，极大减少了人工检查与修改的工作量。

当然，此Skill仍有优化空间。例如，可考虑将其拆分为更细粒度的Skill，如“接口文档解析”与“Service代码生成”分离，以提升组合灵活性。

最佳实践分享：当你有一个清晰构想时，可先将完整思路写出，然后让AI基于此思路生成Skill草案。这样产出的Skill往往更契合AI自身的“思维习惯”，效果有时优于完全手动编写。

来源：互联网