# Provider harnesses

> Supported AI harness directories, install aliases, frontmatter and hook capability matrix, and provider-specific trust or skills-enable steps.

- Repository: pbakaus/impeccable
- GitHub: https://github.com/pbakaus/impeccable
- Human docs: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4
- Complete Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/llms-full.txt

## Source Files

- `docs/HARNESSES.md`
- `cli/bin/commands/skills.mjs`
- `scripts/lib/transformers/providers.js`
- `scripts/lib/utils.js`
- `skill/scripts/lib/provider.mjs`
- `README.md`

---

---
title: "Provider harnesses"
description: "Supported AI harness directories, install aliases, frontmatter and hook capability matrix, and provider-specific trust or skills-enable steps."
---

Impeccable ships one skill payload, compiled into provider-specific trees under tracked root harness folders (for example `.claude/skills/impeccable`, `.cursor/skills/impeccable`, `.agents/skills/impeccable`). The CLI installer (`npx impeccable install|link|update`) and the release build both target those trees. Build config lives in `scripts/lib/transformers/providers.js`; install aliases, detection, hooks, and global path overrides live in `cli/bin/commands/skills.mjs`. Capability notes are summarized in `docs/HARNESSES.md` (point-in-time; verify against the live harness before relying on edge claims).

## Supported harness directories

`PROVIDER_DIRS` is the install surface. Each entry is a project-relative config directory that receives `skills/impeccable/` (and hooks/agents where applicable).

| Display name | Install input | Project dir | Primary skills path |
|--------------|---------------|-------------|---------------------|
| Antigravity | `antigravity` | `.agent` | `.agent/skills/` |
| Claude Code | `claude` | `.claude` | `.claude/skills/` |
| Codex CLI | `codex` | `.agents` | `.agents/skills/` |
| Cursor | `cursor` | `.cursor` | `.cursor/skills/` |
| Gemini CLI | `gemini` | `.gemini` | `.gemini/skills/` |
| GitHub Copilot | `github` | `.github` | `.github/skills/` |
| Grok Build | `grok` | `.grok` | `.grok/skills/` |
| Kiro | `kiro` | `.kiro` | `.kiro/skills/` |
| OpenCode | `opencode` | `.opencode` | `.opencode/skills/` |
| Pi Coding Agent | `pi` | `.pi` | `.pi/skills/` |
| Qoder | `qoder` | `.qoder` | `.qoder/skills/` |
| Trae | `trae` | `.trae` | `.trae/skills/` |
| Trae CN | `trae-cn` | `.trae-cn` | `.trae-cn/skills/` |
| Rovo Dev | `rovo-dev` | `.rovodev` | `.rovodev/skills/` |
| Mistral Vibe | `vibe` | `.vibe` | `.vibe/skills/` |

<Note>
Codex CLI is **not** installed under `.codex/skills`. Skills land in `.agents/skills/` (also the Codex primary skill path). Project hooks for Codex still write to `.codex/hooks.json`.
</Note>

### Cross-read paths

Some harnesses also load skills from shared or sibling folders:

| Harness | Also reads |
|---------|------------|
| Cursor | `.agents/skills/`, `.claude/skills/` |
| Gemini CLI | `.agents/skills/` |
| GitHub Copilot | `.agents/skills/`, `.claude/skills/` |
| OpenCode | `.agents/skills/`, `.claude/skills/` |
| Pi | `.agents/skills/` |
| Mistral Vibe | `.agents/skills/` (project), `~/.agents/skills/` (global) |
| Grok Build | `.agents/skills/`, `.claude/skills/`, `.cursor/skills/` (Claude/Cursor compat; configurable) |
| Antigravity | `.agents/skills/` (project), `~/.agents/skills/` (global) |

All supported trees use `{skill-name}/SKILL.md` plus optional `reference/`, `scripts/`, and `assets/`.

### Global skill path overrides

Project scope is always `<provider>/skills` under the project root. Global (user) installs use `<home>/<provider>/skills` except:

| Provider dir | Global skills directory |
|--------------|-------------------------|
| `.agent` (Antigravity) | `~/.gemini/config/skills` |
| `.pi` | `~/.pi/agent/skills` |
| `.opencode` | `$OPENCODE_CONFIG_DIR/skills`, else `$XDG_CONFIG_HOME/opencode/skills`, else `~/.config/opencode/skills` |

Writing OpenCode global skills to `~/.opencode/skills` is a known miss; the CLI uses the config dir above so `opencode debug skill` can list them.

## Install aliases

Pass aliases to `--providers` as comma-separated names (with or without a leading `.`).

| Alias | Resolves to |
|-------|-------------|
| `agent`, `antigravity` | `.agent` |
| `agents`, `codex` | `.agents` |
| `claude`, `claude-code` | `.claude` |
| `cursor` | `.cursor` |
| `gemini` | `.gemini` |
| `github`, `copilot` | `.github` |
| `grok`, `grok-build`, `xai` | `.grok` |
| `kiro` | `.kiro` |
| `opencode` | `.opencode` |
| `pi` | `.pi` |
| `qoder` | `.qoder` |
| `rovo-dev`, `rovodev` | `.rovodev` |
| `trae` | `.trae` |
| `trae-cn` | `.trae-cn` |
| `vibe` | `.vibe` |

Interactive install order (`PROVIDER_INPUT_ORDER`): `antigravity`, `claude`, `codex`, `cursor`, `gemini`, `github`, `grok`, `kiro`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`, `rovo-dev`, `vibe`.

When nothing is detected, defaults are `.claude` and `.agents`.

Detection when the project has no harness folder yet walks home hints such as `~/.claude`, `~/.codex` → `.agents`, `~/.gemini/antigravity*` → `.agent`, and OpenCode’s config dir.

## Install commands

```bash
# Detect harnesses, choose providers and project vs global scope
npx impeccable install

# Scripted
npx impeccable install --providers=claude,codex,cursor,grok --scope=project
npx impeccable install --providers=claude --scope=global -y

# Refresh existing installs
npx impeccable update

# Skip hook install for this run (does not rewrite recorded consent)
npx impeccable install --providers=claude --no-hooks

# Submodule / local checkout link
npx impeccable link --source=.impeccable --providers=claude,cursor
```

<ParamField body="--providers" type="string">
Comma-separated install aliases or dir names (for example `claude,cursor` or `.claude,.cursor`).
</ParamField>

<ParamField body="--scope" type="string">
`project` (default for project roots) or `global` (user-level skills dirs).
</ParamField>

<ParamField body="--no-hooks" type="boolean">
Skip design-hook manifest install for this run.
</ParamField>

<ParamField body="-y / --yes" type="boolean">
Non-interactive defaults (hooks default on when consent is unset).
</ParamField>

### Plugin installs (skill + agents + hooks package)

<Tabs>
  <Tab title="Claude Code">
```bash
/plugin marketplace add pbakaus/impeccable
# Then install Impeccable from /plugin
```
  </Tab>
  <Tab title="Grok Build">
```bash
grok plugin install pbakaus/impeccable#plugin --trust
```
The `#plugin` suffix installs the slim package under `plugin/` (skills, agents, hooks), not the full monorepo.
  </Tab>
</Tabs>

Manual `cp -r dist/<provider>/...` remains a fallback. Prefer `npx impeccable install` so hooks and agent sidecars are placed correctly.

## Build provider keys vs install dirs

The transformer factory (`PROVIDERS` in `scripts/lib/transformers/providers.js`) uses build keys that map to config dirs. A few names differ from install aliases:

| Build key | `configDir` | Notes |
|-----------|-------------|--------|
| `claude-code` | `.claude` | Full frontmatter + Claude hooks |
| `cursor` | `.cursor` | `hooks.json` at `.cursor/hooks.json` |
| `codex` | `.codex` | Hooks only; skills emitted under `agents` |
| `agents` | `.agents` | Codex primary skills tree; OpenAI metadata sidecar |
| `github` | `.github` | Copilot skills + `hooks/impeccable.json` |
| `grok` | `.grok` | Skills, agents, `hooks/impeccable.json` |
| `antigravity` | `.agent` | Not `.agents` |
| `gemini`, `kiro`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`, `rovo-dev`, `vibe` | matching dot-dir | Skills only (no Impeccable hook emission) |

Runtime placeholders (`PROVIDER_PLACEHOLDERS`) set `{{model}}`, `{{config_file}}`, `{{ask_instruction}}`, and `{{command_prefix}}`. Codex uses command prefix `$`; other providers use `/`. Source scripts default to `/` via `IMPECCABLE_COMMAND_PREFIX` in `skill/scripts/lib/provider.mjs`; the provider build rewrites that constant per target.

## Frontmatter capability matrix

Harnesses implement the [Agent Skills](https://agentskills.io/specification) frontmatter set to varying degrees. Impeccable only **emits** the fields listed in each provider’s `frontmatterFields` config; harnesses ignore unknown keys.

Spec fields: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`. Common extensions: `user-invocable`, `argument-hint`, `disable-model-invocation`, `model`, `effort`, `context`, `agent`, `hooks`.

| Field | Claude | Cursor | Gemini | Codex | Copilot | Grok | Kiro | OpenCode | Pi | Qoder | Rovo | Vibe | Antigravity |
|-------|:------:|:------:|:------:|:-----:|:-------:|:----:|:----:|:--------:|:--:|:-----:|:----:|:----:|:-----------:|
| `name` / `description` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| `license` / `compatibility` / `metadata` | Yes | Yes | Ignored | No* | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| `allowed-tools` | Yes | No | Ignored | No* | No | Yes | No | Yes | Yes | Yes | Yes | Yes | Yes |
| `user-invocable` | Yes | No | No | No | Yes | Yes | No | Yes | No | Yes | Yes | Yes | No |
| `argument-hint` | Yes | No | No | No | Yes | Yes | No | Yes | No | Yes | Yes | No | No |
| `model` / `effort` | Yes | No | No | No | No | Yes | No | model only | No | No | No | No | No |

\*Codex skill body frontmatter is minimal; richer metadata goes to `agents/openai.yaml` when `writeOpenAIMetadata` is set. Grok also documents `when-to-use` as a supported extension.

**Impeccable emission** (what the build writes), by provider config:

| Provider | Emitted optional frontmatter beyond name/description |
|----------|------------------------------------------------------|
| Claude Code, OpenCode, Qoder, Rovo Dev, Grok | `user-invocable`, `argument-hint`, `license`, `compatibility`, `metadata`, `allowed-tools` |
| GitHub Copilot, Trae, Trae CN | `user-invocable`, `argument-hint`, `license`, `compatibility`, `metadata` |
| Cursor, Kiro | `license`, `compatibility`, `metadata` |
| Pi, Antigravity | `license`, `compatibility`, `metadata`, `allowed-tools` |
| Vibe | `user-invocable`, `license`, `compatibility`, `metadata`, `allowed-tools` |
| Gemini, Codex, agents | none (Codex/agents use OpenAI metadata sidecar) |

Runtime variable substitution inside skill bodies (`$ARGUMENTS`, `${CLAUDE_SKILL_DIR}`, …) is Claude Code–specific. Cross-provider text uses compile-time `{{placeholders}}` only.

## Design hook matrix

Impeccable installs hooks only for harnesses with a documented on-disk hook format. Other providers still get skills and commands.

| Harness | When | Manifest path | Script | Trust / enable |
|---------|------|---------------|--------|----------------|
| Claude Code | After edit (`PostToolUse`) | `.claude/settings.local.json` (gitignored); shared `settings.json` honored if the hook was moved there | `${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs` | Project trust as usual for Claude settings |
| Cursor | Before write (`preToolUse`) | `.cursor/hooks.json` | `.cursor/skills/impeccable/scripts/hook-before-edit.mjs` | Enable Agent Skills (Nightly/Beta setup below); reload if hooks do not pick up |
| Codex CLI | After edit | `.codex/hooks.json` (skill payload under `.agents`) | `.agents/skills/impeccable/scripts/hook.mjs` | Open `/hooks` after install/update and approve; definition changes can re-prompt; hooks flagged feature, disabled on Windows |
| GitHub Copilot | After edit | `.github/hooks/impeccable.json` (team-shared) | `.github/skills/impeccable/scripts/hook.mjs` | File on default branch + folder trust (CLI/cloud agent) |
| Grok Build | After edit + Stop deep pass | `.grok/hooks/impeccable.json` | `.grok/skills/impeccable/scripts/hook.mjs` | `/hooks-trust` or launch with `--trust` |
| All others | — | n/a | — | Skill-only install |

Claude/Codex/Copilot/Grok surface findings after edits (and Stop where supported). Cursor can **block** proposed writes that fail the detector.

### Hook consent

On interactive `install`/`update`, Impeccable explains the design hook and asks once (default yes). The answer is stored per developer in gitignored `.impeccable/config.local.json` via `getHookConsent` / `setHookConsent`. Recorded `declined` skips forever until consent is cleared; `--no-hooks` skips only that run without recording. Non-interactive runs default to installing hooks when consent is unset.

Malformed hook manifests abort install by default; `--force` backs up the file as `.bak` and replaces it. Unrelated hook entries are preserved when merging.

## Native subagent emission

Impeccable writes native agent files only where the on-disk format is stable:

| Harness | Location | Format |
|---------|----------|--------|
| Claude Code | Plugin `agents/` (marketplace / `plugin/`) | Markdown + YAML frontmatter |
| Grok Build | Plugin + project `.grok/agents/` | Markdown + YAML (Claude-compatible) |
| Codex CLI | Nested `<skill>/agents/` (auto-discovered with skill) | TOML |
| Cursor | `.cursor/agents/impeccable-*.md` (user: `~/.cursor/agents/`) | Markdown |
| GitHub Copilot | `.github/agents/impeccable-*.agent.md` (user: `~/.copilot/agents/`) | `.agent.md`; user-level can shadow project |

Canonical prompts live under `skill/agents/`. Spawn behavior differs: Claude and Grok can spawn programmatically; Codex requires user-allowed sub-agents; Cursor auto-delegates or uses `/name` and is not reliably skill-spawnable.

## Provider-specific trust and enable steps

<Steps>
  <Step title="Cursor skills enable">
    1. Cursor Settings → Beta → Nightly channel.
    2. Settings → Rules → enable **Agent Skills**.
    3. Install with `npx impeccable install --providers=cursor`.
    4. Reload Cursor if skills or hooks do not appear.
  </Step>
  <Step title="Codex hooks approve">
    1. Install with `npx impeccable install --providers=codex` (skills → `.agents`, hooks → `.codex/hooks.json`).
    2. In Codex, open `/hooks` and approve the project hook.
    3. Re-approve after updates that change the hook definition.
  </Step>
  <Step title="Grok folder trust">
    1. Prefer `npx impeccable install --providers=grok` or `grok plugin install pbakaus/impeccable#plugin --trust`.
    2. Run `/hooks-trust` once per project folder, or start the session with `--trust`.
    3. Grok can also load Claude layouts (`.claude/skills/`, Claude plugins) without native paths.
  </Step>
  <Step title="Claude marketplace plugin">
    1. `/plugin marketplace add pbakaus/impeccable`.
    2. Install from the plugin UI.
    3. Project CLI installs still place machine-local hooks in `.claude/settings.local.json`.
  </Step>
  <Step title="GitHub Copilot shared hook">
    1. Install with `--providers=github` so `.github/skills` and `.github/hooks/impeccable.json` exist.
    2. Commit the hook file; ensure it is on the default branch and the folder is trusted.
  </Step>
</Steps>

## Generated layout (conceptual)

```text
project/
├── .claude/skills/impeccable/     # Claude Code skill
│   └── scripts/hook.mjs
├── .claude/settings.local.json    # Claude hook (machine-local)
├── .cursor/skills/impeccable/
│   └── scripts/hook-before-edit.mjs
├── .cursor/hooks.json
├── .agents/skills/impeccable/     # Codex + universal skills tree
├── .codex/hooks.json              # Codex hooks (sidecar to .agents)
├── .github/skills/impeccable/
├── .github/hooks/impeccable.json
├── .grok/skills/impeccable/
├── .grok/hooks/impeccable.json
└── .impeccable/config.local.json  # hook consent (gitignored)
```

Tracked root harness folders in this repository are **generated distribution artifacts**. Edit `skill/` and rebuild; do not hand-edit provider trees in normal development PRs.

## Verification

| Check | Signal |
|-------|--------|
| Skill present | `<provider>/skills/impeccable/SKILL.md` exists for each installed target |
| Claude hook | `.claude/settings.local.json` (or `settings.json`) references `skills/impeccable/scripts/hook.mjs` |
| Cursor hook | `.cursor/hooks.json` references `hook-before-edit.mjs` |
| Codex hook | `.codex/hooks.json` points at `.agents/skills/impeccable/scripts/hook.mjs` and is approved in `/hooks` |
| Grok hook | `.grok/hooks/impeccable.json` present; session trusted |
| Invoke | `/impeccable` (or `$impeccable` on Codex-built skill text) lists or runs the skill after harness reload |

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Skill missing after install | Wrong provider alias or scope | Pass explicit `--providers=...`; confirm project vs global dir |
| OpenCode global skill invisible | Skills under `~/.opencode` | Install global into OpenCode config dir (`OPENCODE_CONFIG_DIR` / XDG / `~/.config/opencode`) |
| Codex hook silent | Not trusted or wrong script path | Approve in `/hooks`; confirm script under `.agents/skills/...` |
| Grok hooks never run | Folder not trusted | `/hooks-trust` or `--trust` |
| Cursor skills ignored | Skills feature off | Nightly + Agent Skills enable; reload |
| Two providers share one realpath | Symlinked skill dirs | Installer deduplicates by realpath; update once per unique path |
| Malformed hooks.json aborts install | Bad pre-existing manifest | Fix manually or `install`/`update` with `--force` |

## Related pages

<CardGroup>
  <Card title="Installation" href="/installation">
    Install, link, update, scope, and hook consent end-to-end.
  </Card>
  <Card title="Design hook" href="/design-hook">
    Detector-on-edit behavior, quiet/disable controls, native-platform skip.
  </Card>
  <Card title="Plugin agents" href="/plugin-agents">
    Bundled agents and plugin manifest contract for Claude Code and Grok.
  </Card>
  <Card title="Pin shortcuts" href="/pin-shortcuts">
    Standalone `/audit`-style redirects across discovered skill directories.
  </Card>
  <Card title="Environment variables" href="/environment-variables">
    OpenCode config dirs, hook quiet/disable, and related env vars.
  </Card>
  <Card title="Contributing" href="/contributing">
    Source-of-truth under skill/ and generated harness policy.
  </Card>
</CardGroup>