From 36e019b02ff40e05b81af23705bbfb26f449bf6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=89=E6=BA=AA?= Date: Tue, 11 Aug 2026 16:30:46 +0800 Subject: [PATCH 1/3] refactor(skills): standardize Arthas skill layout --- .../arthas/skills/arthas-cpu-high}/SKILL.md | 2 +- .../arthas/skills/arthas-eagleeye-traceid}/SKILL.md | 2 +- .../skills/arthas-springcontext-issues-resolve}/SKILL.md | 3 ++- {skills => plugins/arthas/skills/arthas}/SKILL.md | 7 ++++--- 4 files changed, 8 insertions(+), 6 deletions(-) rename {skills/cpu-high => plugins/arthas/skills/arthas-cpu-high}/SKILL.md (98%) rename {skills/eagleeye-traceid => plugins/arthas/skills/arthas-eagleeye-traceid}/SKILL.md (99%) rename {skills/spring-context => plugins/arthas/skills/arthas-springcontext-issues-resolve}/SKILL.md (99%) rename {skills => plugins/arthas/skills/arthas}/SKILL.md (93%) diff --git a/skills/cpu-high/SKILL.md b/plugins/arthas/skills/arthas-cpu-high/SKILL.md similarity index 98% rename from skills/cpu-high/SKILL.md rename to plugins/arthas/skills/arthas-cpu-high/SKILL.md index 5ef7388d4ae..9767f4e6fc3 100644 --- a/skills/cpu-high/SKILL.md +++ b/plugins/arthas/skills/arthas-cpu-high/SKILL.md @@ -1,6 +1,7 @@ --- name: arthas-cpu-high description: 排查 JVM / 应用 CPU 飙高（线程定位 + 代码路径分析） +license: Apache-2.0 --- # JVM CPU 飙高排查指南（Arthas） @@ -36,4 +37,3 @@ description: 排查 JVM / 应用 CPU 飙高（线程定位 + 代码路径分析 - 现象与证据：dashboard 摘要 + topN 线程堆栈关键片段 - 初步结论：CPU 主要消耗在什么类型的逻辑（计算/锁/GC/日志等） - 下一步：建议进一步 trace/watch 的目标方法（给出类名+方法名的精确范围），或建议用户提供主包名/关键接口信息以继续收敛 - diff --git a/skills/eagleeye-traceid/SKILL.md b/plugins/arthas/skills/arthas-eagleeye-traceid/SKILL.md similarity index 99% rename from skills/eagleeye-traceid/SKILL.md rename to plugins/arthas/skills/arthas-eagleeye-traceid/SKILL.md index fbcef757642..d655eea3a38 100644 --- a/skills/eagleeye-traceid/SKILL.md +++ b/plugins/arthas/skills/arthas-eagleeye-traceid/SKILL.md @@ -1,6 +1,7 @@ --- name: arthas-eagleeye-traceid description: 使用 Arthas 的 watch/trace 获取 EagleEye traceId / 获取请求的 traceId +license: Apache-2.0 --- # 获取 EagleEye traceId（Arthas） @@ -77,4 +78,3 @@ trace <类全名> <方法名> -n 5 ## 扩展 - 其他分布式追踪系统的 traceId、或 ThreadLocal 里的值，也可以用类似方式在 `watch` 的 OGNL 表达式中读取。 - diff --git a/skills/spring-context/SKILL.md b/plugins/arthas/skills/arthas-springcontext-issues-resolve/SKILL.md similarity index 99% rename from skills/spring-context/SKILL.md rename to plugins/arthas/skills/arthas-springcontext-issues-resolve/SKILL.md index 36bdadfc022..45a0ea24ee5 100644 --- a/skills/spring-context/SKILL.md +++ b/plugins/arthas/skills/arthas-springcontext-issues-resolve/SKILL.md @@ -1,6 +1,7 @@ --- name: arthas-springcontext-issues-resolve description: 排查 Spring ApplicationContext / Bean / 配置注入等问题 +license: Apache-2.0 --- # Spring Context / Bean 排查指南 @@ -97,4 +98,4 @@ vmtool --action getInstances --className org.springframework.context.support.Abs ```bash vmtool --action getInstances --className org.springframework.context.support.AbstractApplicationContext -l 1 --express '#ctx=instances[0], #bf=#ctx.getBeanFactory(), #bd=#bf.getBeanDefinition("fooService")' -``` \ No newline at end of file +``` diff --git a/skills/SKILL.md b/plugins/arthas/skills/arthas/SKILL.md similarity index 93% rename from skills/SKILL.md rename to plugins/arthas/skills/arthas/SKILL.md index 19cc2888079..82b5ca373d7 100644 --- a/skills/SKILL.md +++ b/plugins/arthas/skills/arthas/SKILL.md @@ -1,6 +1,7 @@ --- name: arthas description: arthas 诊断 java应用，jvm问题 skill +license: Apache-2.0 --- # Arthas 诊断 Skill @@ -20,7 +21,7 @@ Arthas 是 Java 应用在线诊断工具，本 Skill 包含多个子场景的诊 ### 1. CPU 飙高排查 -**文件：** `cpu-high/SKILL.md` +**文件：** `../arthas-cpu-high/SKILL.md` 适用场景：机器 CPU 飙高、应用响应变慢、负载异常升高。 @@ -35,7 +36,7 @@ Arthas 是 Java 应用在线诊断工具，本 Skill 包含多个子场景的诊 ### 2. 获取 EagleEye traceId -**文件：** `eagleeye-traceid/SKILL.md` +**文件：** `../arthas-eagleeye-traceid/SKILL.md` 适用场景：需要在不改代码的情况下，获取线上请求的 EagleEye traceId，用于关联日志 / 链路分析。 @@ -50,7 +51,7 @@ Arthas 是 Java 应用在线诊断工具，本 Skill 包含多个子场景的诊 ### 3. Spring Context / Bean 排查 -**文件：** `spring-context/SKILL.md` +**文件：** `../arthas-springcontext-issues-resolve/SKILL.md` 适用场景：排查 Spring ApplicationContext / Bean / 配置注入等问题。 From 1da166c0c48dd8f914b31b5aba2a97466539f797 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=89=E6=BA=AA?= Date: Tue, 11 Aug 2026 16:31:15 +0800 Subject: [PATCH 2/3] feat(plugin): package Arthas skills for Codex --- .agents/plugins/marketplace.json | 20 +++++++++++++++++ plugins/arthas/.codex-plugin/plugin.json | 28 ++++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 .agents/plugins/marketplace.json create mode 100644 plugins/arthas/.codex-plugin/plugin.json diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 00000000000..674286edd32 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "arthas-plugins", + "interface": { + "displayName": "Arthas Plugins" + }, + "plugins": [ + { + "name": "arthas", + "source": { + "source": "local", + "path": "./plugins/arthas" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Developer Tools" + } + ] +} diff --git a/plugins/arthas/.codex-plugin/plugin.json b/plugins/arthas/.codex-plugin/plugin.json new file mode 100644 index 00000000000..d82305af76e --- /dev/null +++ b/plugins/arthas/.codex-plugin/plugin.json @@ -0,0 +1,28 @@ +{ + "name": "arthas", + "version": "0.1.0", + "description": "Guided Arthas workflows for diagnosing Java and JVM issues.", + "author": { + "name": "Alibaba Arthas", + "url": "https://github.com/alibaba/arthas" + }, + "homepage": "https://arthas.aliyun.com/", + "repository": "https://github.com/alibaba/arthas", + "license": "Apache-2.0", + "keywords": [ + "arthas", + "java", + "jvm", + "diagnostics" + ], + "skills": "./skills/", + "interface": { + "displayName": "Arthas Diagnostics", + "shortDescription": "Diagnose Java and JVM issues with Arthas.", + "longDescription": "Use guided Arthas workflows to investigate CPU spikes, EagleEye trace IDs, and Spring context or bean issues.", + "developerName": "Alibaba Arthas", + "category": "Developer Tools", + "capabilities": [], + "defaultPrompt": "Help me diagnose a Java application with Arthas." + } +} From eda422866a49b9ab50f6daa188adc8aba38665b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=89=E6=BA=AA?= Date: Tue, 11 Aug 2026 16:33:32 +0800 Subject: [PATCH 3/3] docs(skills): document installation options --- README.md | 1 + README_CN.md | 1 + plugins/arthas/README.md | 89 +++++++++++++++++++++++++++++++++++++ plugins/arthas/README_CN.md | 89 +++++++++++++++++++++++++++++++++++++ 4 files changed, 180 insertions(+) create mode 100644 plugins/arthas/README.md create mode 100644 plugins/arthas/README_CN.md diff --git a/README.md b/README.md index cb04517f247..288bf145b08 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,7 @@ You can enter its interactive interface by executing `as.sh`, or execute `as.sh * [Quick start](https://arthas.aliyun.com/doc/en/quick-start.html) * [Advanced usage](https://arthas.aliyun.com/doc/en/advanced-use.html) * [Commands](https://arthas.aliyun.com/doc/en/commands.html) +* [AI agent skills installation](plugins/arthas/README.md) * [WebConsole](https://arthas.aliyun.com/doc/en/web-console.html) * [Docker](https://arthas.aliyun.com/doc/en/docker.html) * [Arthas Spring Boot Starter](https://arthas.aliyun.com/doc/en/spring-boot-starter.html) diff --git a/README_CN.md b/README_CN.md index 645e3c92431..66a285ff2c5 100644 --- a/README_CN.md +++ b/README_CN.md @@ -76,6 +76,7 @@ curl -L https://arthas.aliyun.com/install.sh | sh * [快速入门](https://arthas.aliyun.com/doc/quick-start.html) * [进阶使用](https://arthas.aliyun.com/doc/advanced-use.html) * [命令列表](https://arthas.aliyun.com/doc/commands.html) +* [AI Agent Skills 安装](plugins/arthas/README_CN.md) * [WebConsole](https://arthas.aliyun.com/doc/web-console.html) * [Docker](https://arthas.aliyun.com/doc/docker.html) * [Arthas Spring Boot Starter](https://arthas.aliyun.com/doc/spring-boot-starter.html) diff --git a/plugins/arthas/README.md b/plugins/arthas/README.md new file mode 100644 index 00000000000..552f4b4078d --- /dev/null +++ b/plugins/arthas/README.md @@ -0,0 +1,89 @@ +# Arthas AI Agent Skills + +Arthas provides reusable skills that guide AI coding agents through common Java and JVM diagnostic workflows. + +[中文说明](README_CN.md) + +## Available skills + +| Skill | Purpose | +| --- | --- | +| `arthas` | Routes a diagnostic request to the most relevant Arthas workflow. | +| `arthas-cpu-high` | Investigates high CPU usage from JVM state to hot threads and methods. | +| `arthas-eagleeye-traceid` | Captures an EagleEye trace ID with bounded `watch` or `trace` commands. | +| `arthas-springcontext-issues-resolve` | Investigates Spring contexts, beans, and configuration values. | + +The repository uses one canonical skill tree at `plugins/arthas/skills/`. The same files can be installed as a Codex plugin, with the cross-agent `skills` CLI, or with the GitHub `gh-skill` extension. + +## Option 1: Codex plugin + +This option installs all four skills together and makes the plugin available in Codex's plugin directory. + +Add the repository marketplace with a sparse checkout, then install the plugin: + +```bash +codex plugin marketplace add alibaba/arthas \ + --sparse .agents/plugins \ + --sparse plugins/arthas +codex plugin add arthas@arthas-plugins +``` + +Verify the installation: + +```bash +codex plugin list --json +``` + +You can also open the Plugins Directory in the ChatGPT desktop app, choose **Arthas Plugins**, and install **Arthas Diagnostics**. + +See the official [plugin packaging guide](https://developers.openai.com/plugins/build/plugins) and [Codex plugin commands](https://learn.chatgpt.com/docs/developer-commands#codex-plugin) for more details. + +## Option 2: `skills` CLI + +Use this option when you want the same skills across Codex, Claude Code, Cursor, or another supported agent. + +List the skills without installing them: + +```bash +npx skills add alibaba/arthas --list +``` + +Install every Arthas skill for Codex in the current project: + +```bash +npx skills add alibaba/arthas --agent codex --skill '*' --yes +``` + +Add `--global` to make them available to Codex in every project. To install only one workflow, replace `'*'` with its skill name, for example `arthas-cpu-high`. + +Update project-scoped installations with: + +```bash +npx skills update --project --yes +``` + +## Option 3: GitHub `gh-skill` + +Use this option when you prefer GitHub-native discovery, preview, version pinning, and updates. + +Browse the available skills interactively: + +```bash +gh skill install alibaba/arthas +``` + +Preview and install one workflow directly: + +```bash +gh skill preview alibaba/arthas arthas-cpu-high +gh skill install alibaba/arthas arthas-cpu-high \ + --agent codex \ + --scope user +``` + +Check for updates without changing local files, then apply all available updates: + +```bash +gh skill update --dry-run +gh skill update --all +``` diff --git a/plugins/arthas/README_CN.md b/plugins/arthas/README_CN.md new file mode 100644 index 00000000000..1ab98511bfa --- /dev/null +++ b/plugins/arthas/README_CN.md @@ -0,0 +1,89 @@ +# Arthas AI Agent Skills + +Arthas 提供了一组可复用的 Skill，帮助 AI 编码 Agent 按规范流程诊断常见的 Java 与 JVM 问题。 + +[English](README.md) + +## 可用 Skill + +| Skill | 用途 | +| --- | --- | +| `arthas` | 根据问题描述选择最合适的 Arthas 诊断流程。 | +| `arthas-cpu-high` | 从 JVM 概况、热点线程到热点方法，排查 CPU 飙高。 | +| `arthas-eagleeye-traceid` | 使用有限次数的 `watch` 或 `trace` 获取 EagleEye traceId。 | +| `arthas-springcontext-issues-resolve` | 排查 Spring Context、Bean 和配置项问题。 | + +仓库以 `plugins/arthas/skills/` 作为唯一 Skill 源目录。同一份文件既可以作为 Codex Plugin 安装，也兼容跨 Agent 的 `skills` CLI 和 GitHub `gh-skill` 扩展。 + +## 方式一：Codex Plugin + +这种方式会一次安装全部四个 Skill，并在 Codex 的插件目录中展示该插件。 + +先用稀疏检出添加仓库 Marketplace，再安装插件： + +```bash +codex plugin marketplace add alibaba/arthas \ + --sparse .agents/plugins \ + --sparse plugins/arthas +codex plugin add arthas@arthas-plugins +``` + +检查安装结果： + +```bash +codex plugin list --json +``` + +也可以在 ChatGPT 桌面端打开插件目录，选择 **Arthas Plugins**，再安装 **Arthas Diagnostics**。 + +更多信息请参考官方的 [Plugin 打包指南](https://developers.openai.com/plugins/build/plugins)和 [Codex Plugin 命令](https://learn.chatgpt.com/docs/developer-commands#codex-plugin)。 + +## 方式二：`skills` CLI + +需要在 Codex、Claude Code、Cursor 或其他兼容 Agent 之间复用 Skill 时，可以选择这种方式。 + +只查看仓库中的 Skill，不执行安装： + +```bash +npx skills add alibaba/arthas --list +``` + +为当前项目的 Codex 安装全部 Arthas Skill： + +```bash +npx skills add alibaba/arthas --agent codex --skill '*' --yes +``` + +追加 `--global` 可以让它们在 Codex 的所有项目中生效。只安装一个诊断流程时，把 `'*'` 替换成对应 Skill 名称，例如 `arthas-cpu-high`。 + +更新项目级安装： + +```bash +npx skills update --project --yes +``` + +## 方式三：GitHub `gh-skill` + +希望使用 GitHub 原生的发现、预览、版本锁定和更新能力时，可以选择这种方式。 + +交互式浏览可用 Skill： + +```bash +gh skill install alibaba/arthas +``` + +直接预览并安装一个诊断流程： + +```bash +gh skill preview alibaba/arthas arthas-cpu-high +gh skill install alibaba/arthas arthas-cpu-high \ + --agent codex \ + --scope user +``` + +先只读检查更新，再应用全部可用更新： + +```bash +gh skill update --dry-run +gh skill update --all +```