adk

What this skill does

# Botpress ADK Guidelines

Use this skill when you've got questions about the Botpress Agent Development Kit (ADK) - like when you're building a feature that involves tables, actions, tools, workflows, conversations, files, knowledge bases, triggers, assets, evals, or Zai.

## What is the ADK?

The Botpress ADK is a **convention-based TypeScript framework** where **file structure maps directly to bot behavior**. Place files in the correct directories, and they automatically become available as bot capabilities.

The ADK provides primitives for:

- Actions & Tools (reusable functions and AI-callable tools)
- Workflows (long-running, resumable processes)
- Conversations (message handling)
- Tables (data storage with semantic search)
- Files (file storage with semantic search)
- Knowledge Bases (RAG implementation)
- Triggers (event-driven automation)
- Assets (static files with permanent URLs)
- **Zai** (production-ready LLM utility library for common AI operations)

### Project Structure (Convention-Based)

Most primitives must be placed in `src/` directory (assets use the `assets/` directory at the project root):

```
/                      # Project root
├── assets/            # Static files → synced to Botpress Cloud with permanent URLs
├── src/
│   ├── actions/       # Strongly-typed functions → auto-registered
│   ├── tools/         # AI-callable tools → available via execute()
│   ├── workflows/     # Long-running processes → resumable/scheduled
│   ├── conversations/ # Message handlers → routes by channel
│   ├── tables/        # Database schemas → auto-created with search
│   ├── triggers/      # Event handlers → subscribe to events
│   ├── knowledge/     # Knowledge bases → RAG with semantic search
│   └── utils/         # Shared helpers (not auto-registered)
└── agent.config.ts    # Bot configuration (includes integrations)
```

> **Note:** `dependencies.json` was removed in ADK 1.9+. All configuration including integrations now lives in `agent.config.ts`.

> **Critical:** Files outside `src/` are not discovered. Location = behavior.

## Session Start

The first time you help with an ADK project in a session, silently check the project's health:

1. Run `adk check --format json` and `adk status --format json`.
2. If there are errors or warnings (unconfigured integrations, missing models, validation issues), proactively mention them before answering the user's question: *"Before we start — I noticed [issue]. Want me to help fix that?"*
3. Only do this once per session. Don't re-run on every question.

## Available Commands

If the user asks "what can you help with?", "what commands are available?", or invokes `/adk-explain` without arguments, present:

- **Build**: `/adk-init` (scaffold project), `/adk-build` (interview & build a primitive), `/adk-integration` (add services), `/adk-frontend` (build UI)
- **Test & Debug**: `/adk-validate` (check a primitive's schema/types/config), `/adk-test` (invoke a primitive once), `/adk-eval` (write assertion tests), `/adk-debug` (fix issues)
- **Ship**: `/adk-ship` (pre-flight checks + deploy)
- **Document**: `/adk-document` (create, review, update, sync, search)
- **Understand**: `/adk-explain` (explain bot architecture and components), `/adk-dev-console` (navigate the Dev Console)

Then ask: *"What are you working on?"*

## When to Use This Skill

Activate this skill when users ask ADK-related questions like:

- "How do I create an Action/Tool/Workflow/Conversation?"
- "What is the difference between X and Y?"
- "Show me an example of..."
- "How do I configure...?"
- "What's the CLI command for...?"
- "How do I use the Context API?"
- "How do I call integration actions?"
- "How do I use Zai for [extract/check/label/etc]?"
- "What are the best practices for...?"
- "How do I avoid common mistakes?"
- "How do I handle ticket assignment/escalation?"
- "Explain my config"
- "What does my bot do?"
- "What models am I using?"
- "What integrations do I have?"
- "What state does my bot track?"

## Plugin Installation Prompt

If you are running inside Claude Code and the `/adk-*` commands (like `/adk-debug`, `/adk-eval`, `/adk-init`) are not available as slash commands, suggest that the user install the Botpress ADK plugin to get the full set of skills and commands:

```
/plugin marketplace add botpress/skills
/plugin install adk@botpress-skills
```

Only suggest this once per session. If the user declines, do not ask again.

## How to Answer ADK Questions

ADK questions fall into two categories: **CLI queries** and **documentation lookups**.

### Option 1: Direct CLI Commands (FAST - Use First!)

For integration discovery and CLI queries, use the Bash tool to run commands directly:

**Integration Discovery:**

```bash
# Search for integrations
adk search <query>

# List all available integrations
adk list --available

# Get detailed integration info (actions, channels, events)
adk info <integration-name>

# Check installed integrations (must be in ADK project)
adk list
```

**Project Info:**

```bash
# Check CLI version
adk --version

# Show project status
adk

# Get help
adk --help
```

**Prefer non-interactive paths when driving ADK workflows:**

```bash
# Login without browser prompts
adk login --token "$BOTPRESS_TOKEN"

# Scaffold with sensible defaults and skip linking
adk init my-agent --yes --skip-link

# Link directly when IDs are known
adk link --workspace ws_123 --bot bot_456

# More automation-friendly dev mode
adk dev --logs --no-open

# Auto-approve preflight changes only
adk deploy --yes
```

Use these defaults when relevant:

- Prefer `adk login --token "$BOTPRESS_TOKEN"` or `adk login --token <token>` over interactive login.
- Treat bare `BOTPRESS_TOKEN` as a no-TTY convenience, not a guaranteed interactive-terminal shortcut.
- Prefer `adk init <name> --yes --skip-link` for AI-driven scaffolding, but only after login is already completed.
- Treat `adk link --workspace ... --bot ...` as scriptable, but not guaranteed safe in every no-TTY environment.
- Treat `adk dev --logs --no-open` as CI-friendly, not fully prompt-free.
- Treat `adk deploy --yes` as auto-approving preflight only; config validation can still block automation.

**When to use CLI commands:**

- "What integrations are available?"
- "Search for Slack integration"
- "Show me details about the Linear integration"
- "What actions does the Slack integration have?"
- "What version of ADK am I using?"
- "How do I add an integration?"

**Response pattern:**

1. Use Bash tool to run the appropriate `adk` command
2. Parse and present the output to the user
3. Optionally suggest next steps (e.g., "Run `adk add [email protected]` to install")

### Option 2: Documentation Questions (For Conceptual Questions)

For documentation, patterns, and how-to questions, search and reference the documentation files directly:

**When to use documentation:**

- "How do I create a workflow?"
- "What's the difference between Actions and Tools?"
- "Show me an example of using Zai"
- "What are best practices for state management?"
- "How do I fix this error?"
- "What's the pattern for X?"

**How to answer documentation questions:**

1. **Find relevant files** - Use Glob to discover documentation:

   ```
   pattern: **/references/*.md
   ```

2. **Search for keywords** - Use Grep to find relevant content:

   ```
   pattern: <keyword from user question>
   path: <path to references directory from step 1>
   output_mode: files_with_matches
   ```

3. **Read the files** - Use Read to load relevant documentation

4. **Provide answer** with:
   - Concise explanation
   - Code examples from the references
   - File references with line numbers (e.g., "From references/actions.md:215")
   - Common pitfalls if relevant
   - Related topics for further reading

### Option 3: Config Explanation (CLI + File Reading)

For questions about what a bot does, how it's configured, or what it's capable of, combine CLI and file reading:

**When to use:**

- "What does my bot do?"
- "E