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

.agents/README.md

@@ -0,0 +1,136 @@
+<!--
+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"]
+}
+```
+
+### Gemini CLI
+
+```bash
+gemini extensions install https://github.com/apache/dubbo-go --path .agents
+```
+
+Update later with:
+
+```bash
+gemini extensions update dubbo-go-agent-skills
+```
+
+### 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.
+
+## 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 points to the relevant `dubbo-go-samples` directory through `samples-index.md`.
+
+### 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