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

# SKILL.md (Agent Skills)

> Progressive disclosure skills — name + description first, full booklet only when asked.

# SKILL.md

## In plain terms

A **skill** is a how-to booklet for one job ("export a PDF", "file an expense").

If you dump every booklet into the prompt, the model gets stuffed and slow. So Agentium does this:

1. Show a **tiny index**: name + one-line description.
2. If the agent needs the booklet, it calls `get_skill_instructions`.
3. Extra files (examples, scripts) are read with `get_skill_reference`.

That pattern is called **progressive disclosure**. It matches the [Agent Skills](https://agentskills.io) idea.

***

## Folder layout

```
skills/
  pdf-export/
    SKILL.md
    references/
      paper-sizes.md
```

`SKILL.md`:

```md theme={null}
---
name: pdf-export
description: Turn a web page or markdown file into a PDF
---

# PDF export

1. Prefer A4.
2. Embed fonts.
3. Don't invent a file path — ask the user.
```

Rules:

* `name` is lowercase kebab-case (`pdf-export`), max 64 chars
* `description` max 1024 chars
* YAML frontmatter is required for discovery

***

## Wire it up

```typescript theme={null}
const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  skillDirs: ["./skills"],
});
```

`Agent.deep()` already sets `skillDirs: ["./skills"]`.

Tools the model gets:

| Tool                     | Does                                                              |
| ------------------------ | ----------------------------------------------------------------- |
| `list_skills`            | Name + description for every skill                                |
| `get_skill_instructions` | Full `SKILL.md` body                                              |
| `get_skill_reference`    | A file inside that skill folder (`references/…`). `..` is blocked |

***

## Two skill systems

|             | `skillDirs` + `SKILL.md` | `skills: [...]` (`skill.json`)  |
| ----------- | ------------------------ | ------------------------------- |
| What        | Markdown booklets        | Packaged tools + instructions   |
| Prompt cost | Tiny until loaded        | All instructions injected       |
| Use         | Playbooks, checklists    | Shipping real `defineTool` code |

You can use both on one agent.