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:

/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:

[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:

/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:

/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:

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:

/meta <name>

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

Example:

/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:

/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:

/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:

/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:

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:

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:

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:

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

If the output is too generic:

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

If creator starts creating but you do not want creation:

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.

---

Docs index · Product guide · Improve this page · Report a docs issue