Skills overview

What are skills?

A skill is a playbook for one type of IT problem. It says when it applies, which checks and fixes to run, which tools it may use, and how to handle edge cases. Skills are written in plain language: the skill supplies the expertise, and Assist works out how to apply it to the problem on this machine.

Built-in skills

Assist ships with built-in skills for common problems, such as disk cleanup, VPN repair, printer repair, and password and MFA resets. idemeum maintains them, and every built-in skill and tool is published in our open skill library, so you can read exactly what Assist will do before you turn a skill on. Turn any skill on or off in Agents → Skills, or write your own using the format below.

Skill and tool library

Browse every built-in skill and tool on GitHub.

How a skill is selected

Assist matches the employee’s request against each skill’s description and example phrases. “My laptop is crawling” matches process-manager, and “I keep getting asked for my email password” matches email-repair. No keywords or menus are needed. Skills with a pill also appear as quick actions in the app. If nothing matches, Assist asks a clarifying question, and the employee can always raise the issue with IT through the triage skill.

Anatomy of a skill

A skill is one SKILL.md file with two parts: the frontmatter and the body.

---
<frontmatter>   ← settings, in YAML
---

<body>          ← the playbook, in Markdown

Frontmatter

---
name: skill-name
description: Diagnoses and fixes <problem>. Use when the user reports <symptom>.
allowed-tools:
  - tool_one
  - tool_two
metadata:
  prerequisites:
    before-corrective:
      - tool_one
  maxAggregateRisk: medium
  userLabel: "Short label for this skill"
  examples:
    - "user's phrasing 1"
    - "user's phrasing 2"
  pill:
    label: Fix X
    goal: My X is broken, please diagnose and fix it
    icon: HardDrive
    iconClass: text-blue-500
    order: 10
---

Field	Description
`name`	The skill’s name. Must match its folder name exactly.
`description`	What the skill fixes and when to use it. Used to pick the right skill.
`allowed-tools`	Every tool the skill may use. Assist refuses to call anything else.
`metadata.prerequisites.before-corrective`	Read-only tools that must run before any tool that makes a change.
`metadata.maxAggregateRisk`	`low`, `medium` or `high`. Set it to the risk level of your riskiest tool.
`metadata.userLabel`	Short label shown when Assist asks the employee to choose between skills.
`metadata.examples`	Ways an employee might describe the problem. Used with `description` to pick the skill.
`metadata.pill`	Adds a quick action button to the app, with its label, icon and position.

Skill body

## When to use

When this skill is right, and when it isn't (name the skill to use instead).

## Steps

**Step 1 — Short name**
What to do, with conditions and notes.

**Step 2 — Next step**
...

## Edge cases

Unusual situations and how to handle them.

Write steps as bold text, **Step N — Name**, not as headings such as ### Step N. Some parts of the system strip Markdown headings.

Writing a step

Each step usually calls one tool. A step can say:

What to write	Example
The tool to call	Call `check_connectivity` to test internet access.
Parameters	Call `check_connectivity` with `targets: ["8.8.8.8", "google.com"]` and `count: 3`.
When to run it	Only run when Step 1 found every target unreachable.
How to read the output	Note: `proxies[]` can have several entries; check each one.
Repeat over a list	For each app the employee approved in Step 4, call `clear_app_cache`.
Values from earlier steps	Call `get_disk_usage` with `volume` set to the mount path from Step 1.
Sensitive data	Treat `password` as sensitive; never log or repeat it.
Always run the step	Add (MUST include) after the step name.

Conditions must refer to what an earlier tool returned, not to the employee’s identity, mood or intent.

Complete skill example

---
name: dns-flush
description: Diagnoses and fixes DNS resolution failures when websites won't load but IP-level connectivity is working.
allowed-tools:
  - check_connectivity
  - check_vpn_status
  - flush_dns_cache
metadata:
  prerequisites:
    before-corrective:
      - check_connectivity
      - check_vpn_status
  maxAggregateRisk: medium
  userLabel: "DNS resolution failure"
  examples:
    - "websites won't load but my internet is on"
    - "I'm getting DNS_PROBE errors"
    - "names don't resolve but ping works"
    - "Chrome says server not found"
    - "DNS isn't working"
  pill:
    label: Fix DNS
    goal: Websites won't load, please diagnose and fix the DNS issue
    icon: Globe
    iconClass: text-blue-500
    order: 12
---

## When to use

Websites won't load but IP-level connectivity is intact (the user can ping IPs but not hostnames). Do NOT use for full connectivity outages — use `network-reset` instead.

## Steps

**Step 1 — Confirm DNS is the problem**

Call `check_connectivity` with `targets: ["8.8.8.8", "1.1.1.1", "google.com", "example.com"]` and `count: 3`.

Note: if numeric IPs are reachable but hostnames aren't, the issue is DNS. If nothing is reachable, this skill is the wrong tool — switch to `network-reset`.

**Step 2 — Rule out VPN-routed DNS** (MUST include)

Call `check_vpn_status`. A connected VPN routes DNS through its tunnel and can produce DNS-failure symptoms. If a VPN is connected, advise disconnecting and retesting before proceeding.

**Step 3 — Flush the DNS cache**

Call `flush_dns_cache`. Consider this before any heavier fix (like network reset) because flushing is non-destructive and instantly reversible.

Only run when Step 1 showed numeric IPs reachable AND hostnames unreachable, AND Step 2 showed no active VPN.

**Step 4 — Verify the fix**

Call `check_connectivity` with the same hostname targets as Step 1. Only run after Step 3. Success means DNS is working; remaining failures mean the upstream DNS server (router or ISP) is at fault.

## Edge cases

- **VPN active** — Step 2 catches this; advise disconnect-and-retest.
- **Hardcoded DNS server** — if the user set a manual DNS server that's now broken, flushing won't help. Suggest reverting to automatic DNS.
- **macOS mDNSResponder hung** — the flush briefly drops all DNS for 1–2 seconds. Normal.

AI agents overview

Assist

Automate

Operate

Skills

Tools

Runs

What are skills?

Built-in skills

Skill and tool library

How a skill is selected

Anatomy of a skill

Frontmatter

Skill body

Writing a step

Complete skill example

​What are skills?

​Built-in skills

Skill and tool library

​How a skill is selected

​Anatomy of a skill

​Frontmatter

​Skill body

​Writing a step

​Complete skill example

What are skills?

Built-in skills

How a skill is selected

Anatomy of a skill

Frontmatter

Skill body

Writing a step

Complete skill example