# Skill

a packaged ability an agent is granted. The same skill is offered to every tenant; what differs is which agents have it, how each is set up, and what it has done.

**Has:** a name · a description · a version · what it needs connected · the settings it declares · a schedule or none. On each agent: that agent's settings, an on switch, a schedule switch and its runs. One grant per agent and skill; deleting the agent, or the skill, takes the grant and its runs.

## The catalogue

- The Hub lists the skills the running worker can actually do, with the description, version, requirements, settings and schedule that code declares.
  - e.g. the registry is unreachable at that moment → the catalogue stays as it was; nothing fails.
- A skill is known by its name; the same name reported again updates that skill rather than making a second one.
- The version shown is the version of the code that was loaded, and each run keeps the version it ran under.
- A requirement or schedule that cannot be read is dropped rather than stored as a guess.
  - e.g. a schedule nobody can read → no schedule switch; the skill runs on demand.
- A skill an agent's worker has no code for is skipped, never pretended to run.

## What it needs connected

- Each skill states which connections it needs, which services satisfy each one, and what it can work without.
- A requirement is needed, optional (it runs, nothing is lost, nobody is told), or needed but degradable (it runs, does less, and says what is lost).
  - e.g. no calendar → meetings are still filed, without calendar matching.
- Where more than one service satisfies a requirement, the screen names them together: "Calendar (ICS link or Google)".
- The Hub is told whether each connection is in place; it never sees the credential itself.
- For each member the screen says whether they can use the skill and what they are missing; a shared connection counts for everyone, a personal one only for its owner.
- For each thing a skill needs, the screen names the command that connects it ([CONN-CONNECT-IN-CHANNEL](https://tonoman.com/docs/connection#conn-connect-in-channel)), and marks what the platform supplies as needing nothing.
- An agent has one Skills & tools tab: its skill copies, each by its keyword with the tools it brings, read only; then the tools it holds ([AGENT-TOOLS-IN-THE-HUB](https://tonoman.com/docs/agent#agent-tools-in-the-hub)). Whether a tool is connected is not said here ([TOOL-CONNECTED-PER-PERSON](https://tonoman.com/docs/agent#tool-connected-per-person)). A copy's own page shows its keyword and, per tool, what it uses. The old Tools, Connections and Skills tabs land on it.
- A skill declares the tools it needs ([TOOL-ACCEPTS-KINDS](https://tonoman.com/docs/agent#tool-accepts-kinds)), and adding it to an agent brings them, with nothing to tick or choose: a skill that lacked one could not run. Removing the skill leaves them, removable ([TOOL-STAYS-AFTER-ITS-SKILL](https://tonoman.com/docs/agent#tool-stays-after-its-skill)). Replaces declaring *kinds* ([SKILL-DECLARES-ITS-NEEDS](https://tonoman.com/docs/skill#skill-declares-its-needs)).
  - e.g. meeting-recap added → Plaud, calendar and transcription appear under it; transcription reads "supplied by Tonoman".
- What is added to an agent is an instance of a skill, under a name that is unique on that agent and is also the word that runs it (`!skill <name>`). The first instance of a skill is named after it, so today's words keep working.
  - e.g. meeting-recap added as `acme-recap` → `!skill acme-recap` runs it; a second `acme-recap` on the same agent is refused.
- One agent may hold several instances of one skill, each with its own settings, schedule, credentials and runs; a run of one never reads another's credentials or settings. Replaces one grant per agent and skill.
- A second copy of a skill that runs on a schedule runs on it like the first, on the agent's one schedule: a second meeting-recap looks at its own Plaud logins and runs what IT has not run — two copies on one login are two runs, as their owner set them up. Tested for which copies each firing runs and from when; a real recording through a second copy waits on a connected dev Plaud login.
- A skill is added by finding it by name in the catalogue, not by ticking a list. A copy the agent had and removed comes back as it was — its settings, logins and history.
- Adding a skill the agent already has makes another copy, its keyword the skill's name with the next number (`meeting-recap-2`). A copy can be renamed on its page; the one named after the skill keeps that name, so the words that run it keep working; a keyword in use, or another skill's name, is refused. Its runs follow a rename.
- A new copy's tool copies are set up like the first copy's — each person's own, or the same shared accounts — until changed ([TOOL-COPY-WITH-SKILL-COPY](https://tonoman.com/docs/agent#tool-copy-with-skill-copy)). The person's own logins are separate: a numbered tool copy reads the logins connected for it.
- A copy's scheduled work starts from when it was added: a second meeting-recap does not treat the recordings made before it existed as new.
- A skill's manifest declares the deterministic steps around its runs — *before*: what there is to do (new recordings, new drops); *after*: checking what the run did — each in a sentence and with the script that does it. The skill's page shows them in order around the run itself, which is a prompt to the agent.
  - e.g. meeting-recap → before: finds recordings not yet recapped; the run; after: waits for the recap to be filed, asks once more, then fails with the reason.
- A skill says where its code lives: the repository and the folder in it, linked from its page. The built-in skills live in the open-source runtime; one Tonoman Cloud declares itself says so.
- Since Oct 6 a binding says which copy of the tool a skill copy uses; what that copy uses is the copy's own setting ([TOOL-COPY-WHOSE-ACCOUNT](https://tonoman.com/docs/agent#tool-copy-whose-account)). What follows holds for the copy. Each tool of an instance is bound to what it uses: one credential, "each person's own", or — for a tool that takes several — a list. Only credentials of a kind the tool accepts may be bound; another is refused with the kinds it takes. The worker is handed, per instance, exactly what each tool uses, and an agent's credentials are what its instances use. Turning a skill on binds its tools to what the agent was already granted, and connecting in the channel binds the new credential where a tool has room, so nothing behaves differently from before bindings. Replaces the agent-wide connection grant.
  - e.g. calendar bound to "Acme Outlook (ICS)" → that calendar and no other; bound to "each person's own" → all of the speaker's calendars.

## Granting it and setting it up

- A skill does nothing until an agent is granted it, and every run belongs to that grant ([RUN-NEEDS-SKILL-ON](https://tonoman.com/docs/run#run-needs-skill-on)).
- Switching a skill off keeps the grant and its settings for when it goes back on.
- The settings form holds exactly the fields the skill declares, and a skill with nothing to configure says so.
- A skill may declare a brain setting: the form offers the tenant's brains, and a brain of another tenant is refused. The skill works in the brain chosen there.
  - e.g. Receipts on Atlas, brain setting → Finances; switched to another brain → the next receipt is filed there.
- An unknown field, a missing required one or a value of the wrong kind is refused with the reason, and nothing is saved.
  - e.g. a required output channel left blank → refused; the agent keeps its old settings.
- Settings can only be saved for a skill the agent has; saving never switches one on.
- Clearing an optional field puts the skill back on its own default.
- Only an owner, an admin or an operator may switch a skill, change its settings or its schedule, or run it; a member sees every control disabled.
- A change reaches the running agent within a second or two; a run already under way finishes on the settings it started with.

## Running on its own

- A skill runs on its own every so often, at set times of day, or not at all; one with no schedule shows no schedule switch.
- Whether a skill can run uses the same words on the agent's Skills list, the skill's page and the Accounts tab: "Ready", "Needs setup" with what is missing, or "Off". Where it is about one person it says that person's; where it sums up, it says who is ready ([SKILL-HEALTH-PER-PERSON](https://tonoman.com/docs/skill#skill-health-per-person)).
  - e.g. Ana connected, Ben not → on Ana's row "Ready", on Ben's "Needs setup: calendar", on the list "Ready for 1 of 2".
- Turning the schedule off stops the timer only: the skill stays on, keeps its settings, and still runs when asked.
  - e.g. the switch is offered for a skill with no schedule → refused.
- Times of day are the tenant's own times, and the screen labels them as tenant time.
- A time that cannot be read is dropped, and settings that leave no readable time mean no schedule at all.
- A time-of-day schedule exists while the agent holds the grant and has somewhere to send the result; changing the times moves it, revoking removes it.
- A scheduled run that comes round while the last is still working is skipped, not queued.
- A schedule paused by hand stays paused; only pauses Tonoman made itself are lifted when their reason goes away.

## What a skill may do

- A skill holds no tenant credentials: it asks Tonoman to transcribe, to think, to file a page in a brain ([BRAIN-SKILL-TARGET](https://tonoman.com/docs/brain#brain-skill-target)), and to read the agent's calendars.
- The thinking a skill asks for runs on the agent's inference login, or on the login of the person the run is for; the skill cannot choose whose login pays.
- A skill reports what it did and hands back what should be said; the agent says it in its own words in its own channel.
- What a skill hands back as a source's own figures — how many are left, when it ends, the link — it can mark to be said exactly as written: Tonoman posts those words as they are, to the person the run is for, and the agent does not put them in its own. A number reworded is a number that can come out wrong.
- A skill can ask Tonoman to file one page it wrote, at a path it names, into the brain the run is pointed at ([BRAIN-SKILL-TARGET](https://tonoman.com/docs/brain#brain-skill-target)). The path stays inside that brain; a run with no brain to file into is told so, and nothing is written.
- A skill that has nothing to do with recordings runs on an agent that has no recording flow set up. What such a skill is handed of the tenant's context is what there is, and the rest is simply absent.
  - e.g. nothing to report → nothing is said.
- A skill cannot start another skill's run.
- A run is handed the tenant's mission, where things are filed, the words to spell, the timezone, who it is for and the agent's settings.

## The skill's page

- The agent's Skills tab ticks what that agent runs and leads into each skill's own page.
- One page per skill: whether it is on, when it runs, its settings, what it needs and how that stands, who can use it, and what it has done ([RUN-HISTORY-PER-SKILL](https://tonoman.com/docs/run#run-history-per-skill)).
- A switch on that page saves the moment it is flipped and says so.