| name | skill-astrbot-dev |
| description | AstrBot plugin development reference and workflow guide.
Use this skill when you are:
- Writing AstrBot plugins, hooks, decorators, or message handlers
- Implementing platform adapters, message chains, or event flows
- Configuring plugin schemas, sessions, or lifecycle management
- Working with Agent system (tools, subagents, personas, sandboxes, cron jobs)
- Converting between AstrBot message models and platform-specific formats
- Looking up AstrBot API signatures, hook inventories, or code entrypoints
- Debugging plugin issues related to message routing, event handling, or provider integration
Provides reference docs for: messages, platform adapters, plugin config, agent system, and core concepts.
|
| metadata | {"short-description":"AstrBot plugin development reference","version":"4.x","compatibility":"astrbot >=4.16","license":"MIT"} |
skill-astrbot-dev
This skill provides the authoritative reference for AstrBot plugin and core development.
It covers message models, platform adapter interfaces, plugin configuration schemas, hooks/lifecycle, and the Agent system (tools, subagents, personas, sandboxes, cron).
When to use
Use this skill when you ask for help with:
- AstrBot plugin structure, decorators/hooks, lifecycle, schema, sessions
- Message model/event flow and message-chain conversion
- Platform adapter interface and message conversion patterns
- Agent topics (tools/providers/personas/subagents/sandbox/cron/context compression)
- Context management (conversation branches, history operations, context injection, compression strategies)
Mandatory workflow (use this every time)
- Start from a single entrypoint (avoid broad loading):
- Site index:
skill-astrbot-dev/index.md
- Core concepts:
skill-astrbot-dev/design_standards/core_concepts.md
- Pick one topic folder and stay focused:
- Agent system:
skill-astrbot-dev/agent/
- Plugin config:
skill-astrbot-dev/plugin_config/
- Messages:
skill-astrbot-dev/messages/
- Platform adapters:
skill-astrbot-dev/platform_adapters/
- For Agent Runner (v4.7.0+):
skill-astrbot-dev/agent/agent-runner.md
- If the user targets a specific AstrBot version, cross-check:
skill-astrbot-dev/snapshots/<version>/
- If docs and code disagree, treat code as truth:
- Core code lives under
astrbotcore/astrbot/core/ (read only the needed files)
STRONGLY ADVISED: use AstrBot SDK while writing plugins
When writing plugin code, strongly advised to install AstrBot SDK locally and use it for API reference,
signature lookup, and IDE auto-completion.
python -m pip install -U astrbot
Use SDK symbols first when implementing hooks, provider/context calls, and agent runner integration.
This helps reduce guesswork and signature mismatch.
If AstrBot source code in this repo is available, still treat repo code as higher priority than package docs.
Plugin project structure (strongly advised)
A standard AstrBot plugin project should include:
main.py: entrypoint. Implement plugin startup and primary features here.metadata.yaml: plugin metadata (name, version, author, repo, description).README.md: installation, usage, feature overview, and dev links..gitignore: ignore Python cache (__pycache__) and IDE config files.LICENSE: open-source license file.
metadata.yaml minimal template
name: astrbot_plugin_helloworld
display_name: helloworld
desc: AstrBot 插件示例。
version: v1.3.0
author: Soulter
repo: https://github.com/Soulter/helloworld
astrbot_version: ">=4.16,<5"
Code rules for plugin implementation
- Use
async def for handlers/hooks/tool functions.
- Keep
main.py focused on plugin entry and orchestration; extract complex logic into submodules.
- Add type hints for public methods and hook signatures.
- Do not hardcode provider IDs or secrets; expose configurable fields in
_conf_schema.json.
- Prefer small, testable functions over large monolithic handler bodies.
- Keep README and metadata consistent with actual plugin behavior and version.
-If you are writing AstrBot core code instead of plugins, you must submit a PR to https://github.com/AstrBotDevs/AstrBot-docs if the changes require doc updates (for instance: new hooks, new APIs, new features, platform adapter changes, and so on). If you don't see the docs repo, please remind the user to clone the docs-repo and add it to the workspace.
Ensure that a
requirements.txt file is created in the plugin directory and populated with the necessary dependencies.
It's best to keep the plugin size under 32MB.
For large resources like high-resolution images, it is best to use a CDN instead of hardcoring.
It's better to use new hooks instead of old ones.
Hooks: avoid missing / outdated references
There are two different "hook" layers you must not mix up:
- Plugin event hooks (decorators):
skill-astrbot-dev/plugin_config/hooks.md
- Agent runner hooks (
BaseAgentRunHooks): skill-astrbot-dev/agent/agent-related-hooks.md
If you need a complete hook inventory (because context may be truncated), generate it locally:
python scripts/generate_hook_inventory.py
This writes to skill-astrbot-dev/.tmp/hook_inventory/ (gitignored). Use it as a scratchpad for writing/updating docs;
do not reference .tmp paths as public documentation URLs.
High-signal code entrypoints (open only when needed)
- Event hooks registration + signatures:
astrbotcore/astrbot/core/star/register/star_handler.py
- Event types:
astrbotcore/astrbot/core/star/star_handler.py
- Agent runners + hook call order:
astrbotcore/astrbot/core/agent/runners/
- Agent hook interface:
astrbotcore/astrbot/core/agent/hooks.py
- Main agent build (sandbox/cron/tools):
astrbotcore/astrbot/core/astr_main_agent.py
- Skills system (AstrBot runtime skills):
astrbotcore/astrbot/core/skills/skill_manager.py
- Subagents config loading:
astrbotcore/astrbot/core/subagent_orchestrator.py
v4.5.7+ New Tool Definition Pattern
推荐使用 dataclass 模式定义 Tool（见 skill-astrbot-dev/design_standards/core_concepts.md 第7节）：
from pydantic.dataclasses import dataclass
from astrbot.api import FunctionTool
@dataclass
class MyTool(FunctionTool):
name: str = "my_tool"
description: str = "工具描述"
parameters: dict = {...}
async def call(self, context, **kwargs) -> str:
return "结果"
注册：self.context.add_llm_tools(MyTool())
装饰器方式仍然支持，但推荐新项目使用 dataclass 模式。
