Wilma

Access Finland's Wilma school system from AI agents. Fetch schedules, homework, exams, grades, messages, and news via the wilma CLI. Start with `wilma summar...

Security Scan

The skill is coherent with its stated purpose (wrapping a Wilma CLI) and asks for the expected local CLI binary/config; it does store and use sensitive Wilma session/TOTP data so review and trust of the npm package and local config are recommended.

Purpose & Capability

Name/description match the requested binaries and install: the skill requires the 'wilma' CLI (provided by npm package @wilm-ai/wilma-cli) and relies on a local Wilma config containing session credentials. These requirements are appropriate for a Wilma integration. Note: registry metadata at the top of the report lists no required config paths, but the SKILL.md declares ~/.config/wilmai/config.json as required — this is an inconsistency in metadata but not a functional mismatch with the skill's purpose.

Instruction Scope

The SKILL.md instructs the agent to run the wilma/wilmai CLI in non-interactive mode and to prefer --json output. It also documents use of a local config file and optional --totp-secret (TOTP secret) on the command line and recommends saving the TOTP secret in the local config via interactive setup. These instructions remain within scope for reading Wilma data, but they imply the agent (via the CLI) will access stored session credentials/TOTP secrets — a sensitive capability that users should be aware of. The SKILL.md does not instruct the agent to read arbitrary system files beyond the Wilma config or to transmit data to unexpected endpoints.

Install Mechanism

Install is an npm global package (@wilm-ai/wilma-cli) which produces the declared 'wilma' binary. This is proportionate for a CLI wrapper. Installing from npm is a moderate-risk action (code executed from registry); user should verify the package and its source (SKILL.md links a GitHub repo and wilm.ai site). The included wrapper script is straightforward and not malicious.

Credentials

The skill declares no environment variables and no remote credentials, which is consistent. However, the workflow requires a local config (~/.config/wilmai/config.json) that stores session credentials and possibly a saved TOTP secret; those are sensitive. The SKILL.md also suggests passing a TOTP secret on the command line (one-off), which exposes the secret to process lists and shell history — a security caveat but within the expected needs of MFA support.

Persistence & Privilege

The skill does not request always:true and is user-invocable only. It does not modify other skills or claim system-wide configuration changes. Its install writes a CLI binary (via npm) which is normal for a CLI integration.

Assessment

This skill is coherent: it wraps a Wilma CLI and expects a local Wilma config that stores session tokens/TOTP secrets. Before installing: (1) verify the npm package and linked GitHub repo (ensure @wilm-ai/wilma-cli is the legitimate project), (2) be aware the CLI stores session credentials and (optionally) TOTP secrets in ~/.config/wilmai/config.json — inspect that file and its permissions, (3) avoid passing TOTP secrets on the command line when possible (use interactive save or other secure storage) because command-line arguments can be exposed in process listings and shell history, (4) note the small metadata inconsistency about required config paths in the registry vs SKILL.md and confirm the agent/runtime will allow use of the local config, and (5) if you need stronger isolation, test the npm package in a sandbox before granting the agent access to real student accounts.

Wilma Skill

Overview

Wilma is the Finnish school information system used by schools and municipalities to share messages, news, exams, schedules, homework, and other student-related updates with parents/guardians.

Use the wilma / wilmai CLI in non-interactive mode to retrieve Wilma data for AI agents. Prefer --json outputs and avoid interactive prompts.

Quick start

Install

npm i -g @wilm-ai/wilma-cli

1. Ensure the user has run the interactive CLI once to create ~/.config/wilmai/config.json.
2. Use non-interactive commands with --json.

Core tasks

Daily briefing (start here)

wilma summary --student <id|name> --json
wilma summary --all-students --json

Returns today's and tomorrow's schedule, upcoming exams, recent homework, recent news, and recent messages in one call. This is the best starting point for any parent-facing summary.

Schedule

wilma schedule list --when today --student <id|name> --json
wilma schedule list --when tomorrow --student <id|name> --json
wilma schedule list --when week --student <id|name> --json
wilma schedule list --date 2026-03-10 --student <id|name> --json
wilma schedule list --weekday thu --student <id|name> --json

--weekday also accepts Finnish short forms: ma, ti, ke, to, pe, la, su. Use --date or --weekday, not both.

Homework

wilma homework list --student <id|name> --json

Upcoming exams

wilma exams list --student <id|name> --json

Exam grades

wilma grades list --student <id|name> --json

List students

wilma kids list --json

News and messages

wilma news list --student <id|name> --json
wilma news read <id> --student <id|name> --json
wilma messages list --student <id|name> --folder inbox --json
wilma messages read <id> --student <id|name> --json

Fetch data for all students

All list commands support --all-students:

wilma summary --all-students --json
wilma homework list --all-students --json
wilma exams list --all-students --json

You can also pass a name fragment for --student (fuzzy match).

MFA (Multi-Factor Authentication)

If the Wilma account has MFA/TOTP enabled:

Interactive setup (recommended): Run wilma interactively. When MFA is detected, choose "Save TOTP secret for automatic login" and paste your TOTP secret or otpauth:// URI. Future logins will auto-authenticate.

Non-interactive (one-off): Pass the TOTP secret directly:

wilma schedule list --totp-secret <base32-key> --student "Stella" --json
wilma schedule list --totp-secret 'otpauth://totp/...' --student "Stella" --json

If the TOTP secret has been saved via interactive setup, --totp-secret is not needed — the CLI auto-authenticates from the stored config.

Notes

• If no --student is provided, the CLI uses the last selected student from ~/.config/wilmai/config.json (or $XDG_CONFIG_HOME/wilmai/config.json).
• If multiple students exist and no default is set, the CLI will print a helpful error with the list of students.
• When the account has multiple students, --student is required for read commands.
• If auth expires or the CLI says no saved profile, re-run wilma interactively or use wilma config clear to reset.
• Run wilma update to update the CLI to the latest version.

Actionability guidance (for parents)

Wilma contains a mix of urgent items and general info. When summarizing for parents, prioritize actionable items:

Include items that:

• Require action or preparation (forms, replies, permissions, materials to bring).
• Announce a deadline or time-specific requirement.
• Describe a schedule deviation or noteworthy event (trips, themed days, school closures, exams).
• Mention homework, exams, or upcoming deadlines.

De-prioritize items that:

• Are purely informational with no action, deadline, or schedule impact.
• Are generic announcements unrelated to the target period.

When in doubt, include and let the parent decide. Prefer a short, structured summary with dates and IDs.

Scripts

Use scripts/wilma-cli.sh for a stable wrapper around the CLI.

Links

• GitHub: https://github.com/aikarjal/wilmai
• Website: https://wilm.ai