Rewrite ADK documentation

adk/advanced/hitl.mdx

@@ -0,0 +1,157 @@
+---
+title: Human-in-the-loop
+description: Escalate conversations to live human agents.
+---
+
+<Info>
+  This covers the HITL integration and plugin, which connects your agent to external helpdesk platforms (Zendesk, Intercom, etc.). This is separate from integrating your ADK agent with [Botpress Desk](/desk/introduction).
+</Info>
+
+HITL (Human-in-the-Loop) lets your agent hand off a conversation to a live human agent. This is powered by two dependencies working together: the **HITL integration** (provides the transport to a helpdesk or agent platform) and the **HITL plugin** (provides the actions your code calls).
+
+## Setup
+
+Add both the integration and plugin to `agent.config.ts`:
+
+```typescript
+import { defineConfig } from "@botpress/runtime"
+
+export default defineConfig({
+  name: "my-agent",
+
+  defaultModels: {
+    autonomous: "openai:gpt-4.1-mini-2025-04-14",
+    zai: "openai:gpt-4.1-mini-2025-04-14",
+  },
+
+  dependencies: {
+    integrations: {
+      chat: { version: "chat@0.7.3", enabled: true },
+      webchat: { version: "webchat@0.3.0", enabled: true },
+      hitl: { version: "hitl@2.0.2", enabled: true },
+    },
+
+    plugins: {
+      hitl: {
+        version: "hitl@1.3.0",
+        dependencies: {
+          hitl: {
+            integrationAlias: "hitl",
+            integrationInterfaceAlias: "hitl<hitlSession>",
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+### How the plugin wiring works
+
+The `plugins` block connects the plugin to the integration:
+
+```typescript
+plugins: {
+  hitl: {
+    version: "hitl@1.3.0",
+    dependencies: {
+      hitl: {
+        integrationAlias: "hitl",           // Must match a key in dependencies.integrations
+        integrationInterfaceAlias: "hitl<hitlSession>",
+      },
+    },
+  },
+},
+```
+
+`integrationAlias` tells the plugin which installed integration to use. It must match a key in `dependencies.integrations`. The ADK validates this at build time.
+
+### Optional plugin config
+
+```typescript
+plugins: {
+  hitl: {
+    version: "hitl@1.3.0",
+    config: {
+      flowOnHitlStopped: false,
+      useHumanAgentInfo: false,
+    },
+    dependencies: { /* ... */ },
+  },
+},
+```
+
+## Starting a handoff
+
+Import `plugins` from `@botpress/runtime` and call `startHitl`. All inputs are fully typed.
+
+```typescript
+import { Conversation, plugins } from "@botpress/runtime"
+
+export default new Conversation({
+  channel: ["chat.channel", "webchat.channel"],
+  handler: async ({ execute, conversation, message }) => {
+    if (message.payload.text.toLowerCase() === "/starthitl") {
+      await plugins.hitl.actions.startHitl({
+        title: "Support HITL",
+        description: "Escalate to support agent",
+        conversationId: conversation.id,
+        userId: message.userId,
+        configurationOverrides: {
+          onHitlHandoffMessage: "Escalating to support...",
+          userHitlCloseCommand: "/end",
+          agentAssignedTimeoutSeconds: 100,
+        },
+      })
+      return
+    }
+
+    await execute({
+      instructions: "You are a helpful assistant. If the user asks for a human, tell them to type /starthitl.",
+    })
+  },
+})
+```
+
+## Using a different provider
+
+The HITL plugin works with any integration that implements the HITL interface. To use Zendesk instead of the generic HITL integration, swap the integration and update the alias:
+
+```typescript
+dependencies: {
+  integrations: {
+    zendesk: { version: "zendesk@1.0.0", enabled: true },
+  },
+  plugins: {
+    hitl: {
+      version: "hitl@1.3.0",
+      dependencies: {
+        hitl: {
+          integrationAlias: "zendesk",
+          integrationInterfaceAlias: "hitl<hitlTicket>",
+        },
+      },
+    },
+  },
+},
+```
+
+The plugin doesn't care about the specific provider, only that it implements the HITL interface.
+
+## Deploy and test
+
+```bash
+adk deploy
+```
+
+<Warning>
+  HITL does not work in dev mode because conversations don't exist on the dev bot. You must deploy and test on the production bot.
+</Warning>
+
+When you run `adk dev`, the ADK downloads the plugin, installs it into `bp_modules/`, and generates TypeScript types. But testing the actual handoff requires a deployed bot.
+
+---
+
+<Card title="CLI Reference" icon="terminal" href="/adk/cli-reference">
+  All commands and flags available with the ADK CLI.
+</Card>

adk/ai-native/skills.mdx

@@ -0,0 +1,87 @@
+---
+title: Skills
+description: Give AI coding assistants deep ADK knowledge with installable skills.
+---
+
+Skills are packaged instructions and documentation that teach AI coding assistants how to build with the ADK. When installed, your assistant (Claude Code, Cursor, Codex) automatically uses them when you ask it to build features, debug issues, write evals, or connect integrations.
+
+Skills are packaged with every new ADK project. When you run `adk init`, skills are installed automatically alongside your dependencies.
+
+## Manual installation
+
+If you need to install skills in an existing project or reinstall them:
+
+```bash
+npx skills add botpress/skills -s '*' -a claude-code codex -y
+```
+
+Install a single skill:
+
+```bash
+npx skills add botpress/skills --skill adk
+```
+
+Or install as a Claude Code plugin:
+
+```
+/plugin marketplace add botpress/skills
+/plugin install adk@botpress-skills
+```
+
+## Available skills
+
+| Skill | What it teaches | Use when |
+|-------|----------------|----------|
+| **adk** | Core ADK framework: actions, tools, workflows, conversations, tables, knowledge, triggers, Zai, configuration | Building any feature with the ADK |
+| **adk-debugger** | Trace reading, log analysis, common failure diagnosis, the debug loop | Bot isn't responding, tools failing, workflows stuck, LLM issues |
+| **adk-evals** | Eval file format, all assertion types, CLI usage, per-primitive testing patterns | Writing and running automated tests |
+| **adk-frontend** | Authentication, type generation, client setup, calling bot actions from React/Next.js | Building a frontend that connects to your bot |
+| **adk-integrations** | Discovery, adding, configuring, and using integrations end-to-end | Connecting Slack, WhatsApp, Linear, or any integration |
+| **adk-docs** | Documentation standards, creation, review, and maintenance | Writing or updating docs for your bot |
+
+## Slash commands
+
+Skills come with slash commands for Claude Code. Type the command instead of describing what you need:
+
+| Command | What it does |
+|---------|-------------|
+| `/adk-init` | Scaffold a new ADK project |
+| `/adk-debug` | Debug bot issues using traces, logs, and the debug loop |
+| `/adk-eval` | Write, run, or debug evals |
+| `/adk-frontend` | Build frontend apps that integrate with ADK bots |
+| `/adk-integration` | Discover, add, and configure integrations |
+| `/adk-doc-create` | Create documentation for a feature |
+| `/adk-doc-review` | Review project docs for accuracy |
+| `/adk-doc-update` | Update docs after code changes |
+| `/adk-doc-sync` | Check if docs are in sync with code |
+| `/adk-doc-search` | Search project documentation |
+
+## MCP server
+
+The ADK also includes an MCP (Model Context Protocol) server that gives assistants live access to your running project. It provides tools for querying traces, searching integrations, sending test messages, and starting workflows.
+
+Generate the MCP configuration:
+
+```bash
+adk mcp:init --all
+```
+
+This creates config files for Claude Code (`.mcp.json`), VS Code (`.vscode/mcp.json`), and Cursor (`.cursor/mcp.json`).
+
+| Tool | What it does |
+|------|-------------|
+| `adk_get_agent_info` | Get project structure and primitives |
+| `adk_search_integrations` | Search the Botpress Hub |
+| `adk_get_integration` | Get detailed integration info |
+| `adk_add_integration` | Add an integration to the project |
+| `adk_send_message` | Send a test message to the running bot |
+| `adk_query_traces` | Query trace spans for debugging |
+| `adk_get_dev_logs` | Get dev server logs and errors |
+| `adk_list_workflows` | List available workflows |
+| `adk_start_workflow` | Start a workflow or get its input schema |
+
+---
+
+<Card title="Human-in-the-loop" icon="user" href="/adk/advanced/hitl">
+  Escalate conversations to live human agents.
+</Card>