OpenSquilla MetaSkill 用户指南

MetaSkill 让 OpenSquilla 从每个 turn 都从零开始琢磨复杂工作，转变为可复用、可显式启动、可审计、可改进的任务协议。

普通对话只解决一次请求。MetaSkill 则保存了完成高价值工作的一种方式。

重要声明

OpenSquilla 中的一些 MetaSkills，以及它们调用的某些 skill，是基于预期功能、可用能力和使用场景，借助 AI 辅助创作、修订或组合的。

这意味着：

MetaSkills 并非仅仅是一组完全手写的脚本。它们是一个系统的一部分，AI 可以在其中协助形式化并演进可复用的任务协议。
由 AI 创作或 AI 辅助生成的 MetaSkills 在被视为可用之前，应当通过结构校验、触发面检查、运行时测试、人工审阅和安全边界评估。
MetaSkill 的输出是决策辅助材料和工作产物草稿。在法律、医疗、金融、招聘、学术、安全或其他高风险场景中，它们不是最终的专业建议。
发布、申请、安装、付款、签署、发送消息或修改生产系统等操作，需要用户明确授权，并仍由用户承担责任。
当 MetaSkill 依赖搜索、文档解析、LLM 判断或第三方工具时，结果可能受到来源质量、模型局限、工具可用性、上下文完整性和时效性变化的影响。
用户应当审阅事实、引用、假设、风险以及无法验证的论断，尤其是在高风险情境下。

简而言之：MetaSkill 将高价值工作转化为可复用、可审计、可改进的 AI 协作协议。它并不免除审阅、判断或责任的需要。

它是什么

OpenSquilla 是一个开源 AI agent 运行时。MetaSkill 是它的任务协议层。

MetaSkill 不会引入新的执行原子。它定义了一种组织现有原子（如 skills、工具、LLM 调用和 sub-agents）的方式，使其成为一个可复用的任务协议。

可以类比 Makefile 和 shell 命令。Makefile 并不替代命令；它定义了如何组合命令。MetaSkill 不替代 skills 或工具；它告诉 OpenSquilla 一类高价值工作应当如何被理解、组织、检查和交付。

MetaSkill 提供四项主要优势：

在带有 kind: meta 和 composition.steps 的 SKILL.md 文件中固化的协议化能力；
通过 /meta 显式启动，仅当 meta_skill.auto_trigger = true 时才可选地自动触发；
可审计、可回放的步骤输入、输出、状态与结果；
随着重复的协作模式转化为提议，能力可随时间改进。

默认启动模型

MetaSkills 默认仅支持手动运行。使用 /meta 列出可用的 workflows，使用 /meta <name> 运行其中一个。这让 workflow 的启动保持审慎、可审阅且更易于解释。

Web 聊天和 CLI gateway TUI 同时支持列出和运行：

/meta
/meta meta-kid-project-planner

Channel 与独立 CLI 形态仅支持 /meta 列出。

要恢复较旧的自动行为，请设置：

[meta_skill]
auto_trigger = true

当 auto_trigger = true 时，OpenSquilla 可能在普通的自然语言 turns 中考虑 MetaSkills。如果你希望 workflows 仅在显式的 /meta <name> 命令之后运行，请保持其关闭。

用户心智模型

使用 MetaSkill 不仅仅是问一个问题。它是委派 OpenSquilla 产出一份可审阅的结果。

一份强有力的 MetaSkill 请求包含四件事：

结果：你想得到什么。
上下文：相关的材料、实体、时间范围与约束。
标准：本任务的”好”意味着什么。
边界：什么事不能做、什么内容不能编造、什么需要确认。

示例：

/meta meta-kid-project-planner

I need a safe weekend project plan, not a generic list of ideas.
Use only materials that are easy to buy locally.
Separate adult-only steps from child-safe steps.
Do not include flames, blades, solvents, or risky chemicals.

用户定义目标与标准；OpenSquilla 组织执行。

当前内置的 MetaSkills

保留下来的内置 MetaSkills 覆盖了一组聚焦的高价值任务类。

MetaSkill	定位
`meta-kid-project-planner`	为学校项目、show-and-tell 或科学活动生成安全且适龄的方案。
`meta-paper-write`	支持学术草稿、稿件结构、引用规划、实验占位以及 LaTeX/PDF 路径。
`meta-short-drama`	生成短剧脚本、视觉 prompts、视频拼装计划、字幕以及渲染好的本地视频 artifacts。
`meta-skill-creator`	将反复出现的多 skill 协作模式转化为新的 MetaSkill 提议。

这些设计上注重质量而非数量。不成熟、重复或单一 skill 的薄封装 MetaSkill 不应保留在内置目录中。

运行 MetaSkills 之前的要求

Skill 页面是当前就绪状态的唯一来源。在运行需要导出文件、编译 PDF 或渲染视频的工作流之前，打开 skill 详情对话框并查看 Requirements 部分。

常见的配置面：

论文/PDF 工作流（如 meta-paper-write）要求 PATH 上有 xelatex 和 bibtex。在请求编译 PDF 之前，安装一个 TeX 发行版，如 TeX Live、MiKTeX 或 BasicTeX。
视频工作流（如 meta-short-drama）要求 PATH 上有 ffmpeg 和 ffprobe，用于片段动画、合并以及字幕烧录。
办公文档工作流会汇总子 skill（如 docx、xlsx、pdf-toolkit 与 pptx）的依赖；这些通常会在 Skill 页面中显示 Python 包依赖。
搜索、天气、图像和视频 provider 步骤可能需要配置好的 API 密钥或 provider 凭据。工作流应将缺失凭据视为配置阻断，而非静默降级输出。

使用 MetaSkill 的两种方式

默认：显式命令

用 /meta <name> 启动 workflow，然后描述结果：

/meta meta-kid-project-planner

Plan a safe 20-minute balcony plant science project for a 7-year-old. Include
materials, steps, safety notes, and a simple presentation outline.

这是 0.4.0 的常规路径。由于 workflow 的启动是显式的，它最适合重要、昂贵或容易混淆的任务。

兼容：自动触发

如果设置了 meta_skill.auto_trigger = true，OpenSquilla 可以从自然语言意图考虑 MetaSkills：

Use meta-skill `meta-kid-project-planner`.

Plan a safe 20-minute balcony plant science project for a 7-year-old. Include
materials, steps, safety notes, and a simple presentation outline.

此模式面向那些有意要恢复旧的自动触发行为的用户。它不是默认设置。

低成本、高质量请求模板

推荐模板：

/meta <name>

Outcome:
Context:
Decision standard:
Expected output:
Constraints:
Do not:

示例：

/meta meta-kid-project-planner

Outcome: plan a child-safe weekend science project.
Context: 7-year-old, balcony plants, 20 minutes of activity, ordinary household
materials only.
Decision standard: safe, age-appropriate, low mess, and easy to present at
school.
Expected output: materials list, adult setup, child steps, safety notes, and a
presentation outline.
Constraints: avoid flames, blades, solvents, and risky chemicals.
Do not: ask the child to do adult-only setup alone.

有用的约束：

不要编造缺失的事实。
区分事实、假设和建议。
除非有可用来源，否则只使用粘贴的材料。
不要自动提交、发布、安装、付款、发送或签署。
当决策依赖于缺失的信息时向我询问。

内置 MetaSkill 使用模式

`meta-kid-project-planner`

用于儿童学校项目、show-and-tell、科学演示和安全的创意活动。

适合：

科学集市；
show-and-tell；
课堂演示；
适合儿童的手工或实验；
低负担的家长准备。

高质量请求：

/meta meta-kid-project-planner

Help my child prepare a second-grade science fair project about plant growth. We
have beans, paper cups, cotton, water, and a sunny windowsill.

Keep it safe and simple.

Give me:
- materials list
- 3-day plan
- what the child should observe
- short presentation script
- what remains unknown

预期结果：安全、适龄、来源严格的输出。不应编造天气、学校要求或孩子的偏好。

`meta-paper-write`

用于学术论文、研究稿件以及面向 LaTeX 的交付物。

适合：

紧凑的论文骨架；
章节结构；
引用规划；
实验和图表占位符；
显式请求时的 LaTeX/PDF 路径。

PDF 编译要求 PATH 上有 xelatex 和 bibtex。如果缺少这些二进制，使用 LaTeX 源码输出，或在请求编译 PDF 之前安装 TeX Live、MiKTeX 或 BasicTeX。

高质量请求：

/meta meta-paper-write

Draft a compact research paper skeleton on retrieval-augmented generation for
customer-support knowledge bases.

Include:
- title
- abstract
- related work plan
- method outline
- experiment placeholders
- figure/table placeholders
- citation plan

Keep it compact first. Do not write a full manuscript unless I ask.

预期结果：一份论文形态的交付物，而非通用文章。除非真的经过验证，否则不应把引用呈现为已验证的来源。

`meta-skill-creator`

用于创建新的 MetaSkill 提议。

适合：

将重复的多 skill 协作转化为可复用能力；
定义触发面；
组合现有的 skills；
加入校验和风险检查；
产出待审阅的提议。

不适合：

创建一个普通的单一用途 skill；
在不创建任何东西的前提下分析已有 skill 列表；
询问 MetaSkill 是什么；
粘贴旧页面以求诊断。

高质量请求：

/meta meta-skill-creator

Create a new meta-skill for product launch briefs. It should search current
sources, collect product context, draft a launch memo, generate a DOCX handoff,
check evidence gaps, and avoid publishing anything automatically.

Please propose:
- name
- description
- triggers
- steps
- validation gates
- collision checks

预期结果：一份提议，而非立刻未经审阅就上线。

避免误触发

如果你粘贴旧聊天记录、Web UI 转储、prompt 示例、skill 列表或测试材料，请将其标记为引用上下文：

The following is quoted context, not my current request.
Do not run any skill.
Do not create or persist any proposal.
Only analyze this text.

这一点很重要，因为历史材料可能包含触发词。若没有清晰的边界，系统可能将引用内容与当前意图混淆。

如果你只想分析 MetaSkill 而不希望创建提议：

Only analyze. Do not create, assemble, preview, or persist any meta-skill
proposal.

运行进度条带

当 MetaSkill 运行时，WebUI 会在 agent 回复的顶部显示一条水平条带，列出 workflow 中的每个步骤。当前正在运行的 chip 会被高亮；成功的步骤显示 ✓、跳过的显示 ↷、失败的显示 ✗，on_failure 替代步骤显示 ⇄。点击任意 chip 可滚动到该步骤的工具卡片。如果某个步骤失败，条带还会就地呈现 “Retry run”、“Switch meta-skill” 与 “Show error detail” 等操作。

条带能在断线后保留：当浏览器重新连接时，gateway 会回放 announce → state → completed 事件，使条带重建到最新状态。

阅读结果

一份强有力的 MetaSkill 结果应当说明：

它产出了什么；
它使用了哪些事实或来源；
哪些是推断或假设的；
还存在哪些风险；
下一步行动是什么；
哪些内容无法验证；
是否真的创建了某个 artifact 或提议。

如果输出出现以下情况，请保持警惕：

不带来源就声明当前事实；
声称文件已创建但并不存在 artifact；
将工具失败伪装为成功；
给出通用建议而非所请求的交付物；
忽略”不要创建”、“不要发送”、“不要发布”或”不要安装”。

修正一次糟糕的运行

如果触发了错误的 MetaSkill：

Stop using the previous MetaSkill. Treat my earlier text as context only. Now
use meta-skill `<correct_name>` for this goal: ...

如果没有任何 MetaSkill 被触发：

Please rerun and explicitly use meta-skill `<name>`.

如果输出太通用：

Redo this as a decision-ready deliverable with evidence, assumptions, risks, and
next actions.

如果 creator 开始创建但你不希望创建：

Do not create, assemble, preview, or persist any meta-skill proposal. Only
analyze.

构建你自己的 MetaSkill

当一项任务符合以下条件时，它是一个良好的 MetaSkill 候选：

你反复执行同一项高价值任务；
每次执行都有多个步骤；
输入相似但细节不同；
输出格式相对稳定；
审阅、审计、回放或确认很重要；
普通 prompt 要求你每次重述太多规则。

不佳的候选包括：一行式事实查询、单次工具调用、随意对话、缺乏稳定输出标准的头脑风暴，以及无人工确认的高风险自动操作。

关于编写协议，请阅读 ../authoring/meta-skills.md。

文档索引 · 产品指南 · 改进此页面 · 报告文档问题