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

# Skills and subagents

> Teach a workspace how you want recurring work done, with skills, subagents, and project instructions that every run picks up.

Prompting the same background into every run gets old, and it drifts. Put it in the workspace instead: agents load these files themselves, so any run in that workspace - from the API, the product, the CLI, or MCP - starts with the same instructions.

| File                       | What it does                                               |
| -------------------------- | ---------------------------------------------------------- |
| `CLAUDE.md` or `AGENTS.md` | Project instructions loaded on every run in the workspace. |
| `.skills/<name>/SKILL.md`  | A named skill the agent loads when the work matches it.    |
| `.agents/<name>.md`        | A subagent the main agent can delegate a task to.          |

They are ordinary workspace files, so you create them the same way you create anything else - upload, write through the API, or let an agent write them.

## Project instructions

`CLAUDE.md` (or `AGENTS.md`) at the workspace root is read on every run. Keep it short and durable: conventions, where things live, what never to touch.

```bash theme={null}
curl -sS -X PUT "$ARG_API/api/workspaces/$WS/files/content?path=/CLAUDE.md" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{"content": "# Working in this workspace\n\n- Raw exports land in /inbox and are never edited in place.\n- Cleaned data goes to /data as CSV with a header row.\n- Reports are .mdx files in /reports, one per month.\n"}'
```

## Skills

A skill is a folder under `.skills/` with a `SKILL.md` inside. The frontmatter is what the agent sees when deciding whether the skill applies, so write the `description` as "when to use this", not as a title.

```markdown theme={null}
---
name: monthly-report
description: Build the monthly revenue report from /data exports. Use whenever someone asks for a month's numbers or a revenue rollup.
---

# Monthly report

1. Read every CSV in `/data` for the requested month.
2. Total revenue by region, then by product line.
3. Write `/reports/<year>-<month>.mdx` with a summary table and a short
   commentary on anything that moved more than 10% month over month.
4. Leave the source CSVs untouched.
```

Write it to `.skills/monthly-report/SKILL.md`:

```bash theme={null}
curl -sS -X PUT "$ARG_API/api/workspaces/$WS/files/content?path=/.skills/monthly-report/SKILL.md" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  --data-binary @skill.json
```

A workspace loads up to 50 skills. Only the name and description sit in the agent's context; the body is loaded when the skill is actually used, so a long skill costs nothing until it applies.

## Subagents

A subagent is a markdown file under `.agents/`. The main agent delegates a self-contained task to it, and the subagent works in its own context - useful for work that would otherwise flood the main conversation, like reading fifty files to answer one question.

```markdown theme={null}
---
name: data-auditor
description: Check a CSV for structural problems before it is used in a report.
model: anthropic/claude-haiku-4.5
tools: read_file, grep, list_files
---

You audit CSV files. Report missing headers, inconsistent column counts,
duplicate ids, and impossible values. Never modify the file - report only.
```

| Frontmatter   | Meaning                                                           |
| ------------- | ----------------------------------------------------------------- |
| `name`        | How the main agent refers to it. Required.                        |
| `description` | When to delegate to it. Required.                                 |
| `model`       | Model override. Omit to inherit the run's model.                  |
| `tools`       | Comma-separated allowlist. Omit to inherit the full tool surface. |

A workspace loads up to 50 subagents.

## Seeing what a workspace offers

```bash theme={null}
curl -sS "$ARG_API/api/workspaces/$WS/skills-and-agents" \
  -H "X-API-Key: $ARG_API_KEY"
```

This returns the skills and subagents a run in this workspace would pick up, which is the fastest way to confirm a new file parsed correctly. A skill or subagent whose frontmatter is missing `name` or `description` is skipped silently, so check here after adding one.

## Turning them off for a single run

Skills and subagents apply automatically. To exclude one from a specific run without deleting it:

```json theme={null}
{
  "message": "Just read the file and tell me what is in it.",
  "workspace_id": "…",
  "disabled_skills": ["monthly-report"],
  "disabled_agents": ["data-auditor"]
}
```

## Related

* [Agent runs](/guides/agents/runs) - the run options these fields belong to
* [Unattended runs](/guides/agents/unattended) - where durable instructions pay off most
* [Files](/guides/files) - writing these files through the API