一、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 的名称和描述，明确任务核心：

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

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

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

# 说明：升级事项内容已拆分至独立文件 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 升级场景，脚本可直接调用：

## 资源层（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 中使用）

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

# 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
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

函数调用：AI原生应用领域的核心驱动力

2023年，OpenAI推出Function Call（函数调用）能力，彻底改变了这一局面。AI原生应用（AI-Native App）的本质，就是以大模型为大脑，通过函数调用连接现实世界的工具/数据，实现“意图理解→任务执行→结果反馈”的完整闭环。用户需求：“我明天要去北京出差，帮我查天气+订酒店”；AI的行动：理解意图：需要调用“天气查询”和“酒店预订”两个工具；函数调用：先调用get_weat

avatar 2048 AI社区

2026最新热门AI编程工具推荐（10款权威盘点）

随着AI技术的飞速迭代，AI编程工具已成为开发者提升效率的核心利器，无需死记语法、无需反复调试，一款优质工具就能轻松搞定从需求分析到部署上线的全流程。以下为大家盘点2026年最新热门、实测好用的10款AI编程工具，干货拉满，首选必看！

avatar 2048 AI社区
cover

人工智能在医疗领域的应用与研究论文写作实操：AI辅助快速完成框架+正文创作

avatar 2048 AI社区