Skip to main content
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:

​
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
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 for the full walkthrough.

​
Template

Copy and customize this SKILL.md for your use case: 
# 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: 
## 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`.
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.