Agent skill

Framework Usage

by ncatbot in ncatbot/NcatBot

使用 NcatBot 框架开发 QQ 机器人或跨平台 Bot。当用户需要快速体验、创建插件、注册事件处理、发送消息、调用 Bot API、使用 Mixin/Hook、使用 CLI 工具、编写插件测试、或调试运行问题时触发此技能。Use when: 开发…

MITAuto-check passedBackend & APIs

Install Framework Usage

skills CLI
$ npx skills add ncatbot/NcatBot --skill framework-usage -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ncatbot/NcatBot framework-usage --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ncatbot/NcatBot.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/framework-usage .claude/skills/framework-usage && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
framework-usage
GitHub stars
116
Token cost
~1.2k tokens
SKILL.md length
292 words
Files
11 (incl. references)
Skills in repo
12
Repo updated
First seen
Licence
MIT

At a glance

使用 NcatBot 框架开发 QQ 机器人或跨平台 Bot。当用户需要快速体验、创建插件、注册事件处理、发送消息、调用 Bot API、使用 Mixin/Hook、使用 CLI 工具、编写插件测试、或调试运行问题时触发此技能。Use when: 开发…

  • Works in 6 steps: :需求理解 → :功能预览与确认 → :深入实现 → …
  • : 开发 bot、写插件、发消息、消息段、群管理、事件处理、响应命令、Mixin、Hook、定时任务、权限、RBAC、CLI、调试、插件测试、多平台、跨平台、platform
  • SKILL.md covers 协作技能, 工作流, 功能参考索引 and 查资料的方法
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Framework Usage is an agent skill from ncatbot/NcatBot. 使用 NcatBot 框架开发 QQ 机器人或跨平台 Bot。当用户需要快速体验、创建插件、注册事件处理、发送消息、调用 Bot API、使用 Mixin/Hook、使用 CLI 工具、编写插件测试、或调试运行问题时触发此技能。Use when: 开发 bot、写插件、发消息、消息段、群管理、事件处理、响应命令、Mixin、Hook、定时任务、权限、RBAC、CLI、调试、插件测试、多平台、跨平台、platform。

Its SKILL.md is about 1.2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 11 other files, including reference files (for example `references/bot-api.md`, `references/events.md` and `references/getting-started.md`).

It sits in Backend & APIs, covering Authorization and RBAC. The repository describes itself as: NapCat Python SDK;快速开发你的 QQ 机器人. The licence is MIT.

When your agent uses it

  • : 开发 bot、写插件、发消息、消息段、群管理、事件处理、响应命令、Mixin、Hook、定时任务、权限、RBAC、CLI、调试、插件测试、多平台、跨平台、platform
  • Tasks that involve Authorization and RBAC

Example prompts

  • “/framework-usage”

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. :需求理解
  2. :功能预览与确认
  3. :深入实现
  4. :验证
  5. 粗读 → references/
  6. 深入 → 读项目文档 docs/

What it can do on your machine

Read from SKILL.md and the folder at commit c26300a. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Framework Usage loads about 1.2k tokens when it runs, and up to ~26k if it reads all its reference files. Until then it costs about 57 tokens; SKILL.md has 292 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~57
When it runs · the whole SKILL.md, loaded when a task matches
~1.2k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~26k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from ncatbot/NcatBot at commit c26300a, republished under its MIT licence (© ncatbot). 292 words, ~1,245 tokens.

Download SKILL.mdSave it as .claude/skills/framework-usage/SKILL.md (or your agent's skills folder). This skill also uses 10 other files; get the full folder from GitHub.
name
framework-usage
description
使用 NcatBot 框架开发 QQ 机器人或跨平台 Bot。当用户需要快速体验、创建插件、注册事件处理、发送消息、调用 Bot API、使用 Mixin/Hook、使用 CLI 工具、编写插件测试、或调试运行问题时触发此技能。Use when: 开发 bot、写插件、发消息、消息段、群管理、事件处理、响应命令、Mixin、Hook、定时任务、权限、RBAC、CLI、调试、插件测试、多平台、跨平台、platform。
license
MIT

技能指令

你是 NcatBot 开发助手。帮助用户使用 NcatBot 框架开发 QQ 机器人或跨平台 Bot。

协作技能

需要做什么委托给
编写/运行/调试测试testing-framework
定位框架内部代码、理解模块实现codebase-nav
修框架 bug、改框架代码framework-dev
用框架开发 botframework-usage(本技能)

工作流

text
Phase 1: 需求理解 → Phase 2: 功能预览与确认 → Phase 3: 深入实现 → Phase 4: 验证
Phase 1:需求理解

接收用户自然语言需求后:

  1. 粗读 references/ — 快速匹配需求涉及的框架功能模块(见下方 §功能参考索引)。

  2. 框架选型由你决定 — 插件/非插件模式、Mixin 选择、Hook vs 装饰器、多平台 vs 单平台等框架内部决策,根据下表自行判断,不问用户。

    场景推荐模式理由
    快速验证想法、体验框架非插件模式零配置,全写在 main.py
    简单 Bot、几个命令非插件模式最小代码量
    需要持久化配置/数据插件模式ConfigMixin / DataMixin
    需要定时任务、权限控制插件模式TimeTaskMixin / RBACMixin
    多功能、可维护的正式项目插件模式热重载 + Mixin + 结构化
  3. 仅外部依赖问用户 — 当需求涉及第三方 API/服务(天气、翻译、AI、数据源等)时,用 vscode_askQuestions 确认具体用哪个。精简,不刷屏。

    规则:每个选项必须包含一个 "我不知道,你帮我选一个" 选项(标记 recommended: true)。

    示例与模板见 preview-workflow.md §askQuestion 模板。

Phase 2:功能预览与确认

将用户需求拆分为独立功能点,为每个功能编写端到端对话流预览。

预览格式(每个功能点):

markdown
### 功能 N:<功能名>
<一句话描述>

**触发方式**:<用户输入的命令 / 外部事件>

**对话流**:
用户: <输入>
Bot:  <输出>
用户: <输入>
Bot:  <输出>
...

完整格式规范和 4-5 个端到端预览样板见 preview-workflow.md。

预览交付方式:

  • 有文件编辑权限 → 在项目根目录创建 PREVIEW.md,写入全部功能预览。
  • 无文件编辑权限 → 在对话中直接输出预览文本。

逐功能确认:

用 vscode_askQuestions 逐功能确认(选项见 preview-workflow.md §功能确认模板):

  • ✅ 满意
  • ✏️ 需要调整(附 freeText 收集意见)
  • ❌ 不要这个功能

若选"需要调整" → 修改预览后重新确认。循环直到全部功能通过。

Phase 3:深入实现

全部功能预览确认后:

  1. 仔细阅读对应 reference/docs(见下方 §查资料的方法)。
  2. 读取用户项目已有代码,理解项目架构和约定。
  3. 生成完整可运行代码,包括插件文件、manifest.toml、配置等。

搭建项目、启动方式、CLI 命令详见 getting-started.md(含工作区检测、config 模板、NapCat 自动安装说明)。

Phase 4:验证
  • 测试:委托 testing-framework 技能(PluginTestHarness、事件工厂、Scenario)。
  • 调试:查阅 troubleshooting.md(日志、配置检查、常见问题)。
  • 框架行为不符预期:使用 codebase-nav 技能定位问题。

功能参考索引

根据用户需求查阅对应 reference:

用户需求框架功能参考
安装/搭建项目/CLI/配置项目初始化getting-started.md
响应命令/消息/事件装饰器 + handlerevents.md
简单命令处理CommandHook(单层命令)hooks.md
分层命令结构(子命令/命令组)CommandGroupHookhooks.md
过滤/拦截/中间件Hook 系统hooks.md
发送文字/图片/视频/转发消息构造与发送messaging.md
群管理/查询信息/文件/平台 APIBot APIbot-api.md
HTTP 下载/请求/代理检查MiscAPI (api.misc)bot-api.md
持久化配置/数据ConfigMixin / DataMixinmixins.md
定时任务/权限控制/事件流TimeTaskMixin / RBACMixin / EventMixinmixins.md
多步对话/等待回复wait_event / EventStreamevents.md
非阻塞启动/事件编排run_async + wait_event + events()events.md
多平台/跨平台/TraitBotAPIClient 多平台门面, Trait 协议multi-platform.md
平台登录/适配器配置各适配器登录流程multi-platform.md
插件结构/生命周期manifest + 基类plugin-structure.md
内置 ! 管理命令(热重载/sysinfo/开关)_system_manager + plugin.* 配置docs/docs/notes/guide/3. 插件开发/12. 内置管理命令.md
调试/排错/日志诊断与排查troubleshooting.md
功能预览格式与样板端到端预览流程preview-workflow.md

查资料的方法

Phase 1 粗读 → references/

references/ 是常用 API 和模式的速查,覆盖搭建、事件、Hook、消息、API、Mixin、多平台、插件结构、排错、功能预览。在 Phase 1 阶段快速匹配功能模块即可。

Phase 3 深入 → 读项目文档 docs/

全部功能预览确认后,在 Phase 3 仔细阅读对应文档:

  1. docs/docs/notes/guide/README.md — 全局入口,含 Quick Start 和指南索引
  2. 按需深入:
关键词直接查阅
快速开始/安装docs/docs/notes/guide/1. 快速开始/
适配器/平台登录docs/docs/notes/guide/2. 适配器/
插件/事件/Hook/生命周期docs/docs/notes/guide/3. 插件开发/
消息段/转发docs/docs/notes/guide/4. 消息发送/
Bot API/群管理docs/docs/notes/guide/5. API 使用/
配置docs/docs/notes/guide/6. 配置管理/
RBAC/权限docs/docs/notes/guide/7. RBAC 权限/
CLIdocs/docs/notes/guide/8. 命令行工具/
测试docs/docs/notes/guide/9. 测试指南/
多平台docs/docs/notes/guide/10. 多平台开发/
架构/概念docs/docs/notes/guide/11. 架构与概念/
  1. docs/docs/notes/reference/ — API 签名完整参考(10 个模块)
  2. docs/docs/README.md — 文档全局目录树
框架内部问题 → codebase-nav

当需要理解框架内部实现(而非使用层面),使用 codebase-nav 技能。

© ncatbot, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 10 other files (references) in .agents/skills/framework-usage of ncatbot/NcatBot.

  • SKILL.md
  • references/bot-api.md
  • references/events.md
  • references/getting-started.md
  • references/hooks.md
  • references/messaging.md
  • references/mixins.md
  • references/multi-platform.md
  • references/plugin-structure.md
  • references/preview-workflow.md
  • references/troubleshooting.md

Open the folder on GitHubat commit c26300a

Compare with similar skills

Framework Usage next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Framework Usage compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Framework Usage this skillncatbot/NcatBot116—~1.2kAutomated safety check: PassMIT
Configuring Horizoncoollabsio/coolify63k4 repos~898Automated safety check: PassMIT
K8s Security PoliciesCybereason-Public/owLSM28012 repos~2kAutomated safety check: PassGPL-2.0
Payloadpayloadcms/payload45k5 repos~6.2kAutomated safety check: PassMIT
Convex Setup Authspokvulcan/poker-planning1148 repos~1.8kAutomated safety check: PassMIT
Abp Authorizationabpframework/abp14k—~1.3kAutomated safety check: PassLGPL-3.0

Similar skills

  • Configuring Horizon

    coollabsio/coolify

    A skill your agent uses whenever the user mentions Horizon by name in a Laravel context.

    63k GitHub starsUsed in 4 repos~898 tokens
    Backend & APIsAuto-check passed
  • K8s Security Policies

    Cybereason-Public/owLSM

    Comprehensive guide for implementing NetworkPolicy, PodSecurityPolicy, RBAC, and Pod Security Standards in Kubernetes.

    280 GitHub starsUsed in 12 repos~2k tokens
    Backend & APIsAuto-check passed
  • Payload

    payloadcms/payload

    A skill your agent uses when working with Payload projects (payload.config.ts, collections, fields, hooks, access control, Payload API).

    45k GitHub starsUsed in 5 repos~6.2k tokens
    Backend & APIsAuto-check passed
  • Convex Setup Auth

    spokvulcan/poker-planning

    Sets up Convex auth, identity mapping, and access control. An agent skill from spokvulcan/poker-planning.

    114 GitHub starsUsed in 8 repos~1.8k tokens
    Backend & APIsAuto-check passed
  • Abp Authorization

    abpframework/abp

    ABP permission system - PermissionDefinitionProvider, [Authorize] attribute, CheckPolicyAsync, IsGrantedAsync, ICurrentUser, IPermissionManager, multi-tenancy side.

    14k GitHub stars~1.3k tokensUpdated today
    Backend & APIsAuto-check passed
  • UI Audit

    bagofwords1/bagofwords

    Exhaustively audit the UI control by control and role by role — enumerate every button, link, and input on a set of pages, write down what each is supposed to do (derived from the handler code and…

    458 GitHub stars~2.9k tokensUpdated today
    Backend & APIsAuto-check passed

More from ncatbot/NcatBot

All 12 skills in this repo
  • Code Nav

    ncatbot/NcatBot

    定位 NcatBot 代码实现:锁定模块目录、找到关键类/函数、追踪调用链。当文档不够时才读代码,用搜索而非遍历。Use when: 找代码实现、哪个文件、哪个类、追踪调用链、定位 bug 行号、代码在哪、模块目录、源码定位。

    116 GitHub stars~460 tokensUpdated 3 days ago
    Auto-check passed
  • Docs Maintenance

    ncatbot/NcatBot

    维护 NcatBot 项目文档、示例、Skills 知识资产。编写/编辑文档、修复文档问题、文档结构规范审查。Use when: 写文档、改文档、新增文档、修复断链、修复索引、修复代码块标注、文档规范、文档模板、文档结构设计、docs maintenance。

    116 GitHub stars~722 tokensUpdated 3 days ago
    Auto-check passed
  • Docs Sync

    ncatbot/NcatBot

    整体/局部防腐检查:Docs 内部链接断裂、README 索引不同步、guide↔reference 内容不一致、examples 导入过时、Code↔Docs API 对齐。逐文件检查,最大化并发 subagent。Use when: docs 防腐、docs 链接、docs 断链、断链检查、docs 审计、docs audit、code docs 对齐、reference 过时、guide…

    116 GitHub stars~1.3k tokensUpdated 3 days ago
    Auto-check passed
  • Plugin Migration

    ncatbot/NcatBot

    将 NcatBot 4.4/4.5 版本插件迁移到 5.0。包括导入路径、注册方式、Config/Data API、事件类型、消息构造的全面映射。Use when: 迁移插件、升级插件、4 转 5、老版本、旧版本、migration、upgrade、plugin migration、版本升级。

    116 GitHub stars~1.2k tokensUpdated 3 days ago
    Auto-check passed
  • Release

    ncatbot/NcatBot

    发布 NcatBot 新版本到 PyPI 和 GitHub Release,或仅编排 Commit 推送到 main。从工作区变更编排 commit 到最终发布的全链路流程。Use when: 发版、release、发布、changelog、版本号、pick commits、挑选提交、release notes、编排 commit、push、推送。

    116 GitHub stars~513 tokensUpdated 3 days ago
    Auto-check passed
  • Skills Sync

    ncatbot/NcatBot

    检查、报告、修复 Skills 间链接内容不同步,以及 Skills↔Docs 内容链接不同步。逐文件检查,最大化并发 subagent。Use when: skill 同步、skill 断链、skill 引用、skill 过时、skill audit、skills 一致性、skill 检查、skill↔docs。

    116 GitHub stars~694 tokensUpdated 3 days ago
    Auto-check passed

Categories

Questions about Framework Usage

What does Framework Usage do?

使用 NcatBot 框架开发 QQ 机器人或跨平台 Bot。当用户需要快速体验、创建插件、注册事件处理、发送消息、调用 Bot API、使用 Mixin/Hook、使用 CLI 工具、编写插件测试、或调试运行问题时触发此技能。Use when: 开发…. Framework Usage is an agent skill from ncatbot/NcatBot.

When should I use Framework Usage?

Framework Usage fits situations like: : 开发 bot、写插件、发消息、消息段、群管理、事件处理、响应命令、Mixin、Hook、定时任务、权限、RBAC、CLI、调试、插件测试、多平台、跨平台、platform; tasks that involve Authorization and RBAC.

How do I install Framework Usage in Claude Code?

Run `npx skills add ncatbot/NcatBot --skill framework-usage -a claude-code`. Or copy the skill folder (.agents/skills/framework-usage in ncatbot/NcatBot) into .claude/skills/framework-usage in your project. Claude Code loads it when a task matches its description.

How do I install Framework Usage in Codex?

Run `npx skills add ncatbot/NcatBot --skill framework-usage -a codex`. Or copy the skill folder (.agents/skills/framework-usage in ncatbot/NcatBot) into .agents/skills/framework-usage in your project. Codex loads it when a task matches its description.

Can I use Framework Usage in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ncatbot/NcatBot --skill framework-usage -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/framework-usage, .gemini/skills/framework-usage, .github/skills/framework-usage and .opencode/skills/framework-usage in your project.

What does Framework Usage need to run?

SKILL.md names no scripts, command-line tools or credentials: Framework Usage is instructions for the agent only.

Does Framework Usage access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Framework Usage safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Framework Usage use?

Framework Usage is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Framework Usage use?

About 1.2k tokens (SKILL.md is roughly 5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 25k tokens, read only when the agent opens those files.

What are the alternatives to Framework Usage?

Skills that share tags, products or a category with Framework Usage: Configuring Horizon (coollabsio/coolify, 63k stars), K8s Security Policies (Cybereason-Public/owLSM, 280 stars), Payload (payloadcms/payload, 45k stars) and Convex Setup Auth (spokvulcan/poker-planning, 114 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Framework Usage?

ncatbot (a GitHub organization) maintains it in ncatbot/NcatBot, which has 116 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on October 4, 2026.

Source: ncatbot/NcatBot on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.