# 3. Add the skills

The MCP tools say **what** can be done. The skills say **how to do it correctly** — and when not to do it at all.

## What the skills are

A tree of Markdown files the agent reads before it calls a tool:

```text
skills/
├─ SKILL.md                 root router: picks the country, then the area; how to talk to the user,
│                           personal-data rules, integration context
└─ fi/                      Finland — one folder per country, like the MCP servers
   ├─ payroll-process/      the whole flow — statuses, what happens next (no tool)
   ├─ calculations/         building a calculation: the wage-type catalogue, one file per row type
   │  └─ references/
   │     ├─ wage-types/     monthlySalary.md, overtime.md, carBenefit.md, …
   │     ├─ scope-and-eligibility.md   when NOT to calculate
   │     └─ yearly-changing-numbers/   rates and limits by year
   └─ employments/  payrolls/  invoices/  reports/  settings/  absences/  holidays/
```

The agent reads the root, picks the **country** — Finland is the only one today, and a request for another country is refused — then follows **one route** to an area (`/skills:fi:<area>`), and opens a reference file only when the area's `SKILL.md` tells it to under a named condition. That keeps the always-read part small: building a single row typically costs about a third of what reading the whole catalogue would.

Four things the skills carry that a model does not know by itself:

- **The wage-type catalogue** — which row type fits a situation, its aliases in everyday Finnish, and the fields it needs.
- **Refusals** — a large part of the content answers *should this calculation be made at all?* A sole proprietor paying themselves, volunteer work, international situations and public employers are out of scope, and the right answer is to say so.
- **Guardrails** — never invent an amount, never guess a wage type, never invent an income-type code or an identifier, money is EUR. These live **in the skills**, so they hold even when a partner's agent loads the skills without Salaxy's agent instructions.
- **Personal-data rules** — payroll data belongs to the employer and the employee, and some rows reveal health or union membership just by existing: the agent never writes the nature of an illness into a reply, never repeats a personal identity code in prose, and leaves the decision that pay is paid to a person.

The skill content is in **Finnish for now** — it started in the domain language of Finnish payroll — and is **moving to English**. Identifiers, field names and enum values are already English, as in the API. The agent answers in the user's own language.

## Ways to get the skills

| Way | Status |
|---|---|
| **The file tree** from the skills repository — give your agent file-read access and start at `skills/SKILL.md` | Today — below |
| **A packaged plugin** for Claude clients | In preparation |
| **Served by the MCP server itself**, as MCP resources the agent reads first — no separate install, and the skills always match the server | Proposed |
| **OpenSharing**, as shared agent skills | Possible later |

## Use them

The skills are a plain file tree today. Your agent needs **file-read access** to it and an instruction to start at `skills/SKILL.md`.

### Claude Code

```sh
git clone https://github.com/salaxy-payroll/salaxy-ai-for-payroll
cd salaxy-ai-for-payroll
claude mcp add --transport http salaxy-payroll-demo https://demo-payroll.salaxy.com/mcp
# then in Claude Code: /mcp → salaxy-payroll-demo → Authenticate

# The reference agent is in Claude Code subagent format:
mkdir -p .claude/agents && cp agents/payroll-agent.md .claude/agents/
claude
```

Then: *"Use the payroll-agent: pay Erkki a car benefit for September 2026 — it's a 2023 car, and we pay the fuel."*

**Repository access:**
The skills repository opens publicly soon. Until then, cloning needs access — ask your Salaxy contact.

### Your own agent

Load `agents/payroll-agent.md` as the system prompt (or write your own — see the next step), give the model a file-read tool rooted at the repository, and connect the MCP server. That is exactly how the [evals](https://code.salaxy.com/reference/verified.md) run.

## What each area covers

| Skill area | Status | MCP tools | Eval cases |
|---|---|---|---|
| Payroll process | Knowledge only | — | 2 / 2 pass |
| Calculations | Live | `calculation_preview`, `calculation_create`, `calculation_set_rows`, `calculation_update`, `calculation_get_summary`, `calculation_show_slip`, `calculation_copy`, `calculation_search`, `row_type_list` | 35 / 37 pass |
| Employments | Live | `employment_search`, `employment_get_summary`, `employment_create`, `employment_update`, `employment_set_rows` | 3 / 3 pass |
| Payrolls | Live | `payroll_create`, `payroll_copy`, `payroll_set_employments`, `payroll_set_rows`, `payroll_update`, `payroll_remove_calculation`, `payroll_get_summary`, `payroll_show_slips`, `payroll_search` | 1 / 1 pass |
| Invoices | Live | `invoice_search`, `invoice_get_summary`, `invoice_preview`, `invoice_confirm` | 1 / 1 pass |
| Reports | Live | `salary_slip`, `salary_slip_pdf`, `summary_report`, `salary_summary`, `accounting_report`, `holiday_pay_debt`, `ir_reports`, `ir_report` | 0 / 2 pass |
| Company settings | Coming soon | — | 0 / 1 pass |
| Absences | Live | `absence_search`, `absence_get_summary`, `absence_set_periods` | 1 / 1 pass |
| Holidays | Live | `holiday_spec_get_summary`, `holiday_spec_update`, `holiday_year_create`, `holiday_year_search`, `holiday_year_get_summary`, `holiday_year_set_accruals`, `holiday_year_set_leaves`, `holiday_year_update`, `holiday_year_recalculate` | 1 / 1 pass |

Areas marked *In development* or *Coming soon* are written ahead of their public tools. On a server that lacks a tool the agent says it cannot do that *here*, names what should happen, and does not substitute another tool. It does not claim the action is impossible: the limit may be the environment's, not Salaxy's.

[Next: build your own agent →](https://code.salaxy.com/get-started/agentic/build-your-agent.md)
