Effortless install: a one-stop install skill every migration skill relies on

[miguel-sanchez-elastic]

Problem

Installation is our first impression and it's currently a cliff. Every migration skill assumes the CLI is already installed; when it isn't, the agent fails with a confusing "command not found" instead of helping. Install friction was the single biggest blocker in dogfooding (e.g. the default Python on macOS is too old). There's no single place that owns "get the tool working", so install guidance is duplicated and inconsistent across skills.

Why now

Installation is a prerequisite for literally every other skill — including the new discovery skill that will start sending first-time users our way. If we're about to increase top-of-funnel traffic, the very first step has to be smooth, or we lose people before they migrate anything. Fixing it once, in a skill every other skill defers to, removes the most common reason a migration never starts.

User stories

• As a first-time user, when the tool isn't installed, the agent offers to set it up for me instead of erroring out.
• As a user on a fresh machine, I get install guidance that already accounts for the common gotchas (wrong Python version, missing extras) so I don't get stuck.
• As a user who only cares about Grafana (or only Datadog), I'm guided to install exactly what I need, not everything.
• As a maintainer, I update install guidance in one place and every skill stays correct.

What we'll ship

• A dedicated install skill that owns getting obs-migrate working and verified, covering the gotchas that actually bite people (Python version, source-specific extras, the Kibana tooling path).
• A reliable "is it installed?" handoff so all existing migration skills detect a missing CLI and route to this skill instead of failing.
• Simpler existing skills: duplicated install instructions are removed and defer to the one source of truth.
• A clear "you're ready" verification step so users know setup succeeded before they invest in a migration.

Implementation note: the skill is mirrored across .claude/skills/ and .cursor/skills/ per AGENTS.md (edit both in lockstep, with the path-prefix caveat).

Success criteria

• A user starting from nothing can reach a verified, working install entirely through the agent.
• Triggering any migration skill without the CLI installed leads to help, not a "command not found" dead end.
• Install guidance lives in exactly one place; other skills point to it rather than repeating it.
• Users are guided to the right footprint for their source (Grafana-only, Datadog-only, or both).

Out of scope

• Docker-based installation.
• Windows support (not currently tested or supported).
• Version upgrade / migration-between-versions flows.

Dependencies

• None blocking — this is foundational and unblocks the others.
• Confirm the real, supported distribution path (repo checkout vs. published/internal package) before documenting an install command, given the internal no-public-publish guardrail. Use docs/command-contract.md (Install And Setup) as the source of truth.

Open questions

• Is there an officially supported install path we want to standardize on (and document), or do we describe the repo-checkout path only for now?
• Do we want the install skill to also cover credential/target setup, or keep that separate (connect-to-o11y-source already exists)?

[shmsr]

Implemented in PR #331 (branch docs/pypi-install-live):

Answers to open questions

1. Install path: standardize on PyPI elastic-observability-migration via uvx (recommended) or persistent pip — not repo-checkout-only. Git tag fallback remains for offline/PyPI-unreachable cases. Never @main.
2. Credentials: kept separate in connect-to-o11y-source (install skill stops at Ready/list-samples).

What shipped

• New skill install-obs-migrate (mirrored .claude / .cursor / .agents) owns doctor, extras ([all]/[grafana]/[datadog]), Python/uv gotchas, Ready checklist.
• All other migration skills now defer to it via a short Prerequisites (install) block instead of duplicating install commands.
• Live-verified: uvx --from '…[all]|[grafana]|[datadog]==0.4.0rc1' obs-migrate doctor.

Happy to close this issue when #331 merges, or keep open until we add an automated “CLI missing → route to install skill” description-trigger check if you want that as a follow-up.