opensquilla--opensquilla/docs/features/meta-skill-user-guide.md

# OpenSquilla MetaSkill User Guide

MetaSkill lets OpenSquilla move from figuring out complex work from scratch on
every turn to reusable, explicitly launchable, auditable, and improvable task
protocols.

A normal conversation solves one request. A MetaSkill preserves a way of doing
high-value work.

## Important Notice

Some MetaSkills in OpenSquilla, and some of the skills they call, are authored,
revised, or composed with AI assistance based on intended functionality,
available capabilities, and usage scenarios.

This means:

- MetaSkills are not merely a collection of fully hand-written scripts. They are
  part of a system where AI can help formalize and evolve reusable task
  protocols.
- AI-authored or AI-assisted MetaSkills should be reviewed through structural
  validation, trigger-surface checks, runtime testing, human review, and
  safety-boundary assessment before they are treated as ready for use.
- MetaSkill outputs are decision-support materials and work-product drafts. They
  are not final professional advice in legal, medical, financial, hiring,
  academic, security, or other high-stakes contexts.
- Actions such as publishing, applying, installing, paying, signing, messaging,
  or modifying production systems require explicit user authorization and remain
  the user's responsibility.
- When a MetaSkill relies on search, document parsing, LLM judgment, or
  third-party tools, the result may be affected by source quality, model
  limitations, tool availability, context completeness, and time-sensitive
  changes.
- Users should review facts, citations, assumptions, risks, and unverifiable
  claims, especially in high-stakes situations.

In short: MetaSkill turns high-value work into reusable, auditable, and
improvable AI collaboration protocols. It does not remove the need for review,
judgment, or accountability.

## What It Is

OpenSquilla is an open-source AI agent runtime. MetaSkill is its task-protocol
layer.

A MetaSkill does not introduce new execution atoms. It defines a way to organize
existing atoms, such as skills, tools, LLM calls, and sub-agents, into a
reusable task protocol.

The analogy is a Makefile and shell commands. A Makefile does not replace
commands; it defines how commands are composed. A MetaSkill does not replace
skills or tools; it tells OpenSquilla how a class of high-value work should be
understood, structured, checked, and delivered.

MetaSkill provides four main advantages:

- protocolized capability captured in a `SKILL.md` file with `kind: meta` and
  `composition.steps`;
- explicit launch through `/meta`, with optional automatic triggering only when
  `meta_skill.auto_trigger = true`;
- auditable and replayable step inputs, outputs, status, and results;
- improvable over time as repeated collaboration patterns become proposals.

## Default Launch Model

MetaSkills are manual-only by default. On supported chat surfaces, use `/meta`
to list available workflows and `/meta <name>` to run one. This keeps workflow
launches deliberate, reviewable, and easier to explain.

Web chat and the CLI gateway TUI support both list and run:

```text
/meta
/meta meta-kid-project-planner
```

Channel surfaces support `/meta` listing only. Standalone CLI chat requires
gateway mode for `/meta`.

To restore the older automatic behavior, set:

```toml
[meta_skill]
auto_trigger = true
```

With `auto_trigger = true`, OpenSquilla may consider MetaSkills during ordinary
natural-language turns. Leave it off when you want workflows to run only after
an explicit `/meta <name>` command.

## User Mental Model

Using a MetaSkill is not just asking a question. It is delegating OpenSquilla to
produce a reviewable result.

A strong MetaSkill request contains four things:

1. Outcome: what you want to receive.
2. Context: materials, entities, time range, and constraints that matter.
3. Standard: what "good" means for this task.
4. Boundaries: what must not happen, what must not be invented, and what requires
   confirmation.

Example:

```text
/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.
```

The user defines the target and standard; OpenSquilla organizes the execution.

## Current Built-In MetaSkills

The retained built-in MetaSkills cover a focused set of high-value task classes.

| MetaSkill | Positioning |
| --- | --- |
| `meta-kid-project-planner` | Produces safe, age-appropriate plans for school projects, show-and-tell, or science activities. |
| `meta-paper-write` | Supports academic drafts, manuscript structure, citation planning, experiment placeholders, and LaTeX/PDF paths. |
| `meta-short-drama` | Produces short-drama scripts, visual prompts, video assembly plans, subtitles, and rendered local video artifacts. |
| `meta-skill-creator` | Turns repeated multi-skill collaboration patterns into new MetaSkill proposals. |

These are designed around quality over quantity. Immature, duplicate, or
single-skill wrapper MetaSkills should not remain in the bundled catalog.

## Requirements Before Running MetaSkills

The Skill page is the source of truth for current readiness. Open the skill
detail dialog and check the **Requirements** section before running workflows
that export files, compile PDFs, or render video.

Common setup surfaces:

- Paper/PDF workflows such as `meta-paper-write` require `xelatex` and
  `bibtex` on `PATH`. Install a TeX distribution such as TeX Live, MiKTeX, or
  BasicTeX before requesting compiled PDFs.
- Video workflows such as `meta-short-drama` require `ffmpeg` and `ffprobe` on
  `PATH` for clip animation, merging, and subtitle burn-in.
- Office-document workflows roll up requirements from child skills such as
  `docx`, `xlsx`, `pdf-toolkit`, and `pptx`; these usually surface Python
  package requirements in the Skill page.
- Search, weather, image, and video-provider steps may require configured API
  keys or provider credentials. The workflow should treat missing credentials as
  setup blockers rather than silently degrading output.

## Two Ways to Use MetaSkill

### Default: Explicit Command

Start the workflow with `/meta <name>` and then describe the outcome:

```text
/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.
```

This is the normal 0.4 release-line path. It is best for important, expensive,
or easily confused tasks because the workflow launch is explicit.

### Compatibility: Automatic Triggering

If `meta_skill.auto_trigger = true` is set, OpenSquilla can consider MetaSkills
from natural-language intent:

```text
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.
```

This mode is for users who intentionally want the older auto-trigger behavior.
It is not the default.

## Low-Cost, High-Quality Request Template

Recommended template:

```text
/meta <name>

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

Example:

```text
/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.
```

Useful constraints:

- Do not invent missing facts.
- Separate facts, assumptions, and recommendations.
- Use only pasted material unless sources are available.
- Do not submit, publish, install, pay, send, or sign automatically.
- Ask me if a decision depends on missing information.

## Built-In MetaSkill Usage Patterns

### `meta-kid-project-planner`

Use for child school projects, show-and-tell, science demos, and safe creative
activities.

Good fit:

- science fair;
- show-and-tell;
- classroom demonstration;
- child-safe craft or experiment;
- low-burden parent preparation.

High-quality request:

```text
/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
```

Expected result: safe, age-appropriate, source-strict output. It should not
invent weather, school requirements, or child preferences.

### `meta-paper-write`

Use for academic papers, research manuscripts, and LaTeX-oriented deliverables.

Good fit:

- compact paper skeleton;
- section structure;
- citation plan;
- experiment and figure/table placeholders;
- LaTeX/PDF path when explicitly requested.

PDF compilation requires `xelatex` and `bibtex` on `PATH`. If those binaries are
missing, use the LaTeX source output or install TeX Live, MiKTeX, or BasicTeX
before asking for a compiled PDF.

High-quality request:

```text
/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.
```

Expected result: a paper-shaped deliverable, not a generic essay. Citations
should not be presented as verified sources unless actually verified.

### `meta-skill-creator`

Use to create a new MetaSkill proposal.

Good fit:

- turning repeated multi-skill collaboration into a reusable capability;
- defining trigger surfaces;
- composing existing skills;
- adding validation and risk checks;
- producing a proposal for review.

Poor fit:

- creating a normal single-purpose skill;
- analyzing existing skill lists without creating anything;
- asking what MetaSkill is;
- pasting old pages for diagnosis.

High-quality request:

```text
/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
```

Expected result: a proposal, not an immediate unreviewed production rollout.

## Avoiding Accidental Activation

If you paste old chat history, Web UI dumps, prompt examples, skill lists, or
test material, mark it as quoted context:

```text
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.
```

This matters because historical material may contain trigger words. Without a
clear boundary, the system may confuse quoted content with current intent.

If you only want to analyze a MetaSkill and do not want proposal creation:

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

## Run Progress Ribbon

While a MetaSkill runs, the WebUI shows a horizontal ribbon at the top
of the agent reply listing every step in the workflow. The currently
running chip is highlighted; succeeded steps show ✓, skipped ↷, failed
✗, and `on_failure` substitutes show ⇄. Click any chip to scroll to
that step's tool card. If a step fails, the ribbon also surfaces
"Retry run", "Switch meta-skill", and "Show error detail" actions
inline.

The ribbon survives disconnects: when the browser reconnects, the gateway
replays the announce → state → completed events so the ribbon rebuilds
to the latest state.

## Reading the Result

A strong MetaSkill result should explain:

- what it produced;
- what facts or sources it used;
- what is inferred or assumed;
- what risks remain;
- what the next action is;
- what could not be verified;
- whether any artifact or proposal was actually created.

Be cautious if the output:

- claims current facts without sources;
- claims a file was created but no artifact exists;
- hides tool failures as success;
- gives generic advice instead of the requested deliverable;
- ignores "do not create", "do not send", "do not publish", or "do not install".

## Correcting a Bad Run

If the wrong MetaSkill triggered:

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

If no MetaSkill triggered:

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

If the output is too generic:

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

If creator starts creating but you do not want creation:

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

## Building Your Own MetaSkill

A task is a good MetaSkill candidate when:

- you repeatedly perform the same high-value task;
- each run has multiple steps;
- inputs are similar but details vary;
- the output format is relatively stable;
- review, audit, replay, or confirmation matters;
- ordinary prompts require you to restate too many rules every time.

Poor candidates include one-line fact queries, single tool calls, casual
conversation, brainstorming without stable output criteria, and high-risk
automated action without human confirmation.

For the authoring protocol, read [`../authoring/meta-skills.md`](../authoring/meta-skills.md).

---

[Docs index](../README.md) · [Product guide](../../README.product.md) · [Improve this page](../contributing-docs.md) · [Report a docs issue](https://github.com/opensquilla/opensquilla/issues/new?template=docs_report.yml)