botpress__skills/README.md

Botpress Skills

A collection of skills for AI coding agents building with Botpress. Skills are packaged instructions and documentation that extend agent capabilities for Botpress development.

Skills follow the Agent Skills format.

Available Skills

botpress-adk

Comprehensive documentation and guidelines for building AI agents with the Botpress Agent Development Kit (ADK). A convention-based TypeScript framework where file structure maps directly to bot behavior.

Use when:

• Building new features with the Botpress ADK
• Working with Actions, Tools, or Workflows
• Implementing data storage (Tables, Files, Knowledge Bases)
• Using Zai for AI operations (extract, check, label, summarize)
• Configuring integrations, plugins, or bot settings
• Setting up event-driven triggers
• Need CLI commands or MCP server setup

Categories covered:

• Core Concepts - Actions (strongly-typed functions), Tools (AI-callable), Workflows (long-running processes), Conversations (message handlers), Triggers (event-driven automation)
• Data & Content - Tables (structured storage with semantic search), Files (file storage and management), Knowledge Bases (RAG implementation)
• AI Features - Zai (production-ready LLM utility library for common AI operations)
• Configuration - Agent config, integrations, plugins, context API, environment variables
• Development Tools - CLI reference, MCP server integration, project structure best practices

botpress-adk-frontend

Production-tested patterns for building frontend applications that integrate with Botpress ADK bots. Covers authentication, type-safe API calls, client management, and type generation workflows.

Use when:

• Building a frontend that connects to a Botpress bot
• Implementing authentication with Personal Access Tokens (PATs)
• Setting up the @botpress/client
• Calling bot actions from React/Next.js
• Generating and using TypeScript types from your bot
• Managing client state and caching
• Handling errors and optimistic updates

Categories covered:

• Authentication - Cookie-based PAT storage, OAuth flow, route protection, token management
• Client Management - Zustand store patterns, client caching and reuse, workspace vs bot-scoped clients
• Type Generation - Triple-slash references, importing generated types, type-safe action calls
• Action Calls - React Query patterns, error handling, optimistic updates, proper typing

Key technologies:

• @botpress/client (official TypeScript client)
• TypeScript triple-slash references
• React Query (optional, recommended for mutations)
• Zustand (for client state management)

botpress-adk-evals

Complete reference for writing, running, and iterating on evals (automated conversation tests) for ADK agents. Covers eval file format, all assertion types, CLI usage, and per-primitive testing patterns.

Use when:

• Writing automated tests for an ADK agent
• Learning the eval file format and assertion types
• Running evals and interpreting results
• Testing specific primitives (actions, tools, workflows, conversations, tables)
• Integrating evals into CI pipelines

Categories covered:

• Eval Format - File structure, turn types, all assertion categories (response, tools, state, tables, workflow, timing)
• Testing Workflow - Running evals, interpreting output, using traces, the write-test-iterate loop
• Test Patterns - Per-primitive testing patterns for actions, tools, workflows, conversations, tables, and state

botpress-adk-docs

Guidelines and commands for creating, reviewing, updating, and maintaining documentation for your ADK bot. Helps you document your own workflows, actions, and features with accurate, searchable guides.

Use when:

• Creating documentation for your bot's features and workflows
• Reviewing existing project docs for accuracy and completeness
• Updating docs after changing your bot's code
• Checking if your docs are in sync with implementation
• Searching your project documentation

Categories covered:

• Documentation Standards - Document types (reference, conceptual, comprehensive), templates, quality checklists
• Creation - Research-first workflow for writing docs with verified code examples from your bot
• Review - Code accuracy, searchability, completeness, and ADK-specific concerns
• Maintenance - Updating, syncing, and searching your project documentation

botpress-adk-debugger

Systematic debugging for ADK agents. Teaches the AI assistant how to read traces and logs, diagnose common failures, debug LLM behavior issues, and follow a structured debug workflow.

Use when:

• Bot isn't responding or behaves unexpectedly
• Tool calls are failing or the wrong tool is selected
• Workflows are stuck or steps aren't executing
• LLM is hallucinating, refusing, or looping
• Build or deploy errors occur
• Need to read and interpret traces or logs
• Debugging config issues (agent.json vs agent.local.json)

Categories covered:

• Traces & Logs - CLI tools (adk check, adk logs, adk traces, adk chat), trace structure, span types, onTrace hooks
• Common Failures - Runtime failure patterns with symptom-to-fix workflows
• LLM Debugging - Wrong tool selection, hallucinated parameters, refusals, looping, reading model reasoning
• Debug Workflow - Systematic 8-step loop: validate, reproduce, logs, traces, classify, fix, verify, prevent

Commands

Commands are thin Claude Code slash commands that load skills. They are the quick entry point - type /adk-debug 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 in your bot
/adk-doc-review	Review project docs for accuracy and completeness
/adk-doc-update	Update project docs after code changes
/adk-doc-sync	Check if project docs are in sync with your bot's code
/adk-doc-search	Search your project documentation

Installing commands

Install the plugin in Claude Code to get all skills and commands:

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

Installation

npx skills add botpress/skills --skill adk

Usage

Skills are automatically available once installed. The agent will use them when relevant tasks are detected.

Examples:

Create an Action that fetches user data

How do I use Zai to extract structured data?

Show me how to call my bot's actions from a Next.js frontend

Set up authentication for my React app with Botpress

My bot isn't responding — how do I debug this?

Write an eval that tests my createTicket tool

Skill Structure

Each skill contains:

• SKILL.md - Instructions for the agent
• references/ - Supporting documentation files

skills/                       # Heavy knowledge (skills)
├── adk/                      # Core ADK framework (23 reference docs)
│   ├── SKILL.md
│   └── references/
├── adk-frontend/             # Frontend integration (11 reference docs)
│   ├── SKILL.md
│   └── references/
├── adk-evals/                # Testing & evals (3 reference docs)
│   ├── SKILL.md
│   └── references/
├── adk-debugger/             # Debugging & observability (4 reference docs)
│   ├── SKILL.md
│   └── references/
└── adk-docs/                 # Documentation management (1 reference doc)
    ├── SKILL.md
    └── references/

commands/                     # Thin slash commands (load skills)
├── adk-init.md               # /adk-init - scaffolding
├── adk-debug.md              # /adk-debug - loads adk-debugger skill
├── adk-eval.md               # /adk-eval - loads adk-evals skill
├── adk-frontend.md           # /adk-frontend - loads adk-frontend skill
├── adk-integration.md        # /adk-integration - loads adk skill for integration management
├── adk-doc-create.md         # /adk-doc-create - loads adk-docs skill
├── adk-doc-review.md         # /adk-doc-review - loads adk-docs skill
├── adk-doc-update.md         # /adk-doc-update - loads adk-docs skill
├── adk-doc-sync.md           # /adk-doc-sync - loads adk-docs skill
└── adk-doc-search.md         # /adk-doc-search - loads adk-docs skill

License

MIT