What are skills?

A skill is a playbook for one type of IT problem. It defines when it applies, the diagnostic and corrective steps to take, the tools it may use, and how to handle edge cases. Skills are written in natural language and interpreted by the agent’s planner: the skill provides the expertise, and the agent reasons about how to apply it to the specific situation on the specific machine. Skills and tools are different things. A skill is the playbook (what to do and when); a tool is a deterministic, code-reviewed function that performs one action (what actually touches the device). Skills reference tools; every skill declares the fixed list of tools it is allowed to use, and the guardrails enforce that list on every run.

How a skill is selected

When an employee describes a problem, the agent matches the request against each skill’s description and example phrasings. “My laptop is crawling” matches the performance skill; “I keep getting asked for my email password” matches email repair. No keywords or menus are involved, and each skill also appears as a quick action in the app for one-click starts. If nothing matches, the triage skill takes over, so no request goes unhandled.

Anatomy of a skill

Every skill has two parts - frontmatter and body.

---
<frontmatter — settings>   ← YAML configuration
---

<body — your workflow>     ← instructions

Frontmatter

---
name: skill-name
description: Diagnoses and fixes <problem>. Use when the user reports <symptom>.
license: Proprietary
compatibility: Requires Node.js 18+, Windows or macOS
allowed-tools:
  - tool_one
  - tool_two
  - tool_three
metadata:
  prerequisites:
    before-corrective:
      - tool_one
  maxAggregateRisk: medium
  userLabel: "Short label about what this skill does"
  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`	Give your skill a name, must match the folder name exactly.
`description`	One sentence describing the problem. Will be used to decide if the skill is the right match.
`allowed-tools`	The exact list of tools your workflow can use. The agent will refuse to call any tool not on this list.
`metadata.prerequisites.before-corrective`	Info tools that need to run before any tools with write actions.
`metadata.maxAggregateRisk`	`low`, `medium`, or `high`. Set this to your riskiest allowed tool’s level.
`metadata.userLabel`	Short message shown to the user when AI agent needs to clarify the skill selection.
`metadata.examples`	List the example ways the user might phrase the problem. Combined with `description` and used for better skill selection.
`metadata.pill`	Creates a button in the desktop agent UI for quick selection. Define the parameters such as `icon`, `order`, etc.

Skill body

When create an instructions in the skill body, use the following structure:

## When to use

Short paragraph: when this skill is right, and when it isn't (point to a different skill by name). This is used for expanded context that did not fit in the `description` frontmatter field.

## Steps

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

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

## Edge cases

Bullet list of unusual situations and how to handle them.

Use **Step N — Name** (bold) for steps. Don’t use ### Step N (heading) — markdown headings get stripped from parts of the system.

Writing a step

Every step calls exactly one tool. Within the step, you can include up to six things:

Step input	Example
Which tool to call	Call `check_connectivity` to test internet reachability.
What parameters to pass to a tool (`params`)	Call `check_connectivity` with `targets: ["8.8.8.8", "google.com"]` and `count: 3`.
When to use / skip the step (`condition`)	Only run when Step 1 returned all targets unreachable. Conditions must reference what a prior tool actually returned. Don’t condition on user identity, mood, or intent.
How to interpret tool output (`notes`)	Note: the tool returns a `proxies[]` array — iterate it, don’t assume one entry.
Iterate over a list of outputs (`foreach`)	For each app the user approved in Step 4, call `clear_app_cache` with `dryRun: false`.
Where parameter values come from (`inputs`)	Call `get_disk_usage` with `volume` set to the mount path from Step 1.
Flag sensitive data	Treat `password` as sensitive — do not log or echo.

Complete skill example

---
name: dns-flush
description: Diagnoses and fixes DNS resolution failures when websites won't load but IP-level connectivity is working.
compatibility: Requires Node.js 18+, Windows or macOS
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.

​What are skills?

​How a skill is selected

​Anatomy of a skill

​Frontmatter

​Skill body

​Writing a step

​Complete skill example