docs: add dubbo-go agent skills

Signed-off-by: Oxidaner <18622412361@163.com>

Author: Oxidaner

.agents/skills/dubbo-go-cluster/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: dubbo-go-cluster
+description: >-
+  Implements and reviews dubbo-go cluster, routing, directory, and load-balancing changes. Use when the user asks about
+  failover, failfast, failsafe, failback, forking, broadcast, available, zoneaware, adaptive service, Directory,
+  RouterChain, condition, tag, script, affinity or Polaris routers, load balance algorithms, retries, provider
+  selection, or packages cluster/cluster/, cluster/directory/, cluster/router/, and cluster/loadbalance/. Do not use
+  for registry backend mechanics unless the directory snapshot contract is affected.
+---
+
+# dubbo-go Cluster
+
+## Purpose
+
+Use this skill to change or explain how provider invokers are listed, routed, load-balanced, retried, and invoked by cluster fault-tolerance strategies.
+
+## When to use
+
+Use for cluster invokers, directory snapshots, router chain behavior, dynamic routing rules, tag or condition matching, load balancing, retries, and adaptive service behavior.
+
+Do not use for registry backend code unless registry notifications affect directory snapshots.
+
+## Inputs
+
+Required:
+- Cluster strategy, router, load balancer, directory, or invocation selection behavior.
+- Intended routing/selection behavior or observed mismatch.
+
+Optional:
+- Consumer URL, provider URLs, invocation attachments, method name, route rule, or registry event sequence.
+
+If missing, start at `cluster/router/chain/chain.go` for routing or `cluster/cluster/` for fault tolerance.
+
+## Workflow
+
+1. Classify the behavior as directory update, router filtering, load balance selection, or cluster fault tolerance.
+2. Read `cluster/directory/` for provider invoker snapshots and registry notification handling.
+3. Read `cluster/router/chain/chain.go` and the relevant router package for filtering behavior.
+4. Read `cluster/loadbalance/` for provider selection.
+5. Read the relevant `cluster/cluster/*/cluster_invoker.go` for retry and error behavior.
+6. Check extension registration under `common/extension/cluster.go`, `loadbalance.go`, and `router_factory.go`.
+7. Read `references/routing-cluster-flow.md` before changing selection semantics.
+
+## Output format
+
+Return directory source, router chain result, load balance or cluster strategy, changed files, and validation performed.
+
+## Validation
+
+- Confirm router priority and stable ordering still produce deterministic results.
+- Confirm directory snapshots are copied safely and not mutated by callers.
+- Confirm retry count and business-error handling match the strategy.
+- Run focused tests such as `go test ./cluster/...`; use `make test` for broad invocation behavior.
+
+## Edge cases
+
+- RouterChain first narrows invokers by service key and falls back to all invokers if no service-key match exists.
+- Static router config is injected after builtin routers are created.
+- Failover retries non-business errors but returns business errors directly.
+- Method-level URL params can override interface-level routing, retries, and load balance settings.
+
+## References
+
+- Read `references/routing-cluster-flow.md` for directory, router, load balance, and cluster invocation details.

.agents/skills/dubbo-go-cluster/references/routing-cluster-flow.md

@@ -0,0 +1,42 @@
+# Routing and Cluster Flow
+
+## Invocation Path
+
+1. A proxy or protocol caller invokes a cluster invoker.
+2. The cluster invoker asks its directory for invokers matching the invocation.
+3. Directory output is routed through `RouterChain`.
+4. The cluster strategy chooses or retries invokers using a load balancer.
+5. The selected protocol invoker performs the remote call.
+
+## Directory
+
+- Static directory holds fixed invokers.
+- Registry directory reacts to registry notifications and rebuilds invoker snapshots.
+- Directory output should be treated as a snapshot for one invocation path.
+
+## Router Chain
+
+- `RouterChain.Route` copies invokers, filters by service key when possible, then applies routers in priority order.
+- Router factories are registered through `extension.SetRouterFactory`.
+- Static router configs are injected through routers implementing `StaticConfigSetter`.
+- Dynamic routers may update internal state on `Notify`.
+
+## Load Balance
+
+- Load balance implementations live under `cluster/loadbalance/`.
+- Selection receives candidate invokers and the invocation.
+- Method-level URL params can affect algorithm choice.
+
+## Cluster Strategies
+
+- `failover`: retry non-business errors and reselect providers.
+- `failfast`: fail immediately.
+- `failsafe`: swallow failures according to strategy.
+- `failback`: retry in background.
+- `forking`, `broadcast`, `available`, `zoneaware`, and `adaptivesvc` have specialized selection behavior.
+
+## Contract Checks
+
+- Keep router output deterministic for the same snapshot and invocation.
+- Avoid mutating shared invoker slices from callers.
+- Preserve distinction between business errors and transport or provider errors.

.agents/skills/dubbo-go-config/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: dubbo-go-config
+description: >-
+  Implements and reviews dubbo-go configuration changes. Use when the user asks about dubbo.Load, config.Load,
+  RootConfig, InstanceOptions, global config structs, YAML or JSON loading, koanf parsing, config center integration,
+  dynamic configuration, hot reload, config post processors, or packages loader.go, config/, global/, config_center/,
+  and common/config/. Do not use for runtime export/refer behavior unless configuration injection is the contract.
+---
+
+# dubbo-go Config
+
+## Purpose
+
+Use this skill to change or explain how dubbo-go loads, initializes, validates, hot-reloads, and exposes configuration to runtime client and server code.
+
+## When to use
+
+Use for configuration files, builder APIs, `RootConfig`, `InstanceOptions`, global config models, config center factories, hot reload allowlists, and config post-processing.
+
+Do not use for protocol transport, registry events, or runtime export/refer behavior unless configuration injection is the contract being changed.
+
+## Inputs
+
+Required:
+- Config key, config struct, loader API, or package path.
+- Intended behavior or observed parse/init bug.
+
+Optional:
+- YAML or JSON snippet.
+- Config center protocol and data ID or group.
+- Related client, server, reference, or service option.
+
+If missing, inspect `loader.go`, `config/config_loader.go`, and the relevant `global/*_config.go` or `config/*_config.go`.
+
+## Workflow
+
+1. Identify whether the task targets top-level `dubbo.Load` and `InstanceOptions` or legacy `config.Load` and `RootConfig`.
+2. Read the owning config model under `global/` and compatibility or builder code under `config/`.
+3. Trace initialization into `InstanceOptions.init`, `RootConfig.Init`, service/reference init, or config center startup.
+4. For dynamic config, inspect `config/config_center_config.go`, `config_center/`, and `common/extension/config_center_factory.go`.
+5. For hot reload, inspect `loader.go` and keep `safeChanged` semantics narrow.
+6. Read `references/config-flow.md` before changing loader behavior or public config keys.
+
+## Output format
+
+Return changed config keys or structs, loader path, runtime injection impact, validation performed, and any compatibility notes.
+
+## Validation
+
+- Confirm new config fields are represented in the right `global/` or `config/` model and initialized before runtime use.
+- Confirm config center changes register the correct extension factory.
+- Confirm hot reload accepts only intended mutable keys.
+- Run focused tests such as `go test ./config ./global ./config_center/...`; use `make test` for broad config behavior.
+
+## Edge cases
+
+- `dubbo.Load` starts provider and consumer runtime; `config.Load` only initializes `RootConfig`.
+- Some config values are transported as URL params, while TLS, application, registry, shutdown, and Triple details often travel as URL attributes.
+- Existing compatibility tests may depend on legacy field names.
+
+## References
+
+- Read `references/config-flow.md` for loader, config center, and runtime injection details.

.agents/skills/dubbo-go-config/references/config-flow.md

@@ -0,0 +1,44 @@
+# Config Flow
+
+## Entry Points
+
+- `loader.go`: top-level `dubbo.Load`, file watch, hot reload, and `InstanceOptions`.
+- `config/config_loader.go`: package-level `config.Load`, `RootConfig` storage, and legacy config accessors.
+- `dubbo.go`: maps `InstanceOptions` into `client.ClientOption` and `server.ServerOption`.
+- `global/`: config models used by public client/server options.
+- `config/`: builders, compatibility models, config center startup, and legacy `RootConfig` initialization.
+
+## Loader Flow
+
+Top-level `dubbo.Load`:
+1. Build `loaderConf`.
+2. Resolve config with koanf from file, raw bytes, or direct options.
+3. Unmarshal into `InstanceOptions`.
+4. Run `InstanceOptions.init`.
+5. Create an `Instance` and start consumer/provider loading.
+6. Start the file watcher once and register shutdown cleanup.
+
+Package `config.Load`:
+1. Build `LoaderConf`.
+2. Resolve into `RootConfig` when one is not provided.
+3. Run `RootConfig.Init`.
+4. Store the initialized root config through the atomic pointer.
+
+## Config Center
+
+- Config center setup is coordinated by `config/config_center_config.go`.
+- Implementations live under `config_center/{apollo,file,nacos,zookeeper}`.
+- Factories register through `common/extension/config_center_factory.go`.
+- Parser behavior is under `config_center/parser/`.
+
+## Runtime Injection
+
+- `Instance.NewClient` clones consumer, application, registry, shutdown, metrics, otel, TLS, protocol, and router config into `client` options.
+- `Instance.NewServer` clones application, registry, protocol, shutdown, metrics, otel, and TLS config into `server` options.
+- Reference and service options ultimately build `common.URL` values. Use params for transportable Dubbo URL values and attributes for in-process objects.
+
+## Hot Reload
+
+- File watching is in `loader.go`.
+- `hotUpdateConfig` compares old and new koanf trees with `safeChanged`.
+- Keep hot reload allowlists conservative because changing immutable runtime fields after export or refer can leave stale protocols, registries, or metadata.

.agents/skills/dubbo-go-domain/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: dubbo-go-domain
+description: >-
+  Use this skill when working on the dubbo-go codebase, including implementing features, fixing bugs, writing tests,
+  reviewing code, updating documentation, or routing work to a narrower dubbo-go-* domain skill. Use for cross-module
+  questions, end-to-end flows, subsystem boundaries, or deciding whether config, runtime, protocol, registry, metadata,
+  cluster routing, filters and observability, or tools guidance applies.
+---
+
+# dubbo-go Project Guide
+
+## Project Overview
+
+dubbo-go is the Go implementation of Apache Dubbo. It is an RPC and microservice framework that provides service export and reference, registry and service discovery, protocol interoperability, cluster fault tolerance, traffic governance, configuration, metadata, metrics, tracing, and developer tools.
+
+It mainly provides:
+- Public client and server APIs for Go services.
+- Dubbo, Dubbo3, Triple, gRPC, REST, JSONRPC, and related transport support.
+- Registry integration with Nacos, Zookeeper, Etcd, Polaris, and application-level service discovery.
+- Metadata collection, metadata reporting, service name mapping, routing, load balancing, filters, metrics, tracing, and CLI or code generation tools.
+
+This repository does not own external registry servers, Dubbo Java implementation, sample applications outside this repository, or production deployment infrastructure.
+
+## Tech Stack
+
+- Language: Go, module `dubbo.apache.org/dubbo-go/v3`.
+- Go version: `go 1.25.0` in `go.mod`; root `Makefile` uses `GOTOOLCHAIN=go1.25.0+auto` for tests.
+- Build: Go modules plus nested Go modules under selected `tools/` directories.
+- Test: `go test`, `testify`, `gomock`, and focused package tests.
+- Lint and format: `go fmt`, `imports-formatter`, `go vet`, `golangci-lint`, and `make fmt` or `make lint`.
+
+Do not introduce a new framework or dependency unless the task requires it and the compatibility impact is clear.
+
+## Repository Structure
+
+- `dubbo.go`, `loader.go`: public instance and top-level load/start APIs.
+- `config/`, `global/`, `config_center/`, `common/config/`: config models, loading, config center, and compatibility behavior.
+- `client/`, `server/`, `proxy/`, `graceful_shutdown/`: runtime client/server construction, refer/export, proxy, and shutdown behavior.
+- `protocol/`, `remoting/`, `common/url.go`: protocol interfaces, codecs, transports, URL contract, invokers, and exporters.
+- `registry/`, `metadata/`: registry discovery, service discovery, metadata, reports, mapping, and revisions.
+- `cluster/`: directories, routers, load balancing, and cluster fault tolerance.
+- `filter/`, `metrics/`, `otel/`, `logger/`: filters, observability, tracing, metrics, and logging.
+- `tools/`: CLI, schema generator, protoc plugins, import formatter, and RPC contract scanner.
+- `docs/`, `doc/`: project documentation and images.
+
+## Workflow
+
+When modifying code:
+
+1. Classify the owning subsystem and load the narrower `dubbo-go-*` skill when relevant.
+2. Read the existing implementation and tests before editing.
+3. Make the smallest correct change that follows current package boundaries.
+4. Prefer existing abstractions, extension registries, URL params, and URL attributes over new patterns.
+5. Add or update focused tests for behavior changes.
+6. Run the most relevant validation command.
+7. Summarize changed files, behavior, compatibility impact, and validation result.
+
+When fixing bugs:
+
+1. Reproduce the issue or identify the failing path from tests, logs, or code.
+2. Find the smallest root cause.
+3. Make a minimal safe change.
+4. Add a regression test when feasible.
+5. Explain why the fix works and what risk remains.
+
+When reviewing code:
+
+1. Check behavior, compatibility, concurrency, error handling, generated file handling, and missing tests first.
+2. Ground findings in file and line references.
+3. Keep summary secondary to concrete risks.
+
+## Coding Guidelines
+
+- Keep changes focused and reviewable.
+- Follow existing package structure, naming, and extension registration patterns.
+- Preserve backward compatibility for public APIs, config keys, URL params, wire behavior, and generated output unless explicitly requested.
+- Use structured config, URL, and parser APIs instead of ad hoc string handling when available.
+- Avoid broad refactors during bug fixes.
+- Do not change unrelated files.
+
+## Testing and Validation
+
+Use the most relevant command:
+
+```bash
+go test ./...
+make test
+make fmt
+make lint
+make rpc-contract-check
+```
+
+For focused work, prefer package-level tests first, for example:
+
+```bash
+go test ./config ./global ./config_center/...
+go test ./client ./server ./proxy ./graceful_shutdown
+go test ./protocol/... ./remoting/...
+go test ./registry/... ./metadata/...
+go test ./cluster/...
+go test ./filter/... ./metrics/... ./otel/...
+```
+
+For nested tools, run tests from the owning module directory.
+
+If validation cannot be run or fails, report the command, the error, and whether it appears related to the current change.
+
+## Do Not
+
+- Do not rewrite large parts of the project without explicit instruction.
+- Do not introduce new dependencies or frameworks unless necessary.
+- Do not change public APIs, config keys, wire contracts, or generated output without documenting compatibility impact.
+- Do not remove or weaken tests to make validation pass.
+- Do not commit secrets, tokens, passwords, private keys, or private config.
+- Do not modify generated files manually unless the generation source is also updated or the repository already treats that file as hand-maintained.
+- Do not ignore existing uncommitted user changes.
+
+## Common Tasks
+
+### Choose a Domain Skill
+
+1. Map the request to the primary package.
+2. Use `references/architecture-map.md` when ownership is unclear.
+3. Load one narrower skill when possible.
+4. If multiple domains are involved, follow runtime flow: config, runtime, protocol, registry or metadata, cluster, filters, observability, tools.
+
+### Add a Feature
+
+1. Find the owning module and existing tests.
+2. Add the core behavior using existing abstractions.
+3. Add or update tests.
+4. Update documentation when public behavior changes.
+5. Run focused validation.
+
+### Add a Configuration Option
+
+1. Define the config key in the owning config model.
+2. Add default and initialization behavior.
+3. Wire it into the consuming module through existing options or URL params/attributes.
+4. Add tests for default and custom behavior.
+5. Update docs or schemas when relevant.
+
+### Fix a Bug
+
+1. Identify the root cause.
+2. Make the minimal fix.
+3. Add a regression test when possible.
+4. Verify with the narrowest relevant command.
+
+## Output Format
+
+Return the selected skill or subsystem, changed files, behavior change, compatibility impact, validation performed, and any residual risk.
+
+## Edge cases
+
+- `dubbo.Load` and `config.Load` both load configuration, but they serve different public APIs.
+- Registry discovery and metadata reporting are tightly coupled; use `dubbo-go-metadata` when revisions or metadata reports control behavior.
+- Filters wrap protocols through `protocol/protocolwrapper`; use `dubbo-go-protocol` when transport semantics change and `dubbo-go-observability-filters` when interception semantics change.
+- Some `tools/` subdirectories are independent Go modules.
+
+## References
+
+- Read `references/architecture-map.md` for subsystem ownership and end-to-end flow.
+- Read `references/project-rules.md` for compatibility, generated-file, validation, and PR guidance.