---
url: 'https://adk.nht.io/developer-tools/eslint-rules/skills.md'
description: >-
  The adk-skills plugin at @nhtio/adk/batteries/skills/lint — a mandatory gate
  and the four unsafe opt-ins that each remove a safety boundary, caught at lint
  time instead of in a diff nobody read.
---

# Skills battery rules

## LLM summary — Skills battery rules

* `import adkSkills from '@nhtio/adk/batteries/skills/lint'`, namespace `adk-skills`, two rules, `configs.recommended` sets them at the stated severities.
* `adk-skills/require-gate` (`error`) — `createSkillManager({…})` with an object literal containing no `gate`. Construction throws `E_INVALID_SKILLS_CONFIG`, because skill lifecycle and every skill-supplied tool funnel through the gate. The callee is matched by its resolved export name: an aliased `createSkillManager as csm` and a namespace `skills.createSkillManager` are checked identically; a same-named factory from another module is not.
* `adk-skills/no-unsafe-opt-in` (`warn`) — any enabled key in a skill-manager config's `unsafe` object: `isolatedToolsInProcess: true`, `scriptsPermissivePolicy: <policy>`, `ungatedSkillTools: true`. One finding per enabled key, naming the boundary it removes.
* Conservative by design: only an object literal carrying a sibling config key or annotated `SkillManagerConfig`/`SkillIsolationConfig` is recognised as a config; spreads and non-literal arguments are left alone.
* TypeScript wrappers are transparent: `as X`, `satisfies X`, `<X>{…}`, `x!` and parentheses around an argument or property value are looked through, so `createSkillManager({ sources } as any)` and `unsafe: { ungatedSkillTools: true } as const` are flagged exactly like the bare literals.
* Rules are report-only. Carve out an exception with `// eslint-disable-next-line adk-skills/<rule> -- <reason>`.

The skills battery is not a content feature. A skill carries tools, and a skill
carrying tools is a plugin supply chain: whatever the skill says it does, the
host is the thing that actually grants it. Two decisions therefore have to be
visible in the diff rather than inherited by default — the gate that approves a
skill-supplied tool call, and every `unsafe` opt-in that deliberately gives a
containment boundary up.

## Install and register

```ts
import adkSkills from "@nhtio/adk/batteries/skills/lint";

export default [
  {
    plugins: { "adk-skills": adkSkills.plugin },
    rules: adkSkills.configs.recommended.rules,
  },
];
```

`eslint` and `@typescript-eslint/utils` are optional peer dependencies of
`@nhtio/adk`; the skills battery never imports this module at runtime. Every rule
is report-only — the fix is a decision, and the decision is the deployment's.

## `adk-skills/require-gate` — error

`createSkillManager` requires a `gate`. Skill lifecycle operations and every
skill-supplied tool run through it: it is the single place a host gets to refuse
a call the model proposed on behalf of a skill. Without it there is no boundary
to refuse at, which is why construction throws `E_INVALID_SKILLS_CONFIG` rather
than defaulting to something.

```ts
// flagged — throws at construction
const manager = await createSkillManager({ sources });

// correct
const manager = await createSkillManager({ sources, gate });
```

Passing `gate: undefined` does not satisfy it either; the factory's own
`typeof gate !== 'function'` check rejects that, and so does the rule.

```ts
// flagged — the assertion is not an escape hatch
const manager = await createSkillManager({ sources } as any);

// correct
const manager = await createSkillManager({ sources, gate });
```

**What it does not catch.** A spread argument (`{ ...config }`) is not inspected —
the gate may be supplied there. A non-literal argument is not inspected at all,
including a config held in a separate variable (`const cfg = { sources }; createSkillManager(cfg)`)
— the rule reads the argument's literal shape, not the variable it came from.
The callee is matched by its resolved export name through the file's import
bindings, so an aliased (`import { createSkillManager as csm }`) or namespace
(`skills.createSkillManager`) call is checked — but only `createSkillManager` is:
the rule is not a general "every tool must be gated" rule, and a skill tool
composed by hand further down is out of scope. A local object that merely carries
the name (`const skills = { createSkillManager }`) is not an import binding and is
not traced.

::: warning `ungatedSkillTools` turns the gate off
`unsafe: { ungatedSkillTools: true }` makes the manager pass `gate: undefined` to
every skill-supplied tool it forges. It is reported separately, by
`adk-skills/no-unsafe-opt-in` — but note the pair: a gated manager that also
opts into `ungatedSkillTools` has a gate for its lifecycle calls and none for
the tools that matter most.
:::

## `adk-skills/no-unsafe-opt-in` — warn

Each key in the manager config's `unsafe` object is a named containment control,
and each one is defined by the boundary it removes. The rule reports every
enabled key separately, so the finding names the specific loss rather than
waving at "unsafe options":

| Key                            | Boundary it removes                                                                                                       |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `isolatedToolsInProcess: true` | Tier-2 skill code runs in the default in-process guest, whose kill is a no-op — cancellation becomes best-effort at best. |
| `scriptsPermissivePolicy`      | Replaces the derived, narrow script policy with a caller-supplied permissive one.                                         |
| `ungatedSkillTools: true`      | Skips the mandatory gate around skill-supplied tools.                                                                     |

`isolatedToolsInProcess` additionally requires `isolation` to be configured with
no `resolveGuest` — without the opt-in, that combination throws rather than
degrading, so the flag is what makes an unsafe configuration reachable at all.

```ts
// two findings: one per enabled key
const manager = await createSkillManager({
  sources,
  gate,
  unsafe: { ungatedSkillTools: true, isolatedToolsInProcess: true },
});
```

**What it does not catch.** The rule recognises a config by its sibling keys
(`sources`, `gate`, `scripts`, `isolation`, `defaultChannel`, `artifactKinds`,
`artifactBindings`, `autoRefresh`) or by a
`SkillManagerConfig`/`SkillIsolationConfig` annotation — recognition that does not
depend on how the factory was spelled, so an aliased or namespace-spelled
`createSkillManager(...)` call with an `unsafe` section is reported identically. A
bare `{ unsafe: { … } }` with none of those keys or annotations is treated as some
other API's object and left alone — the same conservatism as the sandbox plugin —
and a config held in a separate variable is only inspected if that variable's
literal happens to carry the sibling keys at the point it is declared. Spreads and
dynamic values are ignored. A TypeScript wrapper on a value (`as X`,
`satisfies X`, `<X>`, `!`, parens) is looked through, not treated as a bypass.

::: tip Wanting it is fine — hiding it is not
An in-process isolated guest is a legitimate choice for a trusted-tier
deployment that cannot fork. The rule's whole purpose is that the choice appears
in review:
`// eslint-disable-next-line adk-skills/no-unsafe-opt-in -- trusted tier; forking unavailable in this host`.
A silent opt-in and a deliberate one look identical otherwise, and only one of
them is reviewable.
:::
