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:
- 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.
- 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. - 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. - Files the script saves to the output folder reach the person. A script writes finished files to the directory named by the
OUTPUT_DIRenvironment 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
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.
---
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
---| Field | Required | Rules |
|---|---|---|
name | Yes | The skill's identifier: lowercase letters, numbers, and hyphens, up to 40 characters. Changing it renames the skill; it must be unique in your organization |
description | Yes | What 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 |
title | No | A short label, up to 60 characters, shown in the thread while the skill runs, for example "Summarizing a CSV file" |
version | No | A version such as 1.0.0. Bump it when you change the skill |
category | No | A label, up to 60 characters, used to group skills in the library |
license, author | No | Free text |
secrets | No | The 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.
- Write entry scripts in Python, never as shell scripts. A
.pyscript runs with Python on every computer. Anything else runs withbash, which a Windows computer does not have, so a.shentry point fails there. Shell out to other tools from Python withsubprocesswhen you need them. - Never hardcode the skill's location. It differs on every computer. Resolve paths from the script itself:
SKILL_DIR = Path(__file__).resolve().parent.parent. - 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. - 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.
- 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 reconfiguresys.stdoutandsys.stderrat the top of the script. - Branch on the operating system, and build paths portably. Use
platform.system()to branch,shutil.which()to find a program (it handles.exeon Windows),pathlibfor paths,tempfile.gettempdir()instead of/tmp, andos.pathsepinstead of:.apt-getandsudoexist only on the temporary computer; on the dedicated computers and the Mac, install at the user level (pip,npminto a local folder, Homebrew where present, winget on Windows). - Write
python3in commands and documentation. The runtime picks the right interpreter for a.pyscript on each computer; your instructions should namepython3. - 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:
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
| Computer | Always 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:
---
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:
#!/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.mdmust be at the root of the archive or in a single top-level folder; onlySKILL.md,scripts/,references/, andassets/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:
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: falseNames 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
- 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.
- Watch the thread. The agent reads the skill, then runs the script; the step shows the skill's title.
- Check the result: the summary the agent gives, and the
summary.mdfile in the thread. - 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 see | What it means |
|---|---|
| The agent never uses the skill | The 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 Windows | A .sh script, a hardcoded path such as /tmp, or bash-only syntax. Make the entry point Python and use pathlib and tempfile |
ModuleNotFoundError | The script imports a package the computer does not have. Add an ensure(...) step before the import |
UnicodeEncodeError on Windows | The 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 thread | The script saved it somewhere other than OUTPUT_DIR, or the file is over 20 MB |
| The run stopped after five minutes | Scripts 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 rejected | SKILL.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 |