AgoraIO · digitallysavvy · Mar 13, 2026 · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
       "name": "agora",
       "source": "./",
       "description": "Real-time communication with Agora SDKs — RTC, RTM, Conversational AI, and token generation",
-      "version": "1.0.0"
+      "version": "1.1.0"
     }
   ]
 }
diff --git a/.claude-plugin/mcp-config.json b/.claude-plugin/mcp-config.json
@@ -0,0 +1,6 @@
+{
+  "agora-docs": {
+    "type": "http",
+    "url": "https://mcp.agora.io"
+  }
+}
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -5,8 +5,9 @@
   "author": {
     "name": "Agora"
   },
-  "repository": "https://github.com/AgoraIO-Conversational-AI/skills",
+  "repository": "https://github.com/AgoraIO/skills",
   "license": "MIT",
+  "mcpServers": "./mcp-config.json",
   "keywords": [
     "agora",
     "rtc",

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [1.1.0]
+
+### Added
+
+- Cloud Recording references (`references/cloud-recording/`) — REST API acquire/start/query/stop lifecycle
+- Server Gateway references (`references/server-gateway/`) — Linux C++ SDK setup and media pipeline
+- Testing Guidance skill (`references/testing-guidance/SKILL.md`) — ConvoAI and RTC test patterns
+- Next.js RTC pattern (`references/rtc/nextjs.md`) — SSR-safe dynamic import guidance
+- ConvoAI agent client toolkit React references (`references/conversational-ai/agent-client-toolkit-react.md`) — provider, hooks, transcript, state
+- Intake router (`skills/agora/intake/SKILL.md`) — multi-product needs analysis for ambiguous requests
+- Agora token-based auth for ConvoAI REST API — inline gotcha + implementation in `conversational-ai/README.md`
+- OpenAI Realtime MLLM configuration in `agent-samples.md`
+- Agora MCP server config bundled in `.claude-plugin/mcp-config.json`
+
+### Changed
+
+- `plugin.json` repository URL corrected to `AgoraIO/skills`
+- `marketplace.json` version aligned to `1.1.0`
+- `SECURITY.md` vulnerability report URL corrected to `AgoraIO/skills`
+
+## [1.0.0]
+
+### Added
+
+- RTC references for Web, React, iOS (Swift), Android (Kotlin/Java)
+- RTM Web references — messaging, presence, stream channels
+- Conversational AI references — REST API, agent config, 5 recipe files
+- Server-side token generation references
+- 4-layer progressive disclosure architecture (`SKILL.md` → product README → topic file)
+- Eval cases in `tests/eval-cases.md` (25 cases across R, C, F, I series)
+- Validation script (`scripts/validate-skills.sh`)
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -12,12 +12,15 @@ skills/
     ├── SKILL.md               ← entry point; do not restructure this file
     ├── intake/SKILL.md        ← intake router; do not restructure this file
     └── references/
-        ├── mcp-tools.md       ← MCP reference + freeze-forever decision table
+        ├── doc-fetching.md    ← two-tier lookup procedure (agent-facing)
+        ├── mcp-tools.md       ← Agora MCP server install guide (user-facing)
         ├── rtc/
         ├── rtm/
         ├── conversational-ai/
         ├── server/
-        └── cloud-recording/
+        ├── cloud-recording/
+        ├── server-gateway/
+        └── testing-guidance/
 ```
 
 ## Protected Files
@@ -36,9 +39,20 @@ These files contain stable, high-value inline examples. Edits require a verified
 Before adding any inline content, ask: **will this still be correct in 6 months without any updates?**
 
 - **Yes** → put it inline (stable APIs, initialization sequences, gotchas)
-- **No** → route to MCP or an external link (REST API schemas, SDK changelogs, vendor configs, model names)
-
-See [`skills/agora/references/mcp-tools.md`](skills/agora/references/mcp-tools.md) for the full decision table.
+- **No** → route to Level 2 fetch or an external link (REST API schemas, SDK changelogs, vendor configs, model names)
+
+| Content type | Where it lives |
+|---|---|
+| RTC initialization, track management, event registration | Inline — `references/rtc/` |
+| RTM messaging and presence patterns | Inline — `references/rtm/` |
+| Token generation (RTC, RTM, AccessToken2) | Inline — `references/server/` |
+| ConvoAI gotchas, field-type rules, lifecycle | Inline — `references/conversational-ai/README.md` |
+| ConvoAI quick-start code (Python, Go, Java) | Level 2 fetch |
+| ConvoAI full request/response schemas | Level 2 fetch |
+| TTS / ASR / LLM vendor configs and model names | Level 2 fetch |
+| Cloud Recording REST API field details | Level 2 fetch |
+| Error code listings | Level 2 fetch |
+| Release notes and new parameters | Level 2 fetch |
 
 ## Naming Rule
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,6 +10,9 @@ Changes should improve routing accuracy, code generation quality, and maintainab
 
 ## Adding a New Product Skill
 
+Examples of existing products added this way: Cloud Recording (`references/cloud-recording/`),
+Server Gateway (`references/server-gateway/`), Testing Guidance (`references/testing-guidance/`).
+
 1. Create `skills/agora/references/{product}/README.md` (Layer 3 — overview,
    critical rules, topic links, 20–100 lines)
 2. Add an entry to the **Products** section of `skills/agora/SKILL.md`
@@ -23,6 +26,7 @@ Changes should improve routing accuracy, code generation quality, and maintainab
    - Add relevant rows to Common Product Combinations
    - Add a routing entry to the Step 4 table
    - Add a Decision Shortcuts row if the product has a clear keyword trigger
+7. Bump the version in all three version files (see [Version Bumping](#version-bumping))
 
 ## Adding a New Platform
 
@@ -50,7 +54,7 @@ without any updates?**
   ConvoAI request/response schemas): put it **behind an MCP call** or an **external link**.
   Never hardcode fast-moving content.
 
-Ben's existing link-first vs inline decision table in `README.md` already encodes this
+The link-first vs inline decision table in `README.md` already encodes this
 principle. Follow it. When in doubt, add a new row to that table and document your
 reasoning in the PR description.
 
@@ -120,6 +124,74 @@ Rules:
 
     bash scripts/validate-skills.sh
 
+## Running Evals
+
+Eval cases live in `tests/eval-cases.md`. To run them:
+
+1. Load the skill in your AI coding assistant (see [README — Installation](README.md#installation))
+2. For each case, send the "User Input" to the assistant with the skill active
+3. Compare the response against "Expected Behavior" and "Pass Criteria"
+4. Record `PASS` or `FAIL` in the Result field
+5. Add the run to the **Evaluation Log** table at the bottom of `tests/eval-cases.md`
+   (date, skill version, pass/fail counts, failed case IDs, fix actions taken)
+
+Run the full suite after every non-trivial skill change. Failed cases drive targeted
+skill edits — don't ship a fix without verifying the case now passes.
+
+## Version Bumping
+
+Versions must stay in sync across three files. Bump all three together:
+
+| File | Field |
+|------|-------|
+| `skills/agora/SKILL.md` | `metadata.version` in frontmatter |
+| `.claude-plugin/plugin.json` | `"version"` |
+| `.claude-plugin/marketplace.json` | `plugins[0].version` |
+
+Version rules:
+- **Patch** (`x.y.Z`): gotcha fixes, broken link repairs, content corrections
+- **Minor** (`x.Y.0`): new product or platform added, new eval cases, new topic files
+- **Major** (`X.0.0`): breaking restructure of skill entry points or routing logic
+
+Document the change in `CHANGELOG.md` under a new `[x.y.z]` heading.
+
+## Plugin & Marketplace Registration
+
+This skill is published to:
+
+- **[agentskills.io](https://agentskills.io)** — open skill registry (`.claude-plugin/marketplace.json`)
+- **Claude Code plugin marketplace** — hosted at `AgoraIO/skills` on GitHub (`.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json`)
+
+Users install via two slash commands inside Claude Code:
+
+```
+/plugin marketplace add AgoraIO/skills
+/plugin install agora@agora-skills
+```
+
+(`agora-skills` is the marketplace `name` in `marketplace.json`; `agora` is the plugin `name`.)
+
+To update a registration after a version bump:
+1. Submit a PR with the bumped version in both JSON files
+2. Once merged, users get the update automatically when Claude Code refreshes (`/plugin marketplace update`)
+3. For agentskills.io manual updates, follow the [agentskills.io submission guide](https://agentskills.io)
+
+The Agora MCP server config is bundled in `.claude-plugin/mcp-config.json` and
+referenced from `plugin.json` via `"mcpServers": "./mcp-config.json"`.
+
+## Verifying URLs
+
+Before opening a PR, check that all `https://` links in skill files are reachable:
+
+```bash
+grep -roh 'https://[^ )]*' skills/ | sort -u | while read url; do
+  code=$(curl -s -o /dev/null -w "%{http_code}" -L --max-time 10 "$url")
+  echo "$code $url"
+done
+```
+
+Any non-200 response (except intentional 301 redirects) should be investigated and fixed.
+
 ## Code of Conduct
 
 This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to uphold this code.

diff --git a/README.md b/README.md
@@ -4,41 +4,57 @@ Structured reference knowledge for [Agora](https://www.agora.io) (agora.io) real
 
 ## Installation
 
-### Option A: Skills CLI (recommended)
+### Skills CLI (recommended)
 
 ```bash
-npx skills add github:AgoraIO-Conversational-AI/skills
+npx skills add github:AgoraIO/skills
 ```
 
 Skills activate automatically when your agent detects relevant tasks (e.g., "build a voice agent", "integrate Agora RTC", "generate a token").
 
-### Option B: Git clone
+### Claude Code Plugin (recommended if using Claude)
+
+Install Agora skills and the Agora Docs MCP server as a Claude Code plugin. Run these two slash commands inside Claude Code:
+
+```
+/plugin marketplace add AgoraIO/skills
+/plugin install agora@agora-skills
+```
+
+The Agora MCP server (`mcp.agora.io`) is bundled automatically — no separate MCP configuration needed.
+
+### Git clone
 
 Clone the repo once, then point your tool at `skills/agora/`:
 
 ```bash
-git clone https://github.com/AgoraIO-Conversational-AI/skills.git ~/agora-skills
+git clone https://github.com/AgoraIO/skills.git ~/agora-skills
 ```
 
+### Configure with your Agent or IDE (optional)
+
 **Claude Code — symlink (user-level):**
 
+When installing the skill using the Skills CLI, you can symlink the skill to your home directory. This will make the skill available to all your agents.
+
 ```bash
-mkdir -p ~/.claude/skills
 ln -s ~/agora-skills/skills/agora ~/.claude/skills/agora
 ```
 
 **Claude Code — copy (project-level, shared with team):**
 
+When installing the skill using the Claude Code Plugin, you can copy the skill to your project directory. This will make the skill available to all your agents in the project.
+
 ```bash
 mkdir -p .claude/skills
 cp -r ~/agora-skills/skills/agora .claude/skills/agora
 ```
 
-**Cursor:** Copy or symlink into `.cursor/rules/`.
+**Cursor:** Copy or symlink into `.cursor/rules/`. See [Cursor skills docs](https://cursor.com/docs/skills#skill-directories).
 
-**Windsurf:** Add `skills/agora/` to your Cascade context.
+**Windsurf:** Add `skills/agora/` to your Cascade context. See [Windsurf skills docs](https://docs.windsurf.com/windsurf/cascade/skills).
 
-**GitHub Copilot:** Reference via `@workspace` or add to `.github/copilot-instructions.md`.
+**GitHub Copilot:** Reference via `@workspace` or add to `.github/copilot-instructions.md`. See [Copilot CLI skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-skills) and [Copilot Agents skills](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills).
 
 **Any other tool:** The skill files are plain markdown. Point your tool at `skills/agora/` or load individual files directly. Use `SKILL.md` as the entry point — it links to everything else.
 
@@ -50,11 +66,13 @@ This repo contains markdown skill files that give AI coding assistants deep know
 
 **Products covered:**
 
-- **RTC (Video/Voice SDK)** — Web, React, iOS (Swift), Android (Kotlin/Java)
+- **RTC (Video/Voice SDK)** — Web, React, Next.js, iOS (Swift), Android (Kotlin/Java)
 - **RTM (Signaling)** — Web (JS/TS) messaging, presence, metadata, stream channels
-- **Conversational AI** — REST API, agent config, 5 recipe repos (agent-samples, agent-toolkit, agent-ui-kit, server-custom-llm, server-mcp)
+- **Conversational AI** — REST API, agent config, Gemini Live + OpenAI Realtime MLLM, 6 recipe repos (agent-samples, agent-toolkit, agent-client-toolkit-react, agent-ui-kit, server-custom-llm, server-mcp)
+- **Cloud Recording** — REST API acquire/start/query/stop lifecycle
+- **Server Gateway** — Linux SDK (C++) for server-side RTC
 - **Server-Side** — Token generation for Node.js, Python, Go
-
+- **Testing Guidance** — ConvoAI and RTC testing patterns
 
 ## Design — 4-Layer Progressive Disclosure
 
@@ -79,37 +97,47 @@ Not all content belongs inline. The skill uses two strategies depending on how f
 | **RTC / RTM**         | Inline code examples                     | Stable APIs, official docs lack good examples |
 | **Server / Tokens**   | TOC + links to official docs             | Well-documented at docs.agora.io              |
 
-
-ConvoAI files are aligned 1:1 with repos in [AgoraIO-Conversational-AI](https://github.com/AgoraIO-Conversational-AI). Each file maps to one repo and links to its README and AGENT.md as sources of truth. Gotchas and quirks that LLMs consistently get wrong stay inline in the ConvoAI README.
+ConvoAI files are aligned 1:1 with repos in [AgoraIO-Conversational-AI](https://github.com/orgs/AgoraIO-Conversational-AI/repositories). Each file maps to one repo and links to its README and AGENT.md as sources of truth. Gotchas and quirks that LLMs consistently get wrong stay inline in the ConvoAI README.
 
 ## File Structure
 
 ```
 skills/
-└── agora/                                                   Skill root
-    ├── SKILL.md                            (72 lines)   Entry point, product index
+└── agora/                          Skill root
+    ├── SKILL.md                    Entry point, product index
+    ├── intake/
+    │   └── SKILL.md                Multi-product needs analysis router
     └── references/
-        ├── mcp-tools.md                    (93 lines)   MCP tool reference and graceful degradation
-        ├── rtc/                                          RTC (Video/Voice SDK)
-        │   ├── README.md                   (85 lines)   Critical rules, encoder profiles, cross-platform notes
-        │   ├── web.md                     (498 lines)   agora-rtc-sdk-ng: client, tracks, events, screen share
-        │   ├── react.md                   (295 lines)   agora-rtc-react: hooks, custom patterns
-        │   ├── nextjs.md                               Next.js / SSR dynamic import patterns
-        │   ├── ios.md                     (301 lines)   AgoraRtcEngineKit (Swift): setup, delegation
-        │   └── android.md                 (340 lines)   RtcEngine (Kotlin/Java): setup, callbacks
-        ├── rtm/                                          RTM (Signaling / Messaging)
-        │   ├── README.md                   (25 lines)   Key concepts, platform links
-        │   └── web.md                     (375 lines)   agora-rtm v2: messaging, presence, stream channels
-        ├── conversational-ai/                            Conversational AI (Voice AI Agents)
-        │   ├── README.md                  (100 lines)   Architecture, endpoints, auth, lifecycle, REST API + config links, gotchas
-        │   ├── agent-samples.md            (80 lines)   Backend, React clients, profiles, MLLM, deployment
-        │   ├── agent-toolkit.md            (57 lines)   @agora/conversational-ai SDK: API, helpers, hooks
-        │   ├── agent-ui-kit.md             (52 lines)   @agora/agent-ui-kit React components
-        │   ├── server-custom-llm.md        (36 lines)   Custom LLM proxy: RAG, tools, memory
-        │   └── server-mcp.md               (38 lines)   MCP memory server: persistent per-user memory
-        ├── server/                                       Server-Side (Tokens)
-        │   ├── README.md                   (20 lines)   Token types, when tokens are needed
-        │   └── tokens.md                   (34 lines)   Token generation TOC + links to official docs
+        ├── doc-fetching.md         Two-tier lookup procedure (agent-facing)
+        ├── mcp-tools.md            MCP tool reference and graceful degradation
+        ├── rtc/                    RTC (Video/Voice SDK)
+        │   ├── README.md           Critical rules, encoder profiles, cross-platform notes
+        │   ├── web.md              agora-rtc-sdk-ng: client, tracks, events, screen share
+        │   ├── react.md            agora-rtc-react: hooks, custom patterns
+        │   ├── nextjs.md           Next.js / SSR dynamic import patterns
+        │   ├── ios.md              AgoraRtcEngineKit (Swift): setup, delegation
+        │   └── android.md          RtcEngine (Kotlin/Java): setup, callbacks
+        ├── rtm/                    RTM (Signaling / Messaging)
+        │   ├── README.md           Key concepts, platform links
+        │   └── web.md              agora-rtm v2: messaging, presence, stream channels
+        ├── conversational-ai/      Conversational AI (Voice AI Agents)
+        │   ├── README.md           Architecture, endpoints, auth, lifecycle, gotchas
+        │   ├── agent-samples.md    Backend, React clients, profiles, MLLM, deployment
+        │   ├── agent-toolkit.md    @agora/conversational-ai SDK: API, helpers, hooks
+        │   ├── agent-client-toolkit-react.md   React hooks: provider, transcript, state
+        │   ├── agent-ui-kit.md     @agora/agent-ui-kit React components
+        │   ├── server-custom-llm.md  Custom LLM proxy: RAG, tools, memory
+        │   └── server-mcp.md       MCP memory server: persistent per-user memory
+        ├── cloud-recording/        Cloud Recording (REST API)
+        │   └── README.md           acquire/start/query/stop lifecycle, storage config
+        ├── server-gateway/         Server Gateway (Linux SDK)
+        │   ├── README.md           Overview, use cases, critical notes
+        │   └── linux-cpp.md        C++ SDK: setup, callbacks, media pipeline
+        ├── server/                 Server-Side (Tokens)
+        │   ├── README.md           Token types, when tokens are needed
+        │   └── tokens.md           Token generation TOC + links to official docs
+        └── testing-guidance/       Testing Patterns
+            └── SKILL.md            ConvoAI and RTC test setup, mocking patterns
 ```
 
 ## Maintaining and Extending

diff --git a/SECURITY.md b/SECURITY.md
@@ -6,7 +6,7 @@ If you discover a security vulnerability in this project, please report it respo
 
 **Do not open a public issue.**
 
-Instead, use [GitHub's private vulnerability reporting](https://github.com/BenWeekes/skills/security/advisories/new) to submit your report. This ensures the issue can be assessed and addressed before public disclosure.
+Instead, use [GitHub's private vulnerability reporting](https://github.com/AgoraIO/skills/security/advisories/new) to submit your report. This ensures the issue can be assessed and addressed before public disclosure.
 
 For security issues in the broader Agora platform, please follow the reporting process at [https://www.agora.io/en/security](https://www.agora.io/en/security).
 

diff --git a/scripts/blocklist.txt b/scripts/blocklist.txt