> ## Documentation Index
> Fetch the complete documentation index at: https://upsonic-tech-1636.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SKILL.md

> A ready-to-use SKILL.md template for adding a workspace skill your autonomous agent discovers and runs

A `SKILL.md` file defines a **skill** — a self-contained capability that lives as a folder inside your agent's workspace. It tells the agent **when** the skill applies, **how** to run it, and **what it must never do**. Drop the folder into `workspace/skills/`, point to it from `AGENTS.md`, and the agent discovers and runs it on its own — no code changes.

## Where to Use

You can use `SKILL.md` with:

* [**AutonomousAgent**](/concepts/autonomous-agent/skills) — comes with workspace, filesystem, and shell tools built in
* [**Agent** with workspace](/concepts/agents/advanced/workspace) — set the `workspace` parameter on your Agent

## How It Works

A skill is just a directory under `workspace/skills/`. Each one owns a `SKILL.md` plus the scripts, templates, and assets it needs:

```
workspace/
├── AGENTS.md                    # agent behavior + skill index (routing)
├── data/                        # source data the skills operate on
├── reports/                     # outputs
└── skills/
    └── excel_report/
        ├── SKILL.md             # ← when & how to use this skill
        ├── generate.py          # the real generator (the agent calls this)
        ├── templates/
        │   └── onboarding.json  # branding: colors, logo, columns
        └── assets/
            └── upsonic_logo.png
```

1. Create a folder named after your skill inside `workspace/skills/`
2. Add a `SKILL.md` with **When to Use**, **Usage**, and **Important** sections
3. Optionally add scripts, `templates/`, and `assets/`
4. Register the skill in `AGENTS.md` so the agent knows when to reach for it

```python theme={null}
from upsonic import AutonomousAgent, Task

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace="/path/to/workspace"  # <- skills/ and AGENTS.md live here
)

# The agent reads AGENTS.md, routes to the skill, reads its SKILL.md, and runs it
agent.print_do(Task("Generate the onboarding report for the last 2 weeks"))
```

The agent never imports the skill. It **discovers** it at runtime by reading files: `AGENTS.md` routes the request, then the agent opens the matching `SKILL.md` only when a task needs it (progressive disclosure). See [Skills](/concepts/autonomous-agent/skills) for the full walkthrough.

## Template

Copy and customize this `SKILL.md` for your use case:

````markdown theme={null}
# Skill: Excel Report Generator

Generate branded, formatted Excel reports from CSV data using predefined templates.

## When to Use

Trigger this skill when the user asks for:
- Reports (onboarding, weekly, monthly, etc.)
- Excel/spreadsheet generation
- Data exports with formatting

## How It Works

1. **Find the data** — look in `data/` for the relevant CSV file
2. **Pick the template** — match the request to a template in `skills/excel_report/templates/`
3. **Run the generator** — execute `generate.py` with the right arguments
4. **Return the result** — tell the user where the report was saved

## Usage

```bash
python skills/excel_report/generate.py \
  --data data/onboarding.csv \
  --template skills/excel_report/templates/onboarding.json \
  --output reports/<filename>.xlsx
```

### Arguments

| Argument     | Required | Description                                  |
|--------------|----------|----------------------------------------------|
| `--data`     | Yes      | Path to the source CSV file                  |
| `--template` | Yes      | Path to the template JSON config             |
| `--output`   | Yes      | Where to save the generated `.xlsx`          |
| `--filter`   | No       | Date filter, e.g. `--filter "last_2_weeks"`  |
| `--date-col` | No       | Column to apply the date filter on           |

### Date Filters

- `last_2_weeks` — rows from the last 14 days
- `last_month` — rows from the last 30 days
- `this_month` — rows from the current calendar month
- `YYYY-MM-DD:YYYY-MM-DD` — explicit date range

## Naming Convention for Output

Use: `reports/{template_name}_{YYYY-MM-DD}.xlsx`

Example: `reports/onboarding_2026-05-11.xlsx`

## Important

- **Never write Excel manually.** Always use `generate.py` with a template.
- The generator handles all formatting, branding, and data type conversions.
- If a new report type is needed, create a new template JSON — don't modify `generate.py`.
````

## Register the Skill in AGENTS.md

Add the skill to your `AGENTS.md` so the agent knows it exists and when to use it:

```markdown theme={null}
## Skills

Skills live in `skills/`. Each skill has its own folder with a `SKILL.md`.
Read the relevant one before starting a task — skills can be combined.

**Available skills:**

- **excel_report** — Generate branded Excel reports from CSV data. Use when the
  user asks for reports, exports, spreadsheets, or "last 2 weeks' report".

### Routing Rules

| User says...                            | Skill to use |
|-----------------------------------------|--------------|
| "create report", "report", "export"     | excel_report |
| "onboarding status", "last 2 weeks"     | excel_report |
| "excel", "spreadsheet", "table"         | excel_report |

**Important:** Never write Excel files by hand. Always delegate to the skill's `generate.py`.
```

<Tip>
  Keep formatting decisions in scripts and templates — never in the agent's head. The agent's job is to *choose* and *orchestrate* the skill, not to reinvent its output. This is what keeps results reproducible across runs.
</Tip>