{ "markdown": "

\n \n \n \n \n

\n\n# Botpress Skills\n\nA collection of skills for AI coding agents building with Botpress. Skills are packaged instructions and documentation that extend agent capabilities for Botpress development.\n\nSkills follow the [Agent Skills](https://agentskills.io/) format.\n\n## Available Skills\n\n### botpress-adk\n\nComprehensive 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.\n\n**Use when:**\n\n- Building new features with the Botpress ADK\n- Working with Actions, Tools, or Workflows\n- Implementing data storage (Tables, Files, Knowledge Bases)\n- Using Zai for AI operations (extract, check, label, summarize)\n- Configuring integrations, plugins, or bot settings\n- Setting up event-driven triggers\n- Need CLI commands or MCP server setup\n\n**Categories covered:**\n\n- **Core Concepts** - Actions (strongly-typed functions), Tools (AI-callable), Workflows (long-running processes), Conversations (message handlers), Triggers (event-driven automation)\n- **Data & Content** - Tables (structured storage with semantic search), Files (file storage and management), Knowledge Bases (RAG implementation)\n- **AI Features** - Zai (production-ready LLM utility library for common AI operations)\n- **Configuration** - Agent config, integrations, plugins, context API, environment variables\n- **Development Tools** - CLI reference, MCP server integration, project structure best practices\n\n### botpress-adk-frontend\n\nProduction-tested patterns for building frontend applications that integrate with Botpress ADK bots. Covers authentication, type-safe API calls, client management, and type generation workflows.\n\n**Use when:**\n\n- Building a frontend that connects to a Botpress bot\n- Implementing authentication with Personal Access Tokens (PATs)\n- Setting up the @botpress/client\n- Calling bot actions from React/Next.js\n- Generating and using TypeScript types from your bot\n- Managing client state and caching\n- Handling errors and optimistic updates\n\n**Categories covered:**\n\n- **Authentication** - Cookie-based PAT storage, OAuth flow, route protection, token management\n- **Client Management** - Zustand store patterns, client caching and reuse, workspace vs bot-scoped clients\n- **Type Generation** - Triple-slash references, importing generated types, type-safe action calls\n- **Action Calls** - React Query patterns, error handling, optimistic updates, proper typing\n\n**Key technologies:**\n\n- @botpress/client (official TypeScript client)\n- TypeScript triple-slash references\n- React Query (optional, recommended for mutations)\n- Zustand (for client state management)\n\n### botpress-adk-evals\n\nComplete 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.\n\n**Use when:**\n\n- Writing automated tests for an ADK agent\n- Learning the eval file format and assertion types\n- Running evals and interpreting results\n- Testing specific primitives (actions, tools, workflows, conversations, tables)\n- Integrating evals into CI pipelines\n\n**Categories covered:**\n\n- **Eval Format** - File structure, turn types, all assertion categories (response, tools, state, tables, workflow, timing)\n- **Testing Workflow** - Running evals, interpreting output, using traces, the write-test-iterate loop\n- **Test Patterns** - Per-primitive testing patterns for actions, tools, workflows, conversations, tables, and state\n\n### botpress-adk-docs\n\nGuidelines 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.\n\n**Use when:**\n\n- Creating documentation for your bot's features and workflows\n- Reviewing existing project docs for accuracy and completeness\n- Updating docs after changing your bot's code\n- Checking if your docs are in sync with implementation\n- Searching your project documentation\n\n**Categories covered:**\n\n- **Documentation Standards** - Document types (reference, conceptual, comprehensive), templates, quality checklists\n- **Creation** - Research-first workflow for writing docs with verified code examples from your bot\n- **Review** - Code accuracy, searchability, completeness, and ADK-specific concerns\n- **Maintenance** - Updating, syncing, and searching your project documentation\n\n### botpress-adk-debugger\n\nSystematic 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.\n\n**Use when:**\n\n- Bot isn't responding or behaves unexpectedly\n- Tool calls are failing or the wrong tool is selected\n- Workflows are stuck or steps aren't executing\n- LLM is hallucinating, refusing, or looping\n- Build or deploy errors occur\n- Need to read and interpret traces or logs\n- Debugging config issues (agent.json vs agent.local.json)\n\n**Categories covered:**\n\n- **Traces & Logs** - CLI tools (`adk check`, `adk logs`, `adk traces`, `adk chat`), trace structure, span types, `onTrace` hooks\n- **Common Failures** - Runtime failure patterns with symptom-to-fix workflows\n- **LLM Debugging** - Wrong tool selection, hallucinated parameters, refusals, looping, reading model reasoning\n- **Debug Workflow** - Systematic 8-step loop: validate, reproduce, logs, traces, classify, fix, verify, prevent\n\n## Commands\n\nCommands are thin Claude Code slash commands that load skills. They are the quick entry point - type `/adk-debug` instead of describing what you need.\n\n| Command | What it does |\n| ------------------ | ------------------------------------------------------- |\n| `/adk-init` | Scaffold a new ADK project |\n| `/adk-debug` | Debug bot issues using traces, logs, and the debug loop |\n| `/adk-eval` | Write, run, or debug evals |\n| `/adk-frontend` | Build frontend apps that integrate with ADK bots |\n| `/adk-integration` | Discover, add, and configure integrations |\n| `/adk-doc-create` | Create documentation for a feature in your bot |\n| `/adk-doc-review` | Review project docs for accuracy and completeness |\n| `/adk-doc-update` | Update project docs after code changes |\n| `/adk-doc-sync` | Check if project docs are in sync with your bot's code |\n| `/adk-doc-search` | Search your project documentation |\n\n### Installing commands\n\nInstall the plugin in Claude Code to get all skills and commands:\n\n```\n/plugin marketplace add botpress/skills\n/plugin install adk@botpress-skills\n```\n\n## Installation\n\n```bash\nnpx skills add botpress/skills --skill adk\n```\n\n## Usage\n\nSkills are automatically available once installed. The agent will use them when relevant tasks are detected.\n\n**Examples:**\n\n```\nCreate an Action that fetches user data\n```\n\n```\nHow do I use Zai to extract structured data?\n```\n\n```\nShow me how to call my bot's actions from a Next.js frontend\n```\n\n```\nSet up authentication for my React app with Botpress\n```\n\n```\nMy bot isn't responding — how do I debug this?\n```\n\n```\nWrite an eval that tests my createTicket tool\n```\n\n## Skill Structure\n\nEach skill contains:\n\n- `SKILL.md` - Instructions for the agent\n- `references/` - Supporting documentation files\n\n```\nskills/ # Heavy knowledge (skills)\n├── adk/ # Core ADK framework (23 reference docs)\n│ ├── SKILL.md\n│ └── references/\n├── adk-frontend/ # Frontend integration (11 reference docs)\n│ ├── SKILL.md\n│ └── references/\n├── adk-evals/ # Testing & evals (3 reference docs)\n│ ├── SKILL.md\n│ └── references/\n├── adk-debugger/ # Debugging & observability (4 reference docs)\n│ ├── SKILL.md\n│ └── references/\n└── adk-docs/ # Documentation management (1 reference doc)\n ├── SKILL.md\n └── references/\n\ncommands/ # Thin slash commands (load skills)\n├── adk-init.md # /adk-init - scaffolding\n├── adk-debug.md # /adk-debug - loads adk-debugger skill\n├── adk-eval.md # /adk-eval - loads adk-evals skill\n├── adk-frontend.md # /adk-frontend - loads adk-frontend skill\n├── adk-integration.md # /adk-integration - loads adk skill for integration management\n├── adk-doc-create.md # /adk-doc-create - loads adk-docs skill\n├── adk-doc-review.md # /adk-doc-review - loads adk-docs skill\n├── adk-doc-update.md # /adk-doc-update - loads adk-docs skill\n├── adk-doc-sync.md # /adk-doc-sync - loads adk-docs skill\n└── adk-doc-search.md # /adk-doc-search - loads adk-docs skill\n```\n\n## License\n\nMIT\n", "bytes": 9084, "sha": "1893c6011c063eebcae5010af537682d3173de16f3702cf0e2c7968ce928bc57", "repo_slug": "botpress/skills", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/skl_botpress_skills_adk_docs_16a6cc42/readme" }