docs: update dubbo-go agent skills

Author: Oxidaner

.agents/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "dubbo-go-agent-skills",
+  "description": "Agent skills bundled with Apache dubbo-go for framework users and contributors",
+  "owner": {
+    "name": "Apache Dubbo"
+  },
+  "plugins": [
+    {
+      "name": "dubbo-go",
+      "description": "AI skills for Apache dubbo-go contributors and v3 users: repository development, scaffolding, extensions, Java interop, debugging, guidance, and migration.",
+      "category": "development",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/apache/dubbo-go.git"
+      },
+      "homepage": "https://github.com/apache/dubbo-go/tree/develop/.agents"
+    }
+  ]
+}

.agents/.codex/INSTALL.md

@@ -0,0 +1,59 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Installing dubbo-go Agent Skills for Codex
+
+## Quick install
+
+Tell Codex:
+
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/apache/dubbo-go/main/.agents/.codex/INSTALL.md
+```
+
+## Manual installation
+
+Install the skills globally when you want Codex to use them outside an Apache dubbo-go checkout.
+
+```bash
+git clone https://github.com/apache/dubbo-go.git ~/.codex/dubbo-go
+mkdir -p ~/.agents/skills
+ln -s ~/.codex/dubbo-go/.agents/skills ~/.agents/skills/dubbo-go
+```
+
+Restart Codex.
+
+### Windows
+
+```powershell
+git clone https://github.com/apache/dubbo-go.git "$env:USERPROFILE\.codex\dubbo-go"
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
+cmd /c mklink /J "$env:USERPROFILE\.agents\skills\dubbo-go" "$env:USERPROFILE\.codex\dubbo-go\.agents\skills"
+```
+
+## Updating
+
+```bash
+cd ~/.codex/dubbo-go
+git pull --ff-only
+```
+
+Restart Codex after updating.
+
+## Usage
+
+The installed skills cover repository development, scaffolding, extensions, Java interoperability, debugging, guidance, and migration for dubbo-go.

.agents/.gitignore

@@ -0,0 +1,20 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+node_modules/
+.DS_Store
+*.log

.agents/.opencode/plugins/dubbo-go-agent-skills.js

@@ -0,0 +1,46 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ * 
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = join(__dirname, '..', '..');
+
+const skillNames = ['development', 'scaffolding', 'extensions', 'java-interop', 'debug', 'guide', 'migrate'];
+
+export const skills = skillNames.map(name => {
+  const skillPath = join(pluginRoot, 'skills', name, 'SKILL.md');
+  let content;
+  try {
+    content = readFileSync(skillPath, 'utf-8');
+  } catch (err) {
+    throw new Error(`dubbo-go-agent-skills: failed to read ${skillPath}: ${err.message}`);
+  }
+  // Parse frontmatter (tolerates both LF and CRLF line endings)
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  const frontmatter = match ? match[1] : '';
+  const body = match ? match[2] : content;
+  const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+  const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+  return {
+    name: nameMatch ? nameMatch[1].trim() : `dubbo-go:${name}`,
+    description: descMatch ? descMatch[1].trim() : '',
+    content: body,
+  };
+});

.agents/GEMINI.md

@@ -0,0 +1,24 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+@./skills/development/SKILL.md
+@./skills/scaffolding/SKILL.md
+@./skills/extensions/SKILL.md
+@./skills/java-interop/SKILL.md
+@./skills/debug/SKILL.md
+@./skills/guide/SKILL.md
+@./skills/migrate/SKILL.md

.agents/README.md

@@ -0,0 +1,86 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# dubbo-go Agent Skills
+
+[English](README.md) | [中文](README_CN.md)
+
+This directory contains AI agent skills bundled with [Apache dubbo-go](https://github.com/apache/dubbo-go). The skills help coding agents work with the dubbo-go repository, dubbo-go v3 applications, examples, extension points, Java interoperability, debugging, and migration tasks.
+
+The package lives under `.agents/` so it can include multi-agent distribution metadata without overwriting dubbo-go repository root files.
+
+> Note: All skills target dubbo-go v3. v1 and v2 are deprecated.
+
+## Layout
+
+- `skills/`: Codex-compatible skills. Codex reads this directory when working in this repository.
+- `.codex/INSTALL.md`: manual Codex installation notes for using these skills outside this checkout.
+- `.claude-plugin/marketplace.json`: Claude Code plugin marketplace metadata for this `.agents` package.
+- `.opencode/plugins/dubbo-go-agent-skills.js`: OpenCode adapter that exposes the bundled skills.
+- `GEMINI.md` and `gemini-extension.json`: Gemini CLI extension entry points.
+- `plugin.json` and `package.json`: generic plugin/package metadata for tools that can consume a package rooted at `.agents`.
+
+## Using These Skills
+
+When working inside an Apache dubbo-go checkout, Codex can load the repository-local skills from `.agents/skills` directly. No separate clone of a skills repository is required.
+
+For global Codex usage outside this checkout, follow [.codex/INSTALL.md](.codex/INSTALL.md).
+
+For OpenCode, Gemini CLI, or Claude Code packaging, treat `.agents` as the package root. The metadata files in this directory are intentionally relative to `.agents`.
+
+## Skills
+
+### development
+
+Guides agents modifying the apache/dubbo-go repository itself. It covers current Go/toolchain expectations, package boundaries, validation commands, generated files, and repository-specific do-not rules.
+
+### scaffolding
+
+Generates provider or consumer skeletons in the current dubbo-go v3 code-API style. It covers direct mode, registry-backed services, Protobuf generation, OpenAPI, HTTP handler mounting, HTTP/3, and current sample patterns.
+
+### extensions
+
+Guides custom SPI extensions such as Filter, LoadBalance, Router, Registry, Protocol, ConfigCenter, and Logger. It covers the `extension.SetXxx` registration pattern, blank imports, activation options, and common failure modes.
+
+### java-interop
+
+Guides interoperability between dubbo-go and dubbo-java. It helps choose Triple+Protobuf or Dubbo+Hessian2, handle service discovery mapping, and debug cross-language serialization.
+
+### debug
+
+Provides structured diagnosis for runtime issues such as missing providers, registry mapping, connection failures, serialization mismatches, timeouts, OpenAPI issues, attached HTTP handlers, shutdown behavior, and filter panics.
+
+### guide
+
+Explains current dubbo-go architecture, extension points, and best practices. It covers Instance, Protocol, Registry, Metadata, Filter, Cluster, LoadBalance, Router, Triple OpenAPI, HTTP/3, CORS, graceful shutdown, observability, and sample locations.
+
+### migrate
+
+Guides migration from gRPC-Go, Spring Cloud, Gin/plain HTTP, older dubbo-go v1/v2 usage, YAML-heavy apps, Java Dubbo, and Hessian2 services to current dubbo-go v3 patterns.
+
+## Contributing
+
+Skills live in `.agents/skills`.
+
+1. Add or edit a skill under `.agents/skills/<name>/SKILL.md`.
+2. Keep `SKILL.md` frontmatter concise and trigger-focused.
+3. Update this directory's metadata only when install paths, skill names, or supported agents change.
+4. Submit the change through the normal dubbo-go contribution workflow.
+
+## License
+
+Apache License 2.0

.agents/README_CN.md

@@ -0,0 +1,86 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# dubbo-go Agent Skills
+
+[English](README.md) | 中文
+
+本目录存放随 [Apache dubbo-go](https://github.com/apache/dubbo-go) 仓库一起维护的 AI Agent Skills。这些 skills 用于帮助编码 Agent 处理 dubbo-go 仓库源码、dubbo-go v3 应用、示例生成、扩展点、Java 互通、问题排查和迁移任务。
+
+这套包放在 `.agents/` 下，是为了把多 Agent 分发元数据集中在一起，同时避免覆盖 dubbo-go 仓库根目录已有文件。
+
+> 注意：所有 skills 都面向 dubbo-go v3。v1 和 v2 已废弃。
+
+## 目录结构
+
+- `skills/`：Codex 可直接加载的 skills。Codex 在本仓库工作时会读取该目录。
+- `.codex/INSTALL.md`：在本仓库外全局使用这些 skills 的 Codex 手动安装说明。
+- `.claude-plugin/marketplace.json`：面向 Claude Code 插件市场的元数据。
+- `.opencode/plugins/dubbo-go-agent-skills.js`：OpenCode 适配器，用于暴露本目录内的 skills。
+- `GEMINI.md` 和 `gemini-extension.json`：Gemini CLI 扩展入口。
+- `plugin.json` 和 `package.json`：供能够以 `.agents` 为包根目录的工具读取的通用元数据。
+
+## 使用方式
+
+在 Apache dubbo-go 仓库内工作时，Codex 可以直接从 `.agents/skills` 加载仓库内置 skills，不需要再单独克隆一个 skills 仓库。
+
+如果要在本仓库外全局使用这套 Codex skills，请参考 [.codex/INSTALL.md](.codex/INSTALL.md)。
+
+如果用于 OpenCode、Gemini CLI 或 Claude Code 的插件包装，请把 `.agents` 视为包根目录。本目录中的元数据路径都按 `.agents` 为根来组织。
+
+## Skills
+
+### development
+
+指导 Agent 修改 apache/dubbo-go 仓库本身，覆盖当前 Go/toolchain 要求、包边界、验证命令、生成文件和仓库级禁止事项。
+
+### scaffolding
+
+生成当前 dubbo-go v3 code API 风格的 provider 或 consumer 骨架，覆盖直连模式、注册中心服务、Protobuf 生成、OpenAPI、HTTP handler 挂载、HTTP/3 和当前示例模式。
+
+### extensions
+
+指导编写自定义 SPI 扩展，例如 Filter、LoadBalance、Router、Registry、Protocol、ConfigCenter、Logger。覆盖 `extension.SetXxx` 注册模式、blank import、启用方式和常见失败原因。
+
+### java-interop
+
+指导 dubbo-go 和 dubbo-java 互通。根据服务形态和兼容性需求，在 Triple+Protobuf 与 Dubbo+Hessian2 之间做选择，并处理服务发现映射和跨语言序列化问题。
+
+### debug
+
+为运行时问题提供结构化排查流程，例如 provider 找不到、注册中心映射、连接失败、序列化不匹配、超时、OpenAPI、HTTP handler 挂载、shutdown 和 filter panic。
+
+### guide
+
+解释当前 dubbo-go 架构、扩展点和最佳实践，覆盖 Instance、Protocol、Registry、Metadata、Filter、Cluster、LoadBalance、Router、Triple OpenAPI、HTTP/3、CORS、graceful shutdown、可观测性和示例位置。
+
+### migrate
+
+指导从 gRPC-Go、Spring Cloud、Gin/纯 HTTP、dubbo-go v1/v2、YAML-heavy 应用、Java Dubbo 和 Hessian2 服务迁移到当前 dubbo-go v3 模式。
+
+## 贡献
+
+Skills 位于 `.agents/skills`。
+
+1. 在 `.agents/skills/<name>/SKILL.md` 下新增或修改 skill。
+2. 保持 `SKILL.md` frontmatter 简洁，并聚焦触发场景。
+3. 只有当安装路径、skill 名称或支持的 Agent 发生变化时，才更新本目录的元数据。
+4. 按 dubbo-go 正常贡献流程提交修改。
+
+## License
+
+Apache License 2.0

.agents/gemini-extension.json

@@ -0,0 +1,6 @@
+{
+  "name": "dubbo-go-agent-skills",
+  "description": "Agent skills bundled with Apache dubbo-go for repository development, v3 scaffolding, extensions, Java interop, debugging, guidance, and migration.",
+  "version": "0.2.0",
+  "contextFileName": "GEMINI.md"
+}

.agents/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "dubbo-go-agent-skills",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Agent skills bundled with Apache dubbo-go for repository development, v3 scaffolding, extensions, Java interop, debugging, guidance, and migration.",
+  "author": "Apache Dubbo contributors",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apache/dubbo-go.git",
+    "directory": ".agents"
+  },
+  "homepage": "https://github.com/apache/dubbo-go/tree/develop/.agents",
+  "main": ".opencode/plugins/dubbo-go-agent-skills.js"
+}

.agents/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "dubbo-go",
+  "version": "0.2.0",
+  "description": "Agent skills bundled with Apache dubbo-go for repository development, v3 scaffolding, extensions, Java interop, debugging, guidance, and migration.",
+  "author": "Apache Dubbo contributors",
+  "skills": [
+    "skills/development",
+    "skills/scaffolding",
+    "skills/extensions",
+    "skills/java-interop",
+    "skills/debug",
+    "skills/guide",
+    "skills/migrate"
+  ]
+}