# Agent skills

> Shipped skill packs for core authoring, Native UI, and automation, including how agents discover and apply them via the CLI.

- Repository: vercel-labs/native
- GitHub: https://github.com/vercel-labs/native
- Human docs: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a
- Complete Markdown: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/llms-full.txt

## Source Files

- `skills/native-sdk/SKILL.md`
- `skill-data/core/SKILL.md`
- `skill-data/native-ui/SKILL.md`
- `skill-data/automation/SKILL.md`
- `docs/src/app/skills/layout.tsx`

---

---
title: "Agent skills"
description: "Shipped skill packs for core authoring, Native UI, and automation, including how agents discover and apply them via the CLI."
---

The `@native-sdk/cli` package ships version-matched agent skill packs as `SKILL.md` documents under `skills/` and `skill-data/`. `native skills list` and `native skills get` discover those files next to the installed CLI (or via `NATIVE_SDK_SKILLS_ROOT`), print them to stdout, and optionally append each skill’s `references/` and `templates/` trees with `--full`. Skill content is not copied by `native init`; agents and evals load it explicitly so guidance always matches the toolkit binary on PATH.

## Layout on disk

The CLI walks two package-root directories for any file named `SKILL.md`:

| Directory | Role |
| --- | --- |
| `skills/` | Installer-facing discovery stub (`native-sdk`), marked `hidden: true` so it is omitted from `skills list` and `skills get --all` |
| `skill-data/` | Full skill packs served to agents: `core`, `native-ui`, `automation` |

```text
@native-sdk/cli package root
├── skills/
│   └── native-sdk/SKILL.md          # discovery stub (hidden)
└── skill-data/
    ├── core/
    │   ├── SKILL.md
    │   └── references/
    │       ├── project-anatomy.md
    │       ├── app-model-runtime.md
    │       ├── frontend-assets.md
    │       ├── bridge-security-native-capabilities.md
    │       └── web-engines-packaging-debugging.md
    ├── native-ui/
    │   └── SKILL.md
    └── automation/
        └── SKILL.md
```

Both trees are included in the published npm package (`package.json` `files`: `skill-data`, `skills`). The binary resolves the package root by walking parents of the executable until either directory exists; override with `NATIVE_SDK_SKILLS_ROOT` when the binary and skill trees are not co-located.

### Frontmatter contract

Each `SKILL.md` starts with YAML frontmatter. The CLI parses only these keys:

| Field | Required | Behavior |
| --- | --- | --- |
| `name` | yes | Skill identifier for `skills get <name>` |
| `description` | no | Printed as the second column of `skills list` |
| `hidden` | no | `true` / `yes` → excluded from list and `--all` |
| `allowed-tools` | no | Agent-installer metadata (e.g. discovery stub); ignored by the CLI printer |

Missing `name` or invalid frontmatter skips the file during discovery. Skills sort alphabetically by name.

## Install and discovery

Two layers keep install thin and content versioned:

1. **One-time agent install** — register the discovery skill with a skills installer:

```bash
npx skills add vercel-labs/native
```

That installs the compact `native-sdk` entry point (the hidden stub). It orients the agent and directs it to load deep content from the installed CLI rather than embedding a full snapshot.

2. **Version-matched content** — after `@native-sdk/cli` is on PATH, agents (or humans) pull live packs:

```bash
native skills list
native skills get core
native skills get core --full
native skills get native-ui
native skills get automation
```

<Note>
Because deep guidance is always read from the CLI, the agent stays aligned with whatever toolkit version each project uses. Updating `@native-sdk/cli` updates skill text without re-running the skills installer.
</Note>

Skill packs are portable Markdown on disk. Any coding agent that can run shell commands and load a `SKILL.md` path works; nothing in the format assumes a particular model provider, hosted connector, or proprietary skill catalog beyond the optional one-time installer command above.

## CLI surface

### Commands

```bash
native skills list
native skills get <name> [--full]
native skills get --all [--full]
native skills --help
```

| Command | Output | Notes |
| --- | --- | --- |
| `skills list` | `name\tdescription` per visible skill | Hidden skills omitted |
| `skills get <name>` | Full `SKILL.md` body on stdout | Includes frontmatter |
| `skills get <name> --full` | `SKILL.md` plus every file under `references/` and `templates/` | Each supplementary file is separated with `---` and a `# references/…` or `# templates/…` heading |
| `skills get --all [--full]` | All non-hidden skills concatenated | Skills separated by `\n---\n\n` |
| unknown name | stderr `Unknown skill: …`, exit 1 | Does not list available names in the error |
| no package root | stderr `native skills: could not find skills/ or skill-data/ near the native-sdk executable`, exit 1 | Fix install layout or set `NATIVE_SDK_SKILLS_ROOT` |

### Environment

<ParamField body="NATIVE_SDK_SKILLS_ROOT" type="string">
Absolute path to a directory that contains `skills/` and/or `skill-data/`. Checked first, before walking parents of the executable path.
</ParamField>

### Deliver a skill into an agent workspace

`skills get` is stdout-only, so delivery is a redirect into wherever the agent loads skills:

```bash
mkdir -p .claude/skills/native-ui
native skills get native-ui > .claude/skills/native-ui/SKILL.md
```

For implementation work that needs core references:

```bash
mkdir -p .claude/skills/core
native skills get core --full > .claude/skills/core/SKILL.md
```

<Warning>
`native init` does **not** copy skills into the app. Delivery is always explicit so the workspace skill is exactly what the installed CLI serves.
</Warning>

The repository eval harness uses the same path: after `native init … --frontend native`, it runs `native skills get native-ui` and writes the stdout into `.claude/skills/native-ui/SKILL.md` before the agent-under-test runs.

## Shipped skill packs

| Name | Path | Hidden | `--full` extras | Load when |
| --- | --- | --- | --- | --- |
| `native-sdk` | `skills/native-sdk/` | yes | none | Installer discovery only; not listed by default |
| `core` | `skill-data/core/` | no | five `references/*.md` files | Orienting, scaffolding, `app.zon`, WebView shells, bridge, packaging, debug |
| `native-ui` | `skill-data/native-ui/` | no | none today | Authoring `.native` views, `Model`/`Msg`/`update`, `UiApp`, markup testing |
| `automation` | `skill-data/automation/` | no | none today | Live app inspection, `native automate *`, smoke tests, screenshots |

### `core`

Shared foundation for both native-rendered and WebView-shell apps:

- Mental model: `App`, `Runtime`, `WebViewSource`, `app.zon`, `src/main.zig` vs `src/runner.zig`
- Task router into `--full` references
- Frontend frameworks (`next`, `vite`, `react`, `svelte`, `vue`), bridge commands, security defaults
- Package / doctor / validate command checklist

`--full` appends, in walk order under `references/`:

| Reference | Use for |
| --- | --- |
| `project-anatomy.md` | Generated files, build steps, project shape |
| `app-model-runtime.md` | `App` / `Runtime` callbacks, embedding, tests |
| `frontend-assets.md` | Dev server, HMR, bundled assets |
| `bridge-security-native-capabilities.md` | Bridge handlers, permissions, windows, dialogs |
| `web-engines-packaging-debugging.md` | System WebView vs CEF, package, doctor, logs |

For native-rendered UI authoring, `core` explicitly routes agents to `native skills get native-ui`. For running-app inspection, it routes to `automation`.

### `native-ui`

Authoring surface for native-rendered apps: declarative `.native` markup plus Zig `Model` / `Msg` / `update` on `native_sdk.UiApp`. Covers:

- App wiring (`UiApp.create`, markup watch / compiled markup, web panes, status items)
- Element and attribute catalog, flex layout, identity keys, token attributes
- Expression grammar, binding resolution, derive-don’t-store model methods
- Message dispatch, text-field mirror pattern, effects channel (`spawn` / `fetch` / file / clipboard / timer / audio)
- Secondary windows, hidden titlebar chrome, images, templates/imports, markdown, charts
- `native markup check`, unit testing via `msgFor*`, and live verification through automation

Editors treat `.native` as HTML for highlighting; `native init --full` can write the VS Code association.

### `automation`

File-based IPC automation every Native SDK app can embed (native-rendered and WebView shells). Covers:

- Prerequisites: build/run with `-Dautomation=true`, pass `automation.Server` into `RuntimeOptions`
- Commands: `wait`, `assert`, `list`, `snapshot`, `reload`, `screenshot`, widget drive verbs, `bridge`, `profile`, tray actions
- Protocol dir `.zig-cache/native-sdk-automation/` (cwd-relative; CLI never creates it)
- What is in scope (widgets, bridge, readiness, deterministic `gpu_surface` screenshots) and out of scope (WebView DOM / WebView pixels)
- Smoke-test and CI patterns, protocol mismatch and stale-instance debugging

## Recommended agent workflow

```mermaid
flowchart TD
  install["npx skills add vercel-labs/native\n+ npm install -g @native-sdk/cli"]
  list["native skills list"]
  core["native skills get core\n(+ --full for implement)"]
  branch{Task shape}
  ui["native skills get native-ui"]
  auto["native skills get automation"]
  build["native check / test / build / dev"]
  verify["native automate wait\nautomate assert / snapshot / screenshot"]

  install --> list --> core --> branch
  branch -->|markup Model Msg UiApp| ui --> build
  branch -->|WebView bridge package| build
  branch -->|live window / smoke| auto --> verify
  build --> verify
```

<Steps>
  <Step title="Install once">
    Install the CLI (`npm install -g @native-sdk/cli`) and, for agent hosts that use a skills installer, run `npx skills add vercel-labs/native`. Confirm with `native version` and `native skills list` (expect `automation`, `core`, `native-ui`).
  </Step>
  <Step title="Orient with core">
    Run `native skills get core` before explaining or changing an app. For implementation, use `native skills get core --full` so project anatomy, runtime, frontend, bridge, and packaging references are in the same stream.
  </Step>
  <Step title="Load the task-specific pack">
    Native UI authoring → `native skills get native-ui`. Live verification → `native skills get automation`. Write stdout into the agent’s skills directory when the host only auto-loads on-disk skills.
  </Step>
  <Step title="Edit the correct layer">
    Follow skill ownership: `app.zon` for manifest/policy, `src/main.zig` for app behavior / Model-Msg-update, `src/runner.zig` for runtime wiring, `src/*.native` for markup views, `frontend/` for web shells.
  </Step>
  <Step title="Validate, then automate">
    Prefer `native check` / `native test` / headless unit paths first. For GUI confidence, build with `-Dautomation=true`, run the app, then `native automate wait` and `native automate assert` from the app cwd.
  </Step>
</Steps>

## Failure modes

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `could not find skills/ or skill-data/` | Broken package layout or binary moved without skill trees | Reinstall `@native-sdk/cli`, or set `NATIVE_SDK_SKILLS_ROOT` to the package root that contains those dirs |
| `Unknown skill: …` | Typo or requesting the hidden discovery name via list-only habits | Run `native skills list`; use `core`, `native-ui`, or `automation`. `native-sdk` exists but is hidden |
| Empty `skills list` | No parseable `SKILL.md` under the resolved root | Confirm frontmatter `name:` fields and that root points at a real package |
| Stale guidance vs runtime APIs | Workspace skill snapshot older than CLI | Re-run `native skills get <name>` (and `--full` if used) from the current binary |
| Automation commands fail after skill-guided build | App not automation-enabled or wrong cwd | Build with `-Dautomation=true`, launch from the app directory, re-read the automation skill |
| Agent invents layout / APIs | Skipped skills, relied on model memory | Skills themselves instruct agents to assume zero prior Native SDK knowledge and read the pack first |

## Constraints and design notes

- **Version coupling** — skill Markdown ships inside `@native-sdk/cli` next to the Zig framework sources. Skills and binary move together on npm.
- **No init embedding** — scaffolds stay skill-free; evals and agents inject skills deliberately.
- **Hidden discovery skill** — `native-sdk` is for installer catalogs (`allowed-tools` allows `native:*` and `npx @native-sdk/cli:*`). Day-to-day agent work uses the three visible packs.
- **`--full` is append-only** — supplementary files are concatenated after `SKILL.md`; only `core` currently ships `references/`. Empty `templates/` directories are skipped.
- **Not a model-provider lock-in** — packs are plain files + CLI stdout. Hosts may load them as Claude-style skills, generic system context, or custom catalogs.

## Related pages

<CardGroup>
  <Card title="CLI reference" href="/cli-reference">
    Full `native` command surface, including `skills`, `automate`, `check`, and `dev`.
  </Card>
  <Card title="Native UI markup" href="/native-ui">
    Product docs for the markup and UiApp surface the `native-ui` skill teaches.
  </Card>
  <Card title="Automation" href="/automation">
    Embedded automation server, snapshots, widget driving, and screenshots.
  </Card>
  <Card title="App model" href="/app-model">
    Model, Msg, update loop wiring shared by skill guidance and runtime.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    Scaffold with `native init`, run `native dev`, and verify the first window.
  </Card>
  <Card title="Testing" href="/testing">
    Headless UI tests and when to escalate from unit paths to automation.
  </Card>
</CardGroup>