利用自定义Agent-Skill实现项目JDK17升级

懒虫虫~2026-02-09 19:33

一、Agent-Skill 原理与渐进式披露解析

1.1 Agent-Skill 核心原理

在 Claude Code 中，Agent 是任务的执行者，而 Skill 是 Agent 可调用的「能力模块」------本质是将特定任务（如 JDK 升级、代码重构、依赖检查）的流程、指令、资源封装成标准化组件，Agent 可通过解析 Skill 的渐进式披露内容，按需调用对应层级的能力，无需用户手动编写完整流程。

Skill 的核心价值：将复杂任务拆解为标准化步骤，通过渐进式披露降低使用成本（新手可先获取基础指令，进阶用户可调用资源层实现自动化），同时保证任务执行的一致性和可复用性。

1.2 渐进式披露 Skill 核心结构

渐进式披露的核心逻辑是「从浅到深、按需披露」，Skill 分为三个层级，层层递进，且每个层级可独立被 Agent 调用，也可组合使用：

  1. 元数据层（基础披露）：Skill 的「身份标识」，是 Agent 和用户最先获取的基础信息，包含 Skill 的名称和描述，用于快速判断该 Skill 是否匹配当前任务。

  2. 指令层（进阶披露）：Skill 的「操作指南」，对应 skill.md 中除元数据外的核心内容，包含任务执行步骤、注意事项、前置条件等，用于指导用户或 Agent 手动完成任务。

  3. 资源层（深度披露）：Skill 的「工具支撑」，包含 reference（参考资源）和 script（可执行脚本），用于辅助 Agent 自动化完成任务，降低手动操作成本，是进阶使用的核心。

二、渐进式披露 Skill 各层级详解与使用

2.1 元数据层（name + description）

元数据是 Skill 的基础，必须放在 skill.md 的最顶部，用于定义 Skill 的核心标识，格式简洁、清晰，让 Agent 快速识别 Skill 用途。

核心要求：
  • name：唯一标识，简洁明了，包含任务核心关键词（如 Jdk8To17Upgrade）；
  • description：简要说明 Skill 的用途、适用场景，1-2 句话即可，无需冗余信息。

2.2 指令层（skill.md 核心内容）

指令层是元数据之外的核心内容，是「手动执行任务」的完整指南，也是渐进式披露的中间层级------当用户/Agent 无需自动化，仅需步骤指导时，可直接使用指令层内容。

核心内容（以任务为核心，按需补充）：
  • 前置条件：执行任务前需准备的环境、依赖（如 JDK17 安装包、项目依赖检查工具）；
  • 执行步骤：分步骤说明任务执行流程，每个步骤明确操作内容、预期结果；
  • 注意事项：常见问题、避坑点（如 JDK17 移除的 API、依赖包兼容问题）；
  • 验证方法：任务完成后，如何验证结果是否符合预期（如查看 JDK 版本、运行项目是否正常）。

2.3 资源层（reference + script）

资源层是渐进式披露的深度内容，用于辅助 Agent 自动化执行任务，减少手动操作，仅在需要自动化时披露，新手可暂不关注。资源层包含两类核心内容：reference（参考资源）和 script（可执行脚本）。

2.3.1 Reference（参考资源）

作用：提供任务相关的官方文档、参考链接、依赖说明等，Agent 可通过 reference 获取权威信息，解决执行过程中的不确定性问题（如 JDK 升级的官方迁移指南）。

使用说明：
  • 格式：按「资源名称 + 资源链接 + 用途说明」整理，清晰可查；
  • 调用：Agent 在执行任务时，若遇到不确定的步骤（如某 API 替换方案），可自动引用 reference 中的链接，获取权威指导；
  • 示例：JDK17 官方迁移指南、项目依赖兼容列表等。
2.3.2 Script（可执行脚本）

作用：封装重复、繁琐的手动操作（如批量修改配置文件、检查依赖兼容性、验证 JDK 版本），Agent 可直接调用脚本执行，实现任务自动化。

使用说明：
  • 格式：支持 Claude Code 可识别的脚本语言（如 Shell、Python、Groovy），每个脚本对应一个具体的子任务；
  • 调用：Agent 解析指令层步骤后，可自动匹配对应的 script，执行脚本完成子任务（如调用脚本批量修改 pom.xml 中的 JDK 版本）；
  • 要求：脚本需添加注释，说明脚本用途、参数（若有）、执行结果，确保可复用、可维护。

三、Skill 创建步骤（通用流程）

基于渐进式披露结构，创建 Skill 的核心流程分为 3 步，全程以「JDK8 升级到 JDK17」为例，最终生成 skill.md 文件，可直接在 Claude Code 中使用。

可以在用户的C:\Users\用户名.claude目录下，手动创建skills文件夹，存放各种skill。

步骤 1：定义元数据（基础披露）

在 skill.md 顶部，定义 Skill 的名称和描述，明确任务核心：

markdown 复制代码 
# name: Jdk8To17Upgrade
# description: 协助 Java 项目从 JDK8 升级到 JDK17，包含升级步骤、依赖兼容检查、配置修改，支持手动执行和脚本自动化

步骤 2：编写指令层（进阶披露）

在元数据下方，编写完整的手动升级指南，覆盖前置条件、步骤、注意事项、验证方法，贴合 JDK 升级场景：

markdown 复制代码 
# 说明：升级事项内容已拆分至独立文件 upgrade-details.md，Skill 会主动读取该文件（同目录下）
# 读取逻辑：Agent 加载本 Skill 时，自动检索同目录下的 upgrade-details.md，加载其中的升级事项（前置条件、步骤等）
# 若未找到该文件，Agent 会提示用户确认文件路径或创建该文件

## 升级事项文件（upgrade-details.md）读取说明
1.  文件路径：与本 skill.md 置于同一目录，确保 Agent 可正常检索；
2.  读取范围：自动加载文件中所有升级相关内容（前置条件、执行步骤、注意事项、验证方法）；
3.  异常处理：若文件不存在或格式错误，Agent 会提示用户检查文件名称、路径及 md 格式规范性。

另外，关于skill中主动指定读取其它md文件资料，比如这里的upgrade-details.md，建议统一放在当前项目根路径下，方便针对当前项目操作，相当于局部生效。

步骤 3：添加资源层（深度披露）

在指令层下方，添加 reference 和 script，辅助 Agent 自动化执行，贴合 JDK 升级场景，脚本可直接调用：

markdown 复制代码 
## 资源层（reference + script）
### reference（参考资源）
1.  JDK17 官方迁移指南：https://docs.oracle.com/en/java/javase/17/migrate/index.html
2.  Maven 支持 JDK17 配置说明：https://maven.apache.org/plugins/maven-compiler-plugin/examples/set-compiler-source-and-target.html
3.  Spring Boot 与 JDK 版本兼容表：https://spring.io/projects/spring-boot#learn
4.  jdeprscan 工具使用指南：https://docs.oracle.com/en/java/javase/17/docs/specs/man/jdeprscan.html

### script（可执行脚本）
#### 脚本 1：检查当前 JDK 版本（Shell 脚本）
# 用途：检查系统当前 JDK 版本，判断是否为 JDK8（升级前置校验核心脚本）
# 适用场景：JDK8 升级 JDK17 任务启动前，快速校验环境是否符合基础要求
# 执行方式：sh check_jdk_version.sh（需在项目根目录执行，确保环境变量生效）
# 输出结果解读：
#   - 正常输出：当前 JDK 版本+符合要求提示，退出码 0，可继续执行升级
#   - 异常输出：当前 JDK 版本+错误提示，退出码 1，需先切换至 JDK8 再执行升级
#!/bin/bash
jdk_version=$(java -version 2>&1 | awk -F '"' '/version/ {print $2}')
echo "当前 JDK 版本：$jdk_version"
if [[ $jdk_version == 1.8.* ]]; then
    echo "JDK 版本符合要求，可执行升级"
    exit 0
else
    echo "错误：当前 JDK 版本不是 8，无法执行升级"
    exit 1
fi

#### 脚本 2：修改 Maven 项目 JDK 版本（Python 脚本）
# 用途：批量修改 Maven 项目 pom.xml 中的 JDK 版本为 17（替代手动逐个修改，提升效率）
# 适用场景：多模块 Maven 项目或单模块项目，快速统一 JDK 编译版本
# 执行方式：python modify_maven_jdk.py 项目根目录（参数为必传，需准确填写项目根路径）
# 参数说明：项目根目录（如 ./demo-project），即 pom.xml 所在的最上层目录
# 异常处理：若指定目录未找到 pom.xml，会提示跳过该目录，不影响其他正常执行逻辑
# 输出结果：每个 pom.xml 的修改状态，明确提示修改完成或跳过原因
import os
import sys

def modify_pom_jdk(project_root):
    pom_path = os.path.join(project_root, "pom.xml")
    if not os.path.exists(pom_path):
        print(f"跳过：{project_root} 不是 Maven 项目（未找到 pom.xml）")
        return
    # 读取 pom.xml 内容（指定 UTF-8 编码，避免中文注释乱码）
    with open(pom_path, "r", encoding="utf-8") as f:
        content = f.read()
    # 替换 JDK 版本（精准匹配 maven.compiler.source 和 target 标签，避免误改）
    content = content.replace("<maven.compiler.source>1.8</maven.compiler.source>", "<maven.compiler.source>17</maven.compiler.source>")
    content = content.replace("<maven.compiler.target>1.8</maven.compiler.target>", "<maven.compiler.target>17</maven.compiler.target>")
    # 写入修改后的内容（覆盖原文件，建议先备份项目再执行）
    with open(pom_path, "w", encoding="utf-8") as f:
        f.write(content)
    print(f"修改完成：{pom_path} 的 JDK 版本已改为 17")

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("使用方法：python modify_maven_jdk.py 项目根目录")
        sys.exit(1)
    project_root = sys.argv[1]
    modify_pom_jdk(project_root)



#### 脚本 3：JDK 废弃 API 检查（Shell 脚本）
# 用途：调用 JDK17 自带的 jdeprscan 工具，检查项目中 JDK8 废弃、JDK17 移除的 API（核心校验脚本）
# 适用场景：JDK 版本修改完成后，快速定位需替换的不兼容 API，减少手动排查成本
# 执行方式：sh check_deprecated_api.sh 项目 classpath（参数为必传，需填写项目编译后的 class 文件路径）
# 参数说明：项目 classpath（如 target/classes），即项目编译后生成的 .class 文件所在目录
# 输出结果解读：列出所有 JDK17 中移除的 API，明确标注类路径，方便后续替换
# 补充说明：若提示 jdeprscan 命令不存在，需确认 JDK17 已配置为系统环境变量
#!/bin/bash
if [[ $# -ne 1 ]]; then
    echo "使用方法：sh check_deprecated_api.sh 项目 classpath（如 target/classes）"
    exit 1
fi
classpath=$1
echo "开始检查废弃 API，classpath：$classpath"
jdeprscan --class-path $classpath --for-removal  # --for-removal 仅检查 JDK17 中移除的 API（过滤仅废弃未移除的 API）
echo "废弃 API 检查完成，以上为需替换的 API 列表"

四、实操案例：利用 Skill 完成 JDK8 → JDK17 升级

结合上述创建的「Jdk8To17Upgrade」Skill，演示 Claude Code Agent 如何利用该 Skill 完成项目 JDK 升级，全程贴合渐进式披露逻辑，按需调用各层级内容。

4.1 步骤 1：Agent 加载 Skill 并获取元数据

Agent 首先加载 Skill 的元数据（name + description），快速识别该 Skill 可用于 JDK8 到 JDK17 的升级，确认匹配当前任务，无需加载后续层级内容（实现基础披露，降低加载成本）。

4.2 步骤 2：Agent 调用指令层，明确执行流程

Agent 解析指令层内容，获取 JDK 升级的前置条件、执行步骤、注意事项，明确任务整体流程------此时若无需自动化，Agent 可直接引导用户按步骤手动执行。

4.3 步骤 3：Agent 调用资源层，实现自动化升级

当需要自动化执行时，Agent 调用资源层的 reference 和 script，简化手动操作，提升效率：

  1. 调用 reference：当遇到依赖兼容问题（如 Spring Boot 版本不支持 JDK17）时，Agent 引用 reference 中的 Spring Boot 兼容表，自动提示用户升级 Spring Boot 版本；
  2. 调用 script：

    • 执行「检查当前 JDK 版本」脚本，确认项目当前为 JDK8，符合升级条件；

    • 执行「修改 Maven 项目 JDK 版本」脚本，批量修改 pom.xml 中的 JDK 版本，无需手动逐个修改；

    • 执行「JDK 废弃 API 检查」脚本，快速定位项目中需替换的废弃 API，减少手动检查成本。

4.4 步骤 4：验证升级结果

Agent 按照指令层的验证方法，结合脚本（如再次执行 JDK 版本检查脚本），验证升级结果：确认 JDK 版本为 17、项目编译正常、功能无异常，完成整个 JDK 升级任务。

五、完整 skill.md 输出（可直接在 Claude Code 中使用）

实际业务上这个提示词，还需要结合业务场景，不断进行微调，这里只是简单演示而已

markdown 复制代码 
# name: Jdk8To17Upgrade
# description: 协助 Java 项目从 JDK8 升级到 JDK17，包含升级步骤、依赖兼容检查、配置修改，支持手动执行和脚本自动化，可主动读取独立升级事项文件

## 升级事项文件（upgrade-details.md）读取配置
# 核心逻辑：本 Skill 启动后，会自动检索同目录下的 upgrade-details.md 文件，加载其中的升级事项内容
# 文件要求：
# 1.  文件名固定为 upgrade-details.md，不可修改（确保 Agent 能精准检索）；
# 2.  文件路径：与本 skill.md 置于同一目录，无需额外配置路径；
# 3.  格式要求：保持 Markdown 格式，核心包含「前置条件、执行步骤、注意事项、验证方法」四大模块。

## 资源层（reference + script）
### reference（参考资源）
1.  JDK17 官方迁移指南：https://docs.oracle.com/en/java/javase/17/migrate/index.html
2.  Maven 支持 JDK17 配置说明：https://maven.apache.org/plugins/maven-compiler-plugin/examples/set-compiler-source-and-target.html
3.  Spring Boot 与 JDK 版本兼容表：https://spring.io/projects/spring-boot#learn
4.  jdeprscan 工具使用指南：https://docs.oracle.com/en/java/javase/17/docs/specs/man/jdeprscan.html

### script（可执行脚本）
#### 脚本 1：检查当前 JDK 版本（Shell 脚本）
# 用途：检查系统当前 JDK 版本，判断是否为 JDK8（升级前置校验核心脚本）
# 适用场景：JDK8 升级 JDK17 任务启动前，快速校验环境是否符合基础要求
# 执行方式：sh check_jdk_version.sh（需在项目根目录执行，确保环境变量生效）
# 输出结果解读：
#   - 正常输出：当前 JDK 版本+符合要求提示，退出码 0，可继续执行升级
#   - 异常输出：当前 JDK 版本+错误提示，退出码 1，需先切换至 JDK8 再执行升级
#!/bin/bash
jdk_version=$(java -version 2>&1 | awk -F '"' '/version/ {print $2}')
echo "当前 JDK 版本：$jdk_version"
if [[ $jdk_version == 1.8.* ]]; then
    echo "JDK 版本符合要求，可执行升级"
    exit 0
else
    echo "错误：当前 JDK 版本不是 8，无法执行升级"
    exit 1
fi

#### 脚本 2：修改 Maven 项目 JDK 版本（Python 脚本）
# 用途：批量修改 Maven 项目 pom.xml 中的 JDK 版本为 17（替代手动逐个修改，提升效率）
# 适用场景：多模块 Maven 项目或单模块项目，快速统一 JDK 编译版本
# 执行方式：python modify_maven_jdk.py 项目根目录（参数为必传，需准确填写项目根路径）
# 参数说明：项目根目录（如 ./demo-project），即 pom.xml 所在的最上层目录
# 异常处理：若指定目录未找到 pom.xml，会提示跳过该目录，不影响其他正常执行逻辑
# 输出结果：每个 pom.xml 的修改状态，明确提示修改完成或跳过原因
import os
import sys

def modify_pom_jdk(project_root):
    pom_path = os.path.join(project_root, "pom.xml")
    if not os.path.exists(pom_path):
        print(f"跳过：{project_root} 不是 Maven 项目（未找到 pom.xml）")
        return
    # 读取 pom.xml 内容（指定 UTF-8 编码，避免中文注释乱码）
    with open(pom_path, "r", encoding="utf-8") as f:
        content = f.read()
    # 替换 JDK 版本（精准匹配 maven.compiler.source 和 target 标签，避免误改）
    content = content.replace("<maven.compiler.source>1.8</maven.compiler.source>", "<maven.compiler.source>17</maven.compiler.source>")
    content = content.replace("<maven.compiler.target>1.8</maven.compiler.target>", "<maven.compiler.target>17</maven.compiler.target>")
    # 写入修改后的内容（覆盖原文件，建议先备份项目再执行）
    with open(pom_path, "w", encoding="utf-8") as f:
        f.write(content)
    print(f"修改完成：{pom_path} 的 JDK 版本已改为 17")

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("使用方法：python modify_maven_jdk.py 项目根目录")
        sys.exit(1)
    project_root = sys.argv[1]
    modify_pom_jdk(project_root)

#### 脚本 3：JDK 废弃 API 检查（Shell 脚本）
# 用途：调用 JDK17 自带的 jdeprscan 工具，检查项目中 JDK8 废弃、JDK17 移除的 API（核心校验脚本）
# 适用场景：JDK 版本修改完成后，快速定位需替换的不兼容 API，减少手动排查成本
# 执行方式：sh check_deprecated_api.sh 项目 classpath（参数为必传，需填写项目编译后的 class 文件路径）
# 参数说明：项目 classpath（如 target/classes），即项目编译后生成的 .class 文件所在目录
# 输出结果解读：列出所有 JDK17 中移除的 API，明确标注类路径，方便后续替换
# 补充说明：若提示 jdeprscan 命令不存在，需确认 JDK17 已配置为系统环境变量
#!/bin/bash
if [[ $# -ne 1 ]]; then
    echo "使用方法：sh check_deprecated_api.sh 项目 classpath（如 target/classes）"
    exit 1
fi
classpath=$1
echo "开始检查废弃 API，classpath：$classpath"
jdeprscan --class-path $classpath --for-removal  # --for-removal 仅检查 JDK17 中移除的 API（过滤仅废弃未移除的 API）
echo "废弃 API 检查完成，以上为需替换的 API 列表"

---
## 独立升级事项文件：upgrade-details.md（需与 skill.md 同目录）
# 文件名：upgrade-details.md
# 用途：存储 JDK8 升级 JDK17 的核心升级事项，供 skill.md 主动读取，实现内容分离、便于维护
# 格式：Markdown 格式，不可修改核心模块名称

## 前置条件
1.  已下载并安装 JDK17（推荐 Oracle JDK17 或 OpenJDK17）；
2.  项目已备份（避免升级失败导致代码丢失，建议使用 Git 备份或压缩备份）；
3.  安装依赖检查工具（如 jdeprscan，JDK17 自带，无需额外安装）；
4.  确认项目构建工具（Maven/Gradle）版本支持 JDK17（Maven ≥ 3.8.0，Gradle ≥ 7.0，低于该版本需先升级构建工具）。

## 执行步骤
1.  检查项目当前 JDK 版本：在项目根目录执行 `java -version`，确认当前为 JDK8（若不是，需先切换至 JDK8）；
2.  配置系统环境变量：将 JDK17 的 bin 目录添加到系统 PATH，替换原 JDK8 环境，配置完成后重启终端生效；
3.  修改项目构建配置：
    - Maven 项目：修改 pom.xml 中 `maven.compiler.source` 和 `maven.compiler.target` 为 17（可调用脚本 2 批量修改）；
    - Gradle 项目：修改 build.gradle 中 `sourceCompatibility` 和 `targetCompatibility` 为 17；
4.  依赖兼容检查：执行 `jdeprscan --class-path target/classes com.example.demo`（可调用脚本 3 快速检查），检查项目中使用的废弃 API；
5.  替换废弃 API：根据 jdeprscan 输出，替换 JDK17 中移除的 API（如 sun.misc.BASE64Encoder 替换为 java.util.Base64）；
6.  编译项目：执行 `mvn clean compile`（Maven）或 `gradle clean compileJava`（Gradle），解决编译错误（主要为依赖不兼容或 API 未替换完成）；
7.  测试项目：运行项目单元测试和集成测试，确保功能正常，无运行时异常，重点测试涉及 JDK 相关的核心功能。

## 注意事项
1.  JDK17 移除了部分 JDK8 中的 API（如永久代、Unsafe 部分方法、一些内部类），需重点检查，避免遗漏未替换的 API；
2.  第三方依赖可能不兼容 JDK17，需升级依赖版本（如 Spring Boot 项目需升级到 2.7+ 或 3.0+，可参考 reference 中的兼容表）；
3.  若项目使用 Tomcat，需确保 Tomcat 版本支持 JDK17（Tomcat ≥ 9.0.60），否则会出现启动失败；
4.  升级后若出现日志异常，需检查日志框架（如 Log4j2、SLF4J）版本，确保兼容 JDK17，建议升级至最新稳定版；
5.  多模块 Maven 项目，需确保所有子模块的 pom.xml 都修改为 JDK17，避免模块间版本不一致导致编译失败。

## 验证方法
1.  执行 `java -version`，确认输出为 JDK17 版本（如 17.0.9），说明环境配置生效；
2.  执行项目构建命令（mvn clean compile 或 gradle clean compileJava），确保无编译错误；
3.  启动项目，访问接口或执行核心功能，确认无运行时异常，项目能正常提供服务；
4.  查看项目日志，无 JDK 相关的警告或错误信息，尤其是废弃 API、依赖不兼容相关的日志；
5.  执行项目单元测试，确保测试通过率 100%，验证核心功能无异常。

六、总结

Claude Code 中渐进式披露 Agent-Skill 的核心是「按需披露、层层递进」，从元数据（快速识别）→ 指令层（手动执行）→ 资源层（自动化辅助），既降低了新手使用门槛，也满足了进阶用户的自动化需求。

本文通过 JDK8 升级到 JDK17 的实操案例，完整演示了 Skill 的创建、各层级使用及 Agent 调用流程，生成的 skill.md 可直接在 Claude Code 中加载使用。实际使用中，可根据具体任务（如代码重构、依赖升级），参考本文流程，创建自定义的渐进式披露 Skill，提升 Agent 执行复杂任务的效率和一致性。

相关推荐
AI架构全栈开发实战笔记8 小时前
Eureka 在大数据环境中的性能优化技巧
大数据·ai·eureka·性能优化
大厂资深架构师8 小时前
Spring Cloud Eureka在后端系统中的服务剔除策略
spring·spring cloud·ai·eureka
AI架构全栈开发实战笔记8 小时前
Eureka 对大数据领域服务依赖关系的梳理
大数据·ai·云原生·eureka
阿杰学AI9 小时前
AI核心知识91——大语言模型之 Transformer 架构（简洁且通俗易懂版）
人工智能·深度学习·ai·语言模型·自然语言处理·aigc·transformer
shengnan_wsn12 小时前
【一】【ai基础】【大模型和智能体初识】
ai
nimadan1212 小时前
**AI仿真人剧制作工具2025推荐，解锁沉浸式内容创作新范
ai
阿沐的硅基世界13 小时前
OpenClaw记忆层详解
ai
___波子 Pro Max.14 小时前
AI与AGI的区别及未来展望
ai·agi
kali-Myon14 小时前
2025春秋杯网络安全联赛冬季赛-day2
python·安全·web安全·ai·php·pwn·ctf
热门推荐
01GitHub 镜像站点02Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services03openclaw配置教程（linux+局域网ollama）04UV安装并设置国内源05Linux下V2Ray安装配置指南06AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南07openclaw使用nginx反代部署过程 与disconnected (1008): pairing required解决08在Trae中使用Pencil MCP09Claude Code Skills 实用使用手册10OpenClaw Chrome扩展使用教程 - 浏览器中继控制