Instructions and skills

Give an agent standing instructions it reads every turn, and skill packs it loads only when the task calls for them.

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.

Users edit it from the files panel or by asking the agent to. 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

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()

Next

Files and the canvas

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