Introduction¶

When building bots on the QQ Open Platform, the Intents, event names, and reply APIs for the three types of entry points—Channel @, C2C private chat, and Group @—are not consistent. Channel messages also carry a <@!botid> prefix that requires separate parsing. Relying solely on scattered documentation to piece together code can easily lead to missed Intent configurations or startup issues like “no current event loop” on Python 3.10+. The following introduces the QQBot Development Guide (@user_e7c8a23d/qqbot-messaging) on SkillHub: it organizes the three scenarios of qq-botpy, scheduled push notifications, and a runnable template into a SKILL.md that Agents can follow, facilitating the direct generation or modification of bot projects within conversations.

What is this?¶

The QQBot Development Guide is a community-sourced (community) programming Skill, located at @user_e7c8a23d/qqbot-messaging. Currently at version 1.0.0, it is maintained by the publisher user_e7c8a23d. It is categorized under dev-programming on SkillHub, with tags indicating requires_api_key=true (requires configuration of QQ Bot appid / secret).

It is positioned as a QQ Bot messaging framework description: built on Tencent’s qq-botpy SDK, it covers the reception and transmission patterns for Channel @, C2C private chat, and Group @. It also provides a scheduled push loop, startup snippets, and a complete example in scripts/bot_template.py.

Core Features¶

The following capabilities are derived from the Skill’s bundled SKILL.md and scripts. After installation, the Agent will assist in development according to the conventions within.

Three Message Scenarios¶

Key points:

1. C2C and Group messages share public_messages=True, allowing simultaneous listening on the same Bot.
2. Channel replies commonly use await message.reply(content="..."); C2C / Group require corresponding post_c2c_message / post_group_message calls with parameters like msg_id (see the table in the Skill for details).
3. Channel command parsing requires removing the @ prefix; the Skill provides parse_cmd() in scripts/bot_utils.py, and the template contains a same-named implementation.

Scheduled Push¶

Use asyncio.create_task() to attach a background coroutine, using await asyncio.sleep(seconds) inside the loop. To cancel the task, call task.cancel(), and catch asyncio.CancelledError within the loop to exit. bot_template.py maintains subscription dictionaries and PUSH_INTERVAL (default 3600 seconds) for the three scenarios, serving as a starting point for “Start Subscription / Cancel Subscription” business logic.

Startup and Runtime Environment¶

The Skill explicitly requires Python 3.10+ and explicitly creating an event loop before client.run():

loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)

intents = botpy.Intents(public_guild_messages=True, public_messages=True)
client = MyBot(intents=intents)
client.run(appid=config["appid"], secret=config["secret"])

Business dependency installation:

pip install qq-botpy

Project-side config.yaml configuration:

appid: "YOUR_APPID"
secret: "YOUR_SECRET"

Bundled Scripts¶

• scripts/bot_template.py: A runnable template with three types of handlers + scheduled push; copy it to your project and implement handle_command() / get_push_content() to extend business logic.
• scripts/bot_utils.py: parse_cmd() and a generic SubscriptionManager.

The Skill’s FAQ also compiles common causes for issues such as not receiving messages (Intents) and message sending failures (passive msg_id expiration, active message permissions), facilitating Agent-assisted troubleshooting.

Installation and Activation¶

The Skill follows the general SKILL.md format. The method provided on the SkillHub page is to let the AI install coordinates @user_e7c8a23d/qqbot-messaging according to the SkillHub Installation Instructions.

If the skillhub CLI is installed on your local machine, you can install the Skill to the current Agent’s skills directory (must use --dir, otherwise the default ./skills/ might not be recognized):

command -v skillhub && skillhub --version

If the CLI is not installed, follow the official documentation for a full installation (excerpt):

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

Example of installing this Skill (replace <skills directory> with your client’s path):

skillhub install @user_e7c8a23d/qqbot-messaging --dir <skills directory>

Common client skills directories (from SkillHub installation docs):

• Cursor: ~/.cursor/skills/
• Claude Code: ~/.claude/skills/
• Codex: ~/.codex/skills/ or .agents/skills/ under the project

Restart or refresh the Agent after installation to load the new Skill. When describing requirements like “developing a QQ bot”, “handling channel/group/private chat messages”, or “scheduled push” in conversations, the Agent should prioritize referencing the scenario tables and templates within this Skill.

Typical Usage¶

After the installation above, you can implement a minimal runnable Bot based on the Skill documentation.

1. Prepare Configuration and Dependencies

Create a config.yaml in the project directory and fill in the appid and secret applied for from the Open Platform. Run pip install qq-botpy.

2. Start with the Template

Copy the Skill’s scripts/bot_template.py to the project (or let the Agent generate code based on that file structure), retain the three on_* handlers and subscription logic, and implement command branches in handle_command(), such as the semantics included in the Skill’s example:

def handle_command(cmd: str) -> str | None:
    if "查询" in cmd or "行情" in cmd:
        return "这里返回你的业务数据"
    return None

3. Startup

At the end of the file, set up the loop and Intents as required by the Skill, then run python bot_template.py.

In the channel scenario, incoming content needs to be processed by parse_cmd() before being passed to handle_command(); for C2C / Group, the original text can be used directly. For scheduled pushes, follow the asyncio.create_task and get_push_content() in the template, and note the Skill FAQ: the msg_id required for passive replies has a short validity period, so long-cycle pushes may require active message permissions or timely updating of msg_id.

Use Cases and Notes¶

Who is it for

• Developers who have created bots on the QQ Open Platform and need to handle Channel, Private Chat, and Group @ uniformly using qq-botpy.
• Teams hoping for Agents like Cursor / Claude Code to generate Bot skeletons, modify Intents, or supplement scheduled push logic according to fixed patterns.

Limitations and Notes

• Valid appid / secret must be configured (requires_api_key=true); do not commit keys to the repository.
• The Skill focuses on messaging and push patterns, excluding operational processes like Open Platform audits or sandbox activation; permissions and capabilities are subject to current QQ Open Platform rules.
• For Python 3.10+, ensure the event loop is created as written in the Skill; missing Intent configuration for any of the three scenarios will result in “not receiving messages”.
• SkillHub Statistics (as of page info): Rating 100000, Downloads ~1101, Installs 15; as a community Skill, verify the version number on SkillHub before upgrading.

Conclusion¶

The QQBot Development Guide consolidates the three messaging scenarios, configuration fields, startup snippets, and runnable templates of qq-botpy into a single SKILL.md, making it suitable as a reference for Agent-side QQ bot development. To install or view instructions, visit the SkillHub page:

• https://www.skillhub.cn/skills/user_e7c8a23d/qqbot-messaging
• https://api.skillhub.cn/user_e7c8a23d/qqbot-messaging