Instructions and skills

Two mechanisms sit between your system prompt and the model. Instructions are always in context. Skills are loaded on demand.

Workspace instructions

Every turn, the loop reads AGENT.md from the user’s workspace root and appends it to the system prompt, fenced as user preferences that stay subordinate to your .system() prompt.

AGENT.md

Always answer in Arabic unless I write in English.
Our fiscal year starts in April.
When I ask for a report, use the template in templates/report.md.

In the web client, users open Instructions from the dock at the bottom of the right panel. The file opens in the canvas editor, and an empty one shows a few examples to start from. AGENT.md does not appear in the Files list. Users can also ask the agent to change it. Nothing is needed on your side, but the file name is configurable:

llm = cycls.LLM().instructions("NOTES.md")   # a different name
llm = cycls.LLM().instructions(None)         # disable the mechanism

The Instructions tile always opens AGENT.md, so keep the default name if your users edit their instructions in the web client. Content is capped at 24KB and truncated beyond that. Binary or unreadable files are ignored.

Skills

A skill is a folder of instructions the model pulls in when it decides the task calls for it. Only the name and description sit in the system prompt, which costs a line or two. The body enters context when the model calls the skill tool.

skills/
  pdf-reports/
    SKILL.md
    scripts/render.py
    templates/invoice.html

SKILL.md

---
name: pdf-reports
description: Generate branded PDF reports from CSV data. Use when the user asks for a PDF report, an invoice, or a printable summary.
---

# PDF reports

Run `python /skills/pdf-reports/scripts/render.py <csv> <out.pdf>`.
The template lives beside the script and expects columns: date, item, amount.

The frontmatter does the work. name is lowercase with hyphens and falls back to the folder name. description is what the model matches against, so write it as “what this does, and when to use it” in at most 1KB. The body can be up to 48KB.

Shipping skills with the agent

image = cycls.Image().copy("skills/")
llm = cycls.LLM().skills("skills")

Shipped skills are read-only and mount at /skills/<name>/ inside the bash sandbox, so scripts find their own templates by absolute path. They version with your deploys.

Skills users create

Any skills/<name>/SKILL.md in a user’s workspace joins the catalog automatically, rescanned about every thirty seconds. A user skill wins a name collision with a shipped one, so someone can override your default without a redeploy.

llm = cycls.LLM().skills(None)   # turn the whole mechanism off

The description decides whether the model reaches for the skill, so write the trigger rather than the summary. “Use when the user asks for a PDF report, an invoice, or a printable summary” works better than “PDF utilities”.

Which to use

Situation	Use
A preference that applies to every turn	`AGENT.md`
A procedure with support files, needed occasionally	a skill
Product behavior you own and never want overridden	`.system()`

Files and the canvas

The workspace file tree, and how the canvas renders it.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Instructions and skills

Workspace instructions

Skills

Shipping skills with the agent

Skills users create

Which to use

Next

Files and the canvas

​Workspace instructions

​Skills

​Shipping skills with the agent

​Skills users create

​Which to use

​Next

Files and the canvas

Workspace instructions

Skills

Shipping skills with the agent

Skills users create

Which to use

Next