Maintenance Tools

This page groups the small maintenance surfaces that used to be split across separate docs pages. Use it when verifying agent context quality, adapter regressions, or generated skill exports.

Context Lint

npm run lint:context runs scripts/lint-context.sh against agent-facing context such as AGENTS.md, local skills, workflows, and docs. It catches stale paths, missing verification instructions, and weak operational context before an agent relies on it.

Resolution order:

1. agent-lint on PATH.
2. A vendored local build, when present.
3. Soft skip with a warning. The script does not fetch from the network.

Commands:

npm run lint:context
UNICLI_LINT_THRESHOLD=80 npm run lint:context
UNICLI_LINT_DISABLE=1 npm run verify

Threshold checks require jq. Without it, the script prints the raw output and exits 0.

Eval Harness

unicli eval runs YAML-defined regression suites against adapters and reports SCORE=N/M. User-local evals live under ~/.unicli/evals/.

Commands:

unicli eval list
unicli eval run smoke/hackernews
unicli eval run --all smoke/
unicli eval ci --since 7d
unicli eval run smoke/hackernews --json

Eval file shape:

name: hackernews-smoke
adapter: hackernews
description: Hacker News public-API smoke test
cases:
  - command: top
    args:
      limit: 5
    judges:
      - { type: arrayMinLength, min: 5 }
      - { type: nonEmpty }

Judges:

Type	Fields	Passes when
exitCode	equals: 0	The CLI exit code matches.
nonEmpty	none	Raw output is non-whitespace.
matchesPattern	pattern: "regex"	Raw output matches the regex.
contains	field?: "json.path", value:	The resolved value contains the substring.
arrayMinLength	path?: "json.path", min:	The resolved value is an array of min+.

Field paths use dotted syntax with array subscripts:

data.items[0].title
results[3].author

Skill Export

unicli skills export emits one SKILL.md-compatible file per adapter command. Use it when an agent runtime can ingest local skills more cheaply than it can call discovery for every task.

Commands:

unicli skills export
unicli skills export --out /tmp/unicli-skills
unicli skills publish
unicli skills publish --to ~/.cursor/skills/uni-cli/
unicli skills catalog
unicli skills catalog --out /tmp/catalog.json

Generated skill shape:

---
name: hackernews-top
description: Hacker News top stories
when_to_use: When you need the current top items from hackernews.
command: unicli hackernews top
source: unicli
---

## What it does

Hacker News top stories.

## How to call it

```bash
unicli hackernews top --limit 20
```

Use -f json when the caller needs JSON. Errors use the normal v2 envelope and include the failing adapter path, step, and suggestion.

unicli skills catalog writes docs/adapters-catalog.json or a custom output path. Agents can ingest the catalog once and route directly without repeated discovery calls.