docs: add dubbo-go agent skills

.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 v3 framework users",
+  "owner": {
+    "name": "Apache Dubbo"
+  },
+  "plugins": [
+    {
+      "name": "dubbo-go",
+      "description": "AI skills for Apache dubbo-go v3 users — scaffolding, extensions, Java interop, debugging, guidance, migration, plus contributor support.",
+      "category": "development",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/apache/dubbo-go.git"
+      },
+      "homepage": "https://github.com/apache/dubbo-go/tree/main/.agents"
+    }
+  ]
+}

.agents/.codex/INSTALL.md

@@ -0,0 +1,68 @@
+<!--
+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
+
+## Install
+
+Install these skills globally when the user asks to install dubbo-go skills for Codex.
+
+```bash
+if [ -d ~/.codex/dubbo-go/.git ]; then
+  git -C ~/.codex/dubbo-go pull --ff-only
+else
+  git clone https://github.com/apache/dubbo-go.git ~/.codex/dubbo-go
+fi
+
+mkdir -p ~/.agents/skills
+rm -rf ~/.agents/skills/dubbo-go
+ln -s ~/.codex/dubbo-go/.agents/skills ~/.agents/skills/dubbo-go
+```
+
+Restart Codex after installation.
+
+### Windows
+
+```powershell
+$repo = "$env:USERPROFILE\.codex\dubbo-go"
+if (Test-Path "$repo\.git") {
+  git -C $repo pull --ff-only
+} else {
+  git clone https://github.com/apache/dubbo-go.git $repo
+}
+
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
+Remove-Item -Recurse -Force "$env:USERPROFILE\.agents\skills\dubbo-go" -ErrorAction SilentlyContinue
+cmd /c mklink /J "$env:USERPROFILE\.agents\skills\dubbo-go" "$env:USERPROFILE\.codex\dubbo-go\.agents\skills"
+```
+
+Restart Codex after installation.
+
+## Update
+
+```bash
+cd ~/.codex/dubbo-go
+git pull --ff-only
+rm -rf ~/.agents/skills/dubbo-go
+ln -s ~/.codex/dubbo-go/.agents/skills ~/.agents/skills/dubbo-go
+```
+
+Restart Codex after updating.
+
+## Usage
+
+The installed skills cover scaffolding, custom SPI extensions, Java interoperability, runtime debugging, conceptual guidance, and migration for dubbo-go v3 — plus a contributor-focused skill for modifying the `apache/dubbo-go` repository itself.

.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 = ['scaffolding', 'extensions', 'java-interop', 'debug', 'guide', 'migrate', 'development'];
+
+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/README.md

@@ -0,0 +1,130 @@
+<!--
+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)
+
+AI agent skills bundled with [Apache dubbo-go](https://github.com/apache/dubbo-go) — make your coding assistant fluent in dubbo-go v3.
+
+## What This Gives You
+
+When you're using dubbo-go, your AI assistant now actually knows what it's doing.
+
+Ask it to scaffold a new provider or consumer and it picks the current code-API style (`dubbo.NewInstance` + `server.WithServerProtocol`), wires up the registry you actually use, and produces something that compiles on the first try. Need a custom filter or load balancer? It knows the SPI pattern — `extension.SetXxx` registration, blank imports, per-service or per-reference activation. Calling a Java Dubbo service? It picks Triple+Protobuf or Dubbo+Hessian2 based on whether you have a `.proto` or a Java interface, and gets the POJO class names right.
+
+Ask why your service won't connect, and it triages by structured checklist — registry, protocol, serialization, filter chain — instead of guessing. Migrating from gRPC-Go or Spring Cloud? It maps the concepts side by side.
+
+Skills activate automatically when the conversation matches; you don't invoke them by name.
+
+> All skills target dubbo-go **v3**. v1 and v2 are deprecated.
+
+## Install
+
+Install paths vary by AI tool. Claude Code and Cursor read a marketplace; Codex and OpenCode are manual.
+
+### Claude Code / Cursor
+
+```bash
+/plugin marketplace add apache/dubbo-go
+/plugin install dubbo-go@dubbo-go-agent-skills
+```
+
+### Codex
+
+Tell Codex:
+
+```
+Fetch and follow instructions from https://raw.githubusercontent.com/apache/dubbo-go/main/.agents/.codex/INSTALL.md
+```
+
+Full instructions: [.codex/INSTALL.md](.codex/INSTALL.md)
+
+### OpenCode
+
+Add to `opencode.json`:
+
+```json
+{
+  "plugin": ["dubbo-go-agent-skills@git+https://github.com/apache/dubbo-go.git#path:.agents"]
+}
+```
+
+### Verify
+
+Open a new session and try one of these:
+
+- "Scaffold a dubbo-go provider with Nacos"
+- "Why does my consumer log 'no provider available'?"
+- "How do I call a Java Dubbo service from Go?"
+
+The assistant should auto-trigger the matching skill.
+
+## Reference Docs
+
+Use the official Dubbo Golang SDK documentation as the primary reference for user-facing behavior and tutorials:
+
+- [Dubbo Golang SDK documentation](https://github.com/apache/dubbo-website/tree/master/content/zh-cn/overview/mannual/golang-sdk)
+
+## Skills
+
+### scaffolding
+
+Generates provider or consumer skeletons in v3 code-API style (`dubbo.NewInstance` / `server.NewServer` / `client.NewClient`). Asks about protocol (Triple / Dubbo / gRPC) and registry (Nacos / ZooKeeper / etcd / direct) first, then produces a complete, compilable skeleton matching the official samples. Covers OpenAPI, HTTP handler attachment, and HTTP/3.
+
+### extensions
+
+Custom SPI extensions — Filter, LoadBalance, Registry, Protocol, Router, Logger. Explains the uniform pattern (`extension.SetXxx` + blank import + `WithFilter` / `WithLoadBalance`), with runnable templates and the silent-failure modes that catch newcomers.
+
+### java-interop
+
+Cross-language RPC between dubbo-go and dubbo-java. Picks Triple+Protobuf for new services, Dubbo+Hessian2 for existing Java-defined ones, and gets POJO class names, method-name casing, and the curl-friendly HTTP route format right.
+
+### debug
+
+Structured diagnosis for runtime errors. Matches your error or log against known patterns — "no provider available", connection refused, serialization mismatch, timeout, filter panic, OpenAPI 404, AttachHTTPHandler failure, slow shutdown — and gives a targeted checklist.
+
+### guide
+
+Architecture, extension points, and best practices. Covers Instance, Protocol, Registry, Filter, Cluster, LoadBalance, Router, Triple OpenAPI, HTTP/3, CORS, graceful shutdown, observability, and tells agents to read the current `apache/dubbo-go-samples` README and directories when choosing examples.
+
+### migrate
+
+Step-by-step migration guidance:
+
+- **gRPC-Go** — concept mapping, proto reuse, direct mode parallels
+- **Spring Cloud (Java)** — registry sharing, Java/Go coexistence path
+- **Gin / plain HTTP** — coexistence options and Triple REST mode
+- **dubbo-go v1/v2 → v3** — breaking-change table, minimum migration path
+- **YAML-heavy v3** — incremental move to the code API
+
+### development
+
+For contributors modifying the `apache/dubbo-go` repository itself — Go toolchain, package boundaries, validation commands, generated files, repository-level do-not rules. Not for application-side scaffolding.
+
+## Contributing
+
+Skills live in `.agents/skills/<name>/SKILL.md`.
+
+1. Edit or add a skill in place.
+2. Keep the frontmatter `description` trigger-focused — that line is what the agent reads to decide whether to use the skill.
+3. Update `.agents/` metadata only when install paths, skill names, or supported agents change.
+4. Submit through the normal dubbo-go contribution workflow.
+
+## License
+
+Apache License 2.0

.agents/README_CN.md

@@ -0,0 +1,130 @@
+<!--
+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——让你的编码助手真正会写 dubbo-go v3。
+
+## 它能给你什么
+
+你在用 dubbo-go 时，AI 助手现在知道自己在做什么了。
+
+让它搭一个新的 provider 或 consumer，它会选对当前的 code-API 风格（`dubbo.NewInstance` + `server.WithServerProtocol`），接上你实际用的注册中心，第一次就能编译过。要写自定义 filter 或负载均衡？它懂 SPI 模式——`extension.SetXxx` 注册、blank import、按 service 或 reference 启用。要和 Java Dubbo 服务互通？它会根据你有的是 `.proto` 还是 Java 接口，正确选 Triple+Protobuf 或 Dubbo+Hessian2，POJO 类名也能对齐。
+
+问它服务为什么连不上，它按结构化清单逐步排查——注册中心、协议匹配、序列化、filter 链——而不是瞎猜。要从 gRPC-Go 或 Spring Cloud 迁移？它会把概念逐一映射。
+
+Skill 在上下文匹配时自动触发，不需要手动调用。
+
+> 所有 skill 仅支持 dubbo-go **v3**，v1/v2 已废弃。
+
+## 安装
+
+不同 AI 工具安装方式不同。Claude Code 和 Cursor 内置市场，Codex 和 OpenCode 需要手动安装。
+
+### Claude Code / Cursor
+
+```bash
+/plugin marketplace add apache/dubbo-go
+/plugin install dubbo-go@dubbo-go-agent-skills
+```
+
+### Codex
+
+告诉 Codex：
+
+```
+Fetch and follow instructions from https://raw.githubusercontent.com/apache/dubbo-go/main/.agents/.codex/INSTALL.md
+```
+
+详细文档：[.codex/INSTALL.md](.codex/INSTALL.md)
+
+### OpenCode
+
+在 `opencode.json` 中加：
+
+```json
+{
+  "plugin": ["dubbo-go-agent-skills@git+https://github.com/apache/dubbo-go.git#path:.agents"]
+}
+```
+
+### 验证
+
+新开一个会话，试试这些：
+
+- "帮我搭一个用 Nacos 的 dubbo-go provider"
+- "consumer 报 'no provider available' 是什么原因"
+- "怎么从 Go 调一个 Java Dubbo 服务？"
+
+助手应该会自动触发对应的 skill。
+
+## 参考文档
+
+面向用户的行为说明和教程，以官方 Dubbo Golang SDK 文档为主要参考：
+
+- [Dubbo Golang SDK 文档](https://github.com/apache/dubbo-website/tree/master/content/zh-cn/overview/mannual/golang-sdk)
+
+## Skills
+
+### scaffolding
+
+按 v3 code-API 风格（`dubbo.NewInstance` / `server.NewServer` / `client.NewClient`）生成 provider 或 consumer 骨架。先确认协议（Triple / Dubbo / gRPC）和注册中心（Nacos / ZooKeeper / etcd / 直连），再生成与官方 samples 一致、可直接编译运行的骨架。覆盖 OpenAPI、HTTP handler 挂载、HTTP/3。
+
+### extensions
+
+自定义 SPI 扩展——Filter、LoadBalance、Registry、Protocol、Router、Logger。讲清统一模式（`extension.SetXxx` + blank import + `WithFilter` / `WithLoadBalance`），附可运行模板和新人最常踩的"静默失败"陷阱。
+
+### java-interop
+
+dubbo-go 与 dubbo-java 的跨语言 RPC。新服务选 Triple+Protobuf，老 Java 接口选 Dubbo+Hessian2，POJO 类名、方法名大小写、curl 友好的 HTTP 路由格式都对齐好。
+
+### debug
+
+运行时报错的结构化排查。把错误或日志和已知模式匹配——"no provider available"、连接被拒、序列化不匹配、超时、filter panic、OpenAPI 404、AttachHTTPHandler 失败、shutdown 偏慢——给出针对性的检查清单。
+
+### guide
+
+架构、扩展点、最佳实践。覆盖 Instance、Protocol、Registry、Filter、Cluster、LoadBalance、Router、Triple OpenAPI、HTTP/3、CORS、graceful shutdown、可观测性，并要求 Agent 在选择示例时读取当前 `apache/dubbo-go-samples` README 和目录。
+
+### migrate
+
+分步骤迁移指引：
+
+- **gRPC-Go**——概念映射、proto 复用、直连模式对照
+- **Spring Cloud（Java）**——注册中心复用、Java/Go 共存
+- **Gin / 纯 HTTP**——共存方案和 Triple REST 模式
+- **dubbo-go v1/v2 → v3**——breaking-change 对照、最小迁移路径
+- **YAML 重度依赖的 v3**——平滑迁移到 code API
+
+### development
+
+面向 `apache/dubbo-go` 仓库本身的贡献者——Go 工具链、包边界、校验命令、生成文件、仓库级禁止事项。**不**用于应用侧脚手架。
+
+## 贡献
+
+Skill 文件位于 `.agents/skills/<name>/SKILL.md`。
+
+1. 直接修改或新增 skill。
+2. 保持 frontmatter 的 `description` 聚焦触发场景——Agent 就是靠这一行决定要不要使用该 skill。
+3. 只有当安装路径、skill 名称或支持的 Agent 发生变化时，才修改 `.agents/` 下的元数据。
+4. 按 dubbo-go 正常贡献流程提交修改。
+
+## License
+
+Apache License 2.0