setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# ax:setup

Install and verify ax - the local agent-experience graph. After this skill
the user has the `ax` CLI on PATH, an ingested local graph (embedded DuckDB,
no daemon to run or watch), and the ax skills loaded into Claude Code.

This skill is intentionally narrow: install + verify only. For day-to-day
use see `ax:retro` (experiment loop), `ax:extract-workflow` (reconstruct
the recipe behind a shipped artifact), or run the CLI directly.

## When to fire

Trigger phrases:
- "install ax" / "set up ax" / "first-time ax setup"
- "ax not found" / "where is axctl"
- "ax doctor" / "is ax running" / "is ax working"
- "what does ax give me"

Do NOT auto-trigger on unrelated work or when the user is already deep in
an ax workflow (`ax improve list`, `ax recall …`).

## Install

```bash
# 1. Download the installer and inspect it before executing. Review the target
#    paths first; this repository does not publish a checksum for install.sh.
(
    set -eu
    ax_install_dir="$(mktemp -d "${TMPDIR:-/tmp}/ax-install.XXXXXXXX")"
    trap 'rm -f "$ax_install_dir/install.sh"; rmdir "$ax_install_dir"' EXIT
    curl -fsSL https://raw.githubusercontent.com/Necmttn/ax/main/install.sh -o "$ax_install_dir/install.sh"
    less "$ax_install_dir/install.sh"
    read -r -p "Execute this installer? [y/N] " answer
    case "$answer" in
        [yY][eE][sS]|[yY]) bash "$ax_install_dir/install.sh" ;;
        *) echo "Installer not run."; exit 1 ;;
    esac
)
```

Continue only after the installer completes successfully. A failed download,
failed review command, declined approval, or end of input stops installation.
Agents inspect the downloaded file and obtain approval before executing that
same file. The private directory prevents another local user replacing it.

```bash
# 2. Review the skill changes and confirm before installing into the selected
#    agent skill directory. Omit -g unless a global install is intentional.
npx skills add Necmttn/ax -a codex

# 3. First ingest - seeds the graph from the user's last 7 days of
#    Claude Code + Codex transcripts.
PATH="$HOME/.local/bin:$PATH" ax ingest --since=7
```

If any step fails, run `ax doctor --json` and surface the blocker. If
`ax` itself isn't found after step 1, the user probably has a custom
shell rc - tell them to add `$HOME/.local/bin` to PATH.

## Verify

```bash
ax --version              # expect axctl v0.1.x
ax doctor --json          # expect ok: true for cache + skills
ax skills taste --limit=5 # rank top skills - proof the graph populated
```

Specific failure modes:
- `cache` check fails / no successful ingest recorded → run `ax ingest`.
  There is no daemon to start - the graph is a published DuckDB snapshot,
  rebuilt on demand. A stale graph also self-heals: any DB-backed command
  forks a debounced background `ax ingest` on its own (`AX_NO_AUTO_INGEST=1`
  to opt out).
- Zero skill invocations after ingest → user has a different Claude
  transcripts path. Set `AX_TRANSCRIPTS_DIR` and re-ingest.

## Label skills ax can't classify (do this for the user)

ax tags skills with *roles* (e.g. framing, execution, verification) so
`ax skills weighted` ranks by usage × role, not raw count. A skill the user
invokes ≥3× with no role is "unclassified" - ax hands each one back to YOU as a
task brief to fill. This is the core agent-in-the-loop step; don't skip it.

```bash
ax skills classify        # writes .ax/tasks/classify-<skill>.md per unclassified skill
```

For each brief written:
1. Read the skill (its SKILL.md / what it does) and the brief's evidence.
2. Fill the YAML frontmatter at the top of the brief: `primary_role:` (required,
   one label), plus optional `secondary:`, `confidence:` (0–1), `rationale:`.
   Run `ax roles` to see labels already in use; reuse them when they fit.
3. Apply + check:

```bash
ax skills lint            # reads filled briefs → writes plays_role edges
ax skills weighted        # the re-ranked list, now role-weighted
```

If `classify` reports "no unclassified skills", the user hasn't used enough yet -
say so and revisit after a few days (re-run `ax ingest`, or let the
freshness drive top it up automatically). One-off override without a brief:
`ax skills tag <skill> <role>`.

Also surface the config front door when relevant:
- `ax skills config` - skill lifecycle (live / orphan / out-of-scope / parked).
- `ax hooks config` - hooks across claude/cursor/codex/opencode (+ add/remove/edit).
- `ax hooks init` - scaffold `~/.ax/hooks` for authoring custom TypeScript guards (`defineHook` from `@ax/hooks-sdk`); validate with `ax hooks backtest` before `ax hooks install`.
- `ax agents config` - agent definitions and the skills they scope.

After the first ingest completes, show the user where their model spend goes -
this is the fastest "aha" in the product:

```bash
ax cost split --days=7       # main loop vs subagents, by model
ax dispatches --candidates   # dispatches that could run on cheaper models
```

If the candidates list is non-empty, point at the routing loop: the

From Necmttn/ax, AGPL-3.0.

More from Necmttn/ax