Assistant skills

Who it’s for

Lab owners who repeat the same kind of job, such as checking image updates or patching a server.

What it covers

What a skill is, where to find the built-in ones, how to write or import your own, and what each script is allowed to do.

Why it exists

The assistant knows a lot in general but not how you like things done. A skill puts your steps and checks in one place, so every chat and job follows the same method.

A skill is a folder of instructions, with optional files and scripts, that the assistant reads when a task fits it. Think of it as a runbook. You write the steps once, and the assistant follows them the same way each time.

Lucia ships five built-in skills. You can read them, but not change them. You can duplicate one to make your own version.

Built-in skill	What it covers
App troubleshooting	Working out why an app is down or restarting
Container image updates	Checking whether a newer image exists and what changing it involves
Custom app authoring	Writing a custom app for the catalog
OS security patching	Checking for and planning OS security updates
Skill authoring	Turning commands you declined or that timed out into narrow skills for you to review

Find the skills

Open Settings → Assistant skills. The page lists every skill, with its name, a short description, where its scripts run and whether it is on. Turn a skill off to hide it from the assistant. A turned-off skill stays saved, so you can turn it back on later.

Choose a skill to see its instructions and files. Built-in skills show a note that says they are read-only.

Make a skill

You can add a skill three ways.

• New skill. Give it a name, such as zfs-pool-health, and a short description. The description helps the assistant decide when the skill fits, so write it as one plain sentence. Lucia creates the folder with a starter SKILL.md file.
• Upload a package. Send a zip of a skill folder. A zip can be at most 5 MiB.
• Import from GitHub. Paste the address of a folder on github.com, such as https://github.com/owner/repo/tree/main/skills/my-skill. Lucia reads the folder through GitHub's public API, so private repositories won't import.

Skill names use lowercase letters, numbers and single hyphens. A skill can hold up to 200 files, with 1 MiB for each file and 5 MiB in total. The editor lets you change text files up to 256 KiB.

A skill folder looks like this:

my-skill/
  SKILL.md          instructions, with a short header at the top
  scripts/          scripts the assistant can run
  references/       notes it reads when it needs more detail
  assets/           other files it can read

The header in SKILL.md holds the skill's name, description and settings:

---
name: zfs-pool-health
description: Checks ZFS pool health on the TrueNAS box and reports any pool that is degraded.
metadata:
  lucia.execution: node
  lucia.tier: read
---

Run scripts/check-pools.sh on the storage server, then summarize any pool that is not ONLINE.

A skill can also describe the arguments its scripts take, under parameters_schema in metadata. Write it as a JSON Schema object with "type": "object", and list each argument with its type and limits. The assistant reads that description before it calls a script, so it sends the right values. The script still checks its own input.

Turn declined commands into skills

When the assistant asks to run a command and you decline it, or the answer never comes, that call stays in the chat. The sessions list shows a count for each chat, such as "2 declined · 1 timed out".

To act on those calls, type / in the chat box and choose /create-skill. A chip appears. Choose This chat, or Choose chats… to pick up to 10 saved chats, newest first. Add an optional note, then send.

The assistant reads the problem calls and drafts narrow skills. Each draft is saved disabled, so nothing runs until you enable it. When it drafts one, the chat shows a card with the skill's name and any warnings, and a link to review it.

Review a draft

The Skills page has a Needs review section above the list. The Skills item in the menu shows how many drafts wait. Each draft shows the assistant's reason, links to the chats it came from, and any warnings.

• Open shows the full skill, so you can read the script before you decide.
• Enable turns the draft on. Lucia checks that the draft is the exact version you are looking at. If the assistant changed it since you opened the page, Enable fails with a message, and you need to review it again.
• Delete removes the draft.

Warnings come from a set of quick checks. They flag a command passed straight to the shell, a read-only script that seems to change something, arguments that are used without checking, and network calls. A warning is a prompt to look closer, not a verdict.

Once you enable a draft, or edit it yourself, the assistant can no longer change it.

Approve a change to a skill

The assistant can change a skill you own, or a draft it wrote, through an edit. It never applies an edit on its own. The chat shows a diff for each changed file, and nothing is written until you approve it.

• Each edit needs its own approval. There is no "always allow" for edits.
• The assistant doesn't propose edits in Plan mode or in scheduled jobs.
• Built-in skills can't be edited. Duplicate one instead.
• An approval lasts 2 hours. If the skill changed while you were deciding, the edit is refused and the assistant has to ask again.

Where a script runs

Each skill picks where its scripts run. You set it in the skill's header, and you can see it on the skill's page.

Where	What it means	Use it for
On a server	The script runs on the managed server the assistant names. The server's agent runs it.	Checks and changes that must happen on that machine
On the Spark	The script runs on the Spark, in a throwaway container.	Checks that belong on the Spark itself
In the sandbox	Python and JavaScript run in an isolated micro-VM on a server with KVM. The script gets no network unless the skill allows it.	Scripts you want kept away from the rest of the server

A sandboxed script needs a server with hardware virtualization (KVM). If none of your servers has it, the assistant says so and the script doesn't run.

Each skill also has a tier, which sets how much approval it needs:

• Read. The script only looks. It runs without asking.
• Change. The script changes something. It asks first, unless you have allowed it.
• Destructive. The script can delete or interrupt something. It always asks in a chat.

Lucia checks the tier when the script runs. It takes the tier from the skill's header, so a skill can't lower its own tier by editing a file.

Approve a script

The first time the assistant wants to run a script that isn't read-only, its approval card shows the skill's name, its tier and where it runs. You can approve once, or pick the card's option to always allow that skill's scripts for the chat.

A standing "always allow" applies to one exact version of the skill. The grant includes a short fingerprint of the skill's content. If you edit the skill, the grant no longer matches, and the next run asks you again. This keeps a changed script from running on an old yes.

warning

A script that runs on a server runs with the same reach as a command you type there. Read the script before you approve it, the same way you would read a command.

Use skills in jobs

Each job has a Skills it may use list. Leave it empty to give the job no skills, choose specific skills, or choose All enabled skills. Built-in skills are offered to every job, because they only describe tools the job already has. A job still asks before a script runs, as described in Assistant jobs.

Refresh the list

When you add or change a skill during a chat, say so in your message, for example "I just added a skill for the backups." The assistant then reloads the list. Its new tools join the chat from your next message.

Problems

You see	What to do
"Built-in skills are read-only"	Duplicate the skill and edit the copy.
"parameters_schema in the SKILL.md metadata must be a JSON Schema object with "type": "object""	Fix the parameters_schema header so it is a JSON Schema object with "type": "object".
"Lucia keeps at most 200 skills"	Delete or turn off skills you no longer use.
"The skill is larger than 5 MiB"	Remove large files from the folder, or move them out of the skill.
A server says it can't run sandboxed skills	That server has no KVM. Use a different server or put the script on a server or the Spark.
"That skill no longer exists"	The skill was deleted or turned off during the chat. Turn it back on, or ask again.
A script asks again after you edited it	The skill's version changed, so earlier "always allow" choices no longer apply. Review the change and approve again.
Enable says the draft changed	The assistant updated the draft after you opened it. Open it again and review the new version.
"The skill changed after you approved; ask again."	The edit was refused because the skill changed after the approval card appeared. Ask the assistant to make the change again.
An edit to a built-in skill is refused	Built-in skills can't be edited. Duplicate the skill and edit the copy.

For the rest of the assistant, see Assistant.