> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cycls.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```markdown AGENT.md theme={null}
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:

```python theme={null}
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
```

```markdown SKILL.md theme={null}
---
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

```python theme={null}
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.

```python theme={null}
llm = cycls.LLM().skills(None)   # turn the whole mechanism off
```

<Tip>
  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".
</Tip>

## 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

<Card title="Files and the canvas" icon="folder-open" href="/agents/files">
  The workspace file tree, and how the canvas renders it.
</Card>