# Install dowsing for an AI agent

Install the CLI first, then the optional Agent Skill for the agent that is
currently running. Review each command before executing it. Do not pipe
downloaded code into a shell.

## 1. Run the CLI

dowsing needs Node.js `^22.18.0 || >=24.11.0` and nothing else. There is no
install step at all if you are happy to run it through npx:

```sh
npx -y dowsing --help
```

To install it into the project you are working in, so that repeated calls skip
the download:

```sh
npm install --save-dev dowsing
```

Do not replace an existing installation without the user's permission.

Verify, in a git repository with real history:

```sh
npx -y dowsing hotspots --top 5 --json
```

That must print JSON and exit 0. If `meta.git.shallow` is `true`, the checkout
is shallow and every metric is degraded — fetch the full history first
(`git fetch --unshallow`, or `fetch-depth: 0` in CI).

## 2. Install the Agent Skill

The CLI works on its own. The Skill teaches an agent when to reach for dowsing
and — the part `--help` cannot carry — how to read the numbers it returns, and
what not to claim from them.

GitHub CLI 2.90 or newer is preferred, because it records provenance and can
update the Skill later:

```sh
gh skill preview yhay81/dowsing dowsing
gh skill install yhay81/dowsing dowsing --agent AGENT --scope user
```

Replace `AGENT` with the current host. Common values are `claude-code`,
`codex`, `cursor`, `github-copilot`, `opencode`, `cline`, `kiro-cli`, and
`windsurf`. Use `universal` only when the host is unknown.

If `gh skill` is unavailable:

```sh
npx skills add yhay81/dowsing --skill dowsing --agent AGENT --global --yes
```

The canonical, reviewable Skill source is
<https://github.com/yhay81/dowsing/tree/main/skills/dowsing>.

## 3. Tell this repository's agents about it

The Skill is installed per host, so it only reaches agents belonging to whoever
installed it. A line in `AGENTS.md` travels with the repository instead, and is
read by every agent that works in it, whatever the host:

```sh
npx -y dowsing init          # appends a dowsing section to AGENTS.md
npx -y dowsing init --dry-run   # see what it would write first
```

Ask the user before writing to a file they track in git.

## 4. Confirm discovery

Confirm that the host lists a Skill named `dowsing`. Restart the agent if it only
discovers Skills at startup. Then, in a fresh task, ask where to refactor first:
the agent should choose dowsing, read `dowsing --help`, run `hotspots --json`, and
report the ranking with the analysis conditions attached (time window, excluded
commits) rather than as bare numbers.