Agent skills

A skill is a reusable playbook: a short description tells agents when it applies, and its instructions explain how to do that kind of work well. Skills add knowledge, not tools or permissions. Every agent can discover and load relevant skills without receiving every skill's full text on every model call.

Create a personal skill

Ask the Assistant to save a repeated workflow as a skill. It creates a Markdown file in the VFS through the run's normal permission mode; in the default mode, the write pauses for approval. The file appears at:

~/Skills/<slug>/SKILL.md

You can also create or edit that file directly in VSCode. Use this format:

---
name: Prepare a weekly product review
description: Use when preparing the weekly product review from current project and support data.
---

1. Gather the current project status and recent support themes.
2. Separate verified facts from open questions.
3. Draft a one-page review with decisions needed at the top.
4. Link every claim to the record or source it came from.

Keep the description concrete: agents use it to decide whether to load the skill. Put durable steps and quality checks in the body; keep a personal skill under 32,000 characters so listing and background reads stay fast. Do not put credentials, private keys, or approval instructions in a skill. A skill cannot approve an action or grant an agent additional tools.

How agents use skills

The skills_list tool returns skill ids, descriptions, and their source. When one description matches the task, the agent calls skills_read with that id. This is progressive disclosure: list first, load only what is useful, then do the work with the agent's configured tools.

Built-in skills cover working across NextOS, making apps, scripts, extensions, sites, and desktop skins. Team skills appear when the account's governance policy allows them. Your own VFS skills are identified with ids such as local:weekly-product-review.

The Assistant and configured agents use the same skills. A team can restrict which built-in, team, and personal VFS skills agents may read in Settings > Governance; enabling personal skills uses the local:* policy entry. An empty “Only these” selection blocks all skills. Pinned built-in and team skills are added to the Assistant's context automatically; other agents can load an allowed skill when relevant.

Background runs

Background agents can always load allowed built-in and team skills. To use personal VFS skills in a background run, enable background runs and Drive access in Settings > Privacy, then let ~/Skills sync. Without Drive access, a background agent explains that the personal skill files are unavailable; it does not pretend to have read them.

What a skill can and cannot do

A skill explains a workflow. The agent still needs an allowed tool for each real action, and the normal approval rules still apply. Skill text is treated as task guidance; it cannot override what you asked for, change the agent's permissions, or authorize destructive actions.

Team-wide skills can be authored, governed, and pinned in Settings > Governance. Personal skills stay in your VFS and can be read or edited like any other Markdown file.