一个包里可以装三类东西，面向三种消费者：

Agent 工具

模型可调用的函数。设计上有两条硬规则。

规则一：工具数量尽可能少。 每个注册的工具都会注入模型的每一轮上下文，工具越多越费 token，模型选错的概率也越高。

规则二：相关操作合并为一个带 action 参数的工具。

ctx.tools.register({
  name: 'pjblog_post',
  title: 'PJBlog Post',
  description: `Manage blog posts.
action:
  list    — list all posts
  create  — create a new draft
  update  — update an existing post
  publish — publish a draft`,
  inputSchema: {
    type: 'object',
    properties: {
      action: { type: 'string', enum: ['list', 'create', 'update', 'publish'] },
      slug: { type: 'string' },
      title: { type: 'string' },
    },
    required: ['action'],
  },
  risk: 'medium',
  async execute(input, exec) { /* switch (input.action) */ },
});

description 里必须逐条列出所有 action，这是模型唯一的行为说明书。

工具命名固定小写 snake_case，格式 <mini_tool_name>_<function_name>，禁止 init、status 这类通用短名。

工具确实超过 10 个时，改用本地 MCP server 按需加载，见《MCP 集成》。

长任务进度：exec.progress.report({ message }) 显示不确定进度条，加上 percent 显示确定进度。进度不是结果，工具最终仍要返回一个 ToolResult。

交互与服务能力

不面向模型、由用户或系统触发的部分：Composer 按钮、对话框、表单、Session 容器、OAuth 登录、MCP 桥接、后台轮询。这构成小工具的“服务面”，详见《标准化 UI》《账号、配置与 OAuth 登录》《Session 容器》《Session Loop》。

内置 Skills

包内可携带 Skills，随启用生效、随停用消失：

my-mini-tool/
└── skills/
    └── my-workflow/
        └── SKILL.md

manifest 声明 contributes.skills: true 即可。它们不会被复制到全局 skills 目录。

小工具的组成

Agent 工具

交互与服务能力

内置 Skills