Automation and apps

Guide

Create a skill

Write a SKILL.md with optional reference files and scripts, import it, give it to an agent, and add a slash command that uses it.

At the end of this guide an agent has a skill of yours: instructions it loads when a question needs them, with reference files it reads on demand, and a slash command that turns a repeated request into one line. An organization skill needs the Manage organization skills permission, and you become its Admin; a private skill for your own assistant needs Create private skills. Attaching a skill to a shared agent is an admin's job.

Before you begin

  • Manage organization skills (for an organization skill) or Create private skills (for a private one).
  • For scripts, a sandbox profile you can bind to the skill.
  • An agent to give the skill to: your personal assistant, or a shared agent whose settings you manage.

Write the SKILL.md

  1. Make a folder named after the skill, such as release-checklist, and put a SKILL.md in it.
  2. Write the frontmatter: name is the slug (lowercase letters, digits and hyphens), description says what the skill does and when to use it.
  3. Write the instructions in the body. Keep them short; move long procedures into reference files.
Text
---
name: release-checklist
description: Walks a release through its checklist and drafts the release notes page. Use when someone prepares, checks or announces a release.
allowed-tools: search_pages read_page create_page update_page
---

## When activated

1. Read `references/checklist.md` and go through it item by item.
2. Search for an existing release notes page before creating a new one.
3. Never invent version numbers or dates. Ask when they are not given.

Note

allowed-tools is a suggestion. Volobox maps the built-in tool keys it knows, shows unknown ones as warnings, and grants nothing: the people who configure the skill decide what it may use.

Add reference files or scripts (optional)

  1. Put each file in the skill's folder. Files keep the path they have relative to SKILL.md. Text documents (markdown, JSON, YAML, CSV and similar) are references the agent reads on demand; runnable files outside references/ and assets/ are scripts.

    Text
    release-checklist/
      SKILL.md
      references/
        checklist.md
      scripts/
        collect_changes.py
  2. Zip the folder for import. A zip can hold several skills: every folder with an exact SKILL.md is one. The format is in Skills and packs.

Import the skill

  1. For an organization skill, open Organization Settings > AI > Skills, stay on Organization and choose Import. For a private skill, open your Personal Settings > AI > Skills, then Private > Import.
  2. Choose Paste SKILL.md and paste the document, or Upload zip and choose Upload bundle (.zip).
  3. Choose Preview. Check the slug, description, body, suggested built-in tools, the files that will be imported, the files that will not be imported (each with its reason), and the warnings.
  4. If a skill with the same slug exists, the preview names it and offers Overwrite when you may overwrite it. Otherwise rename the skill in the file.
  5. Choose Import skill. The skill opens.
The Skill library in Organization Settings, AI, Skills: the Organization tab with Import and Create skill, and the organization's skills as cards.

To change it later, edit it in place (text files on its Files tab can be edited in the browser), or use ⋯ > Replace from file… on the skill.

Let its scripts run

  1. On the skill's Sandbox tab, bind a sandbox profile. Without one, scripts are readable but never run.
  2. Each run then raises an approval card with the exact command line before it runs.
  3. For scheduled or event-triggered workflows, an administrator opens the organization skill, finds Unattended automation, selects Trust for automations, reviews the content hash and every file, and selects Trust this revision. Changing the skill's content revokes the trust.

Give it to an agent

  1. Open the agent's settings: your personal assistant's, or, for a shared agent, the agent's (admins).
  2. Open Skills > Default skills.
  3. Choose the skill in Add a skill… and add it. On a shared agent, people without access to the skill do not see or load it when they chat with the agent.

The agent starts each turn with a small baseline of tools and turns a skill on when a question needs it, so you do not have to mention the skill by name.

Warning: Enable and Disable apply to everyone

Enable and Disable on a skill's card or page turn it on or off for everyone who uses it, not only for you. A turned-off skill does not load, even when an agent has it.

Add a slash command

  1. Open Commands in your Personal Settings > AI (or in Organization Settings > AI for an organization command) and choose Create command.

  2. Set the Handle (lowercase, typed after /), such as release-prepare, the Display name and a starting Prompt template, then choose Save and edit details.

  3. On the Prompt tab, write the template. {{args}} takes the free text after the handle; {{version}} takes a named input.

    Text
    Prepare release {{version}} with the release checklist. {{args}}
  4. On the Inputs tab, add the input: Label "Version", Name version, Type Free text, required.

  5. Save, and attach the command to the agent if it is not Available on all agents. To use it in coding sessions too, turn on Usable in coding sessions on Overall.

A command can also name skills it always enables or suggests. A prompt you already sent can become a command: hover your own message in an agent chat and choose Save as command.

Check that it works

  • In a chat with the agent, ask something the skill's description covers. The agent turns the skill on and follows its instructions, reading references/checklist.md when it needs it.
  • Type / in the composer: the command is listed. Send /release-prepare version=2.4.0 focus on the API changes, and the agent receives the rendered prompt, not the slash line.
  • A script run shows an approval card with its command line.

Troubleshooting

SymptomFix
The import is rejected as an existing slugChoose Overwrite if you may, or rename the skill in the file. A personal import cannot overwrite an organization skill; use Replace from file… on the skill instead
A file was not importedThe preview and the result list each skipped file with its reason, such as an executable type or a path with characters that are not allowed
The agent never uses the skillCheck that the skill is turned on, attached to the agent, and that you have access to it
A script is readable but does not runBind a sandbox profile on the skill's Sandbox tab
A scheduled workflow cannot run the skill's scriptTrust the current revision under Unattended automation
The command is missing from the / menuCheck that it is enabled, that you can access it, and that it is attached to the agent (or Usable in coding sessions for a coding session)
A value is not substitutedThe template must contain {{exact_name}} matching the input's Name

Next steps