SKILL.md

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

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

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

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