Skip to main content

Build a custom skill for your agents

Package instructions and scripts into a skill that your Octavus Agents can read and run on any of their computers, Linux, Windows, or Mac.

A skill teaches your Octavus Agents how to do something repeatable: a folder with a SKILL.md that explains the task and, when the task needs code, scripts the agent runs. Skills follow the open Agent Skills format, so a skill written for another assistant usually works here with little change. This article covers how an agent uses a skill, how to write one that runs on every computer an agent can have, and how to add it to Octavus and to your agents.

You need:

  • An owner, admin, or developer role in your organization, which is what creating and editing skills requires.
  • For a skill with scripts, basic Python. A skill can also be instructions only, with no scripts at all.
  • An agent to try it on. Any of your agents works, whatever computer it has.

How an agent uses a skill

Design a skill around how the agent meets it:

  1. The agent always sees the skill's name and description. From those alone it decides whether a task calls for the skill, so the description has to say what the skill does and when to use it.
  2. When the task matches, the agent reads SKILL.md. The body is its instructions: the steps, the scripts to run and with what, what good output looks like. It is loaded only when needed, so it can be as detailed as the task requires.
  3. The agent runs the skill's scripts from the scripts/ folder, passing command-line arguments and, when the instructions call for it, a JSON object on standard input.
  4. Files the script saves to the output folder reach the person. A script writes finished files to the directory named by the OUTPUT_DIR environment variable; the agent collects them and they appear in the thread as files.

The skill lives as a folder on the agent's computer, so the agent can also open its reference documents and assets with its ordinary file tools. The agent installs an attached skill the first time it needs it, and picks up a new version the next time it uses the skill after you save a change.

Anatomy of a skill

text
csv-summary/
├── SKILL.md          # Required: frontmatter + instructions
├── scripts/          # Optional: code the agent runs
│   └── summarize.py
├── references/       # Optional: documents the agent reads only when it needs them
└── assets/           # Optional: files used in the output (templates, images, fonts)

Only these locations are kept when a skill is stored; anything else in a bundle is dropped. Keep SKILL.md focused on the task, and move long reference material into references/ so the agent reads it only when relevant. Do not add a README, a changelog, or setup notes: the agent is the only reader.

SKILL.md

SKILL.md starts with a YAML front matter block, then the instructions in Markdown.

yaml
---
name: csv-summary
title: Summarizing a CSV file
description: >
  Summarize a CSV file: row count, columns, how many values each column is
  missing, and a sample of rows. Use when someone shares a CSV or asks what
  is in a spreadsheet export before deciding what to do with it.
version: 1.0.0
category: Data
---
FieldRequiredRules
nameYesThe skill's identifier: lowercase letters, numbers, and hyphens, up to 40 characters. Changing it renames the skill; it must be unique in your organization
descriptionYesWhat the skill does and when to use it, up to 2000 characters. The agent decides from this text alone whether to use the skill, so make it concrete and include the words a request would contain. Under 1024 characters keeps it valid for other Agent Skills consumers too
titleNoA short label, up to 60 characters, shown in the thread while the skill runs, for example "Summarizing a CSV file"
versionNoA version such as 1.0.0. Bump it when you change the skill
categoryNoA label, up to 60 characters, used to group skills in the library
license, authorNoFree text
secretsNoThe credentials the skill needs; see Give a skill secrets

The body is for the agent. Say when to use the skill, the exact command to run for each script and what it needs, what the output is, and anything the agent would otherwise get wrong. Concise examples beat long explanations: the agent already knows how to read a CSV; it needs to know what you want done with it.

Write scripts that run everywhere

An agent's computer can be a temporary Linux computer, a dedicated Linux or Windows computer, a Mac running the desktop app, or a machine you run the Agent CLI on. The same skill runs on all of them, so write every script for the lowest common denominator. These rules are what the built-in skills follow.

  1. Write entry scripts in Python, never as shell scripts. A .py script runs with Python on every computer. Anything else runs with bash, which a Windows computer does not have, so a .sh entry point fails there. Shell out to other tools from Python with subprocess when you need them.
  2. Never hardcode the skill's location. It differs on every computer. Resolve paths from the script itself: SKILL_DIR = Path(__file__).resolve().parent.parent.
  3. Save output to OUTPUT_DIR, read from the environment. os.environ["OUTPUT_DIR"] is the folder whose files reach the thread. It exists only for the current turn; write finished results there, not working files.
  4. Install your own dependencies, on first use. Nothing beyond Python itself is guaranteed. Probe for what you need and install it when missing (the pattern is below); the install is cached on persistent computers, so later runs skip it.
  5. Force UTF-8. The Windows console defaults to a legacy encoding, so a script that prints an accented name or a check mark can crash after doing its work. Pass encoding="utf-8" to every text file you open, and reconfigure sys.stdout and sys.stderr at the top of the script.
  6. Branch on the operating system, and build paths portably. Use platform.system() to branch, shutil.which() to find a program (it handles .exe on Windows), pathlib for paths, tempfile.gettempdir() instead of /tmp, and os.pathsep instead of :. apt-get and sudo exist only on the temporary computer; on the dedicated computers and the Mac, install at the user level (pip, npm into a local folder, Homebrew where present, winget on Windows).
  7. Write python3 in commands and documentation. The runtime picks the right interpreter for a .py script on each computer; your instructions should name python3.
  8. Never embed credentials. Declare them under secrets: in the front matter and read them from environment variables at run time.

A script's working directory is the skill's folder, and it runs with a minimal environment: a few system variables, the skill's secrets, and OUTPUT_DIR. It has five minutes to finish. Its stdout and stderr are returned to the agent (up to 10 MB), and the files it saves to OUTPUT_DIR are collected up to 20 MB per file and 50 MB per run. Exit with a non-zero code and a one-line reason on stderr when something is wrong; the agent reads it and can fix its input or explain the problem.

Installing dependencies

Nothing but Python is guaranteed, so each entry script makes sure its own imports are available before using them. Prefer uv when it is present (it is on every Octavus computer and is much faster), fall back to pip, and print one line to stderr so the install is visible in the thread:

python
import importlib.util
import shutil
import subprocess
import sys


def ensure(*packages: str) -> None:
    """Install the pip packages that are not importable yet, then return."""
    missing = [p for p in packages if importlib.util.find_spec(p.split("==")[0]) is None]
    if not missing:
        return
    print(f"[csv-summary] installing {', '.join(missing)}...", file=sys.stderr, flush=True)
    if shutil.which("uv"):
        cmd = ["uv", "pip", "install", "--python", sys.executable, "--break-system-packages", "-q", *missing]
    else:
        cmd = [sys.executable, "-m", "pip", "install", "--break-system-packages", "-q", *missing]
    try:
        subprocess.check_call(cmd)
    except subprocess.CalledProcessError:
        subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", *missing])

When an import name differs from the package name (PIL comes from Pillow, yaml from PyYAML), map one to the other before calling ensure.

What each computer provides

ComputerAlways there
Temporary computer (Linux)Python 3, uv, pip, requests, httpx, pyyaml, python-dateutil; LibreOffice, pdftoppm and pdftotext, pandoc, ffmpeg
Dedicated computer (Linux)Python 3, uv, Node.js, Homebrew, LibreOffice. Installs are at the user level; there is no sudo
Dedicated computer (Windows)Python 3, uv, pip, Node.js, PowerShell. No bash
Mac (desktop app)Python 3.12, uv, Node.js, requests, httpx, pyyaml, python-dateutil, plus whatever the Mac has
Your own machine (Agent CLI)Whatever you installed. python3 must be on the PATH for .py scripts

Treat the table as a floor, not a contract: probe with shutil.which() and importlib.util.find_spec() and install what is missing.

A complete example

A skill that summarizes a CSV file the agent has on its computer. It uses only the standard library, takes its input as a command-line argument, and saves its result to OUTPUT_DIR.

SKILL.md:

markdown
---
name: csv-summary
title: Summarizing a CSV file
description: >
  Summarize a CSV file: row count, columns, how many values each column is
  missing, and a sample of rows. Use when someone shares a CSV or asks what
  is in a spreadsheet export before deciding what to do with it.
version: 1.0.0
category: Data
---

# CSV summary

Use this before working with a CSV you have not seen, so you describe the
file accurately and spot missing data early.

## Run

`python3 scripts/summarize.py <path-to-file.csv> [--sample 5]`

The script saves `summary.md` to the output folder and prints the same
summary. Read it, then tell the person what the file contains and anything
that looks off: a column that is mostly empty, far fewer rows than expected.

## Notes

- The file must be a comma-separated text file. For an Excel workbook,
  export the sheet to CSV first.
- `--sample` sets how many rows the summary shows (default 5).

scripts/summarize.py:

python
#!/usr/bin/env python3
"""Summarize a CSV file: rows, columns, missing values, and a sample."""

import argparse
import csv
import os
import sys
from pathlib import Path

for stream in (sys.stdout, sys.stderr):
    try:
        stream.reconfigure(encoding="utf-8")
    except (AttributeError, ValueError):
        pass


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("path", help="The CSV file to summarize")
    parser.add_argument("--sample", type=int, default=5, help="Rows to show")
    args = parser.parse_args()

    path = Path(args.path)
    if not path.is_file():
        print(f"File not found: {path}", file=sys.stderr)
        return 1

    with path.open(encoding="utf-8", newline="") as handle:
        reader = csv.DictReader(handle)
        columns = reader.fieldnames or []
        rows = list(reader)

    missing = {column: sum(1 for row in rows if not (row.get(column) or "").strip()) for column in columns}

    lines = [f"# {path.name}", "", f"- Rows: {len(rows)}", f"- Columns: {len(columns)}", "", "## Columns", ""]
    lines += [f"- `{column}`: {missing[column]} missing" for column in columns]
    lines += ["", f"## First {min(args.sample, len(rows))} rows", ""]
    lines += [", ".join(f"{column}={row.get(column, '')}" for column in columns) for row in rows[: args.sample]]
    summary = "\n".join(lines) + "\n"

    output_dir = Path(os.environ.get("OUTPUT_DIR", "."))
    output_dir.mkdir(parents=True, exist_ok=True)
    (output_dir / "summary.md").write_text(summary, encoding="utf-8")

    print(summary)
    return 0


if __name__ == "__main__":
    sys.exit(main())

When a script needs structured input rather than a file path, have the instructions say so and read a JSON object from standard input (json.load(sys.stdin)): the agent passes it as the run's input.

Add the skill to Octavus

In the dashboard, open Library in the header; it opens on Skills, your organization's collection of skills and connectors. Select Create Skill. Two ways:

  • Start from scratch: give the skill a name and a description. The editor opens with SKILL.md; add your scripts and other files there, then Save. The editor also uploads a ZIP to replace the files, and downloads the skill as a ZIP.
  • Upload a bundle: zip the skill folder and upload the .zip (or .skill) file, up to 50 MB. SKILL.md must be at the root of the archive or in a single top-level folder; only SKILL.md, scripts/, references/, and assets/ are kept, and hidden files are dropped.

An upload is rejected when the front matter is invalid; the message says which field. The name in the front matter becomes the skill's identifier.

You can also create and update skills from Cursor or Claude Code with the save_skill tool of the MCP server.

Give a skill secrets

A skill that calls a service with a key or token declares the credentials it needs, and never contains them:

yaml
secrets:
  - name: ACME_API_TOKEN
    description: An Acme API token with read access to invoices
    required: true
  - name: ACME_REGION
    description: The Acme region to call, such as eu or us
    required: false

Names are uppercase letters, digits, and underscores. Set the values in the skill's Secrets section in the editor; they are encrypted, and at run time each one is an environment variable your script reads with os.environ. An agent's Settings -> Skills can override a value for that agent alone. The values never appear in the skill's files or in the thread.

Attach the skill to an agent

Open the agent, go to Settings -> Skills, select Add a skill, and pick yours. Skills that came with the agent are listed as included; the ones you add are listed separately and can be removed the same way. The agent installs the skill on its computer the first time it needs it, and after you save a change in the editor it picks up the new version the next time it uses the skill.

Test it

  1. Open a thread with the agent and give it a task the description covers, for example "Here is the export from our billing system, what's in it?" with the CSV attached.
  2. Watch the thread. The agent reads the skill, then runs the script; the step shows the skill's title.
  3. Check the result: the summary the agent gives, and the summary.md file in the thread.
  4. If something is off, fix it in the editor and Save. The agent uses the new version on its next run; a persistent computer keeps installed dependencies, so the fix is quick to try.

Try it on each kind of computer your agents use. A skill that works on a Linux computer and fails on Windows almost always does so for one of the reasons in the next section.

Verify

The agent used the skill without being told its name, the step in the thread carries the skill's title, and the file the script saved is in the thread.

Troubleshooting

What you seeWhat it means
The agent never uses the skillThe description does not match how people ask. Rewrite it to say when to use the skill, with the words a request would contain
"Script not found"The instructions name a path that is not in the bundle. Scripts live under scripts/; check the exact file name and case
The skill works on Linux, fails on WindowsA .sh script, a hardcoded path such as /tmp, or bash-only syntax. Make the entry point Python and use pathlib and tempfile
ModuleNotFoundErrorThe script imports a package the computer does not have. Add an ensure(...) step before the import
UnicodeEncodeError on WindowsThe script printed or wrote non-ASCII text without UTF-8. Reconfigure stdout and stderr and pass encoding="utf-8" to open()
The agent says the file was produced, but nothing is in the threadThe script saved it somewhere other than OUTPUT_DIR, or the file is over 20 MB
The run stopped after five minutesScripts have a five-minute limit. Split the work, or write partial results to OUTPUT_DIR as you go
"Skill is not available on this device"The install failed, usually a network problem on the computer. Ask the agent to try again; the error it was given says why
The upload is rejectedSKILL.md is missing from the root of the archive, or a front matter field is invalid: name must be lowercase letters, numbers, and hyphens, and description is required