---
name: dintel-bootstrap
description: Use when the user asks to "set up MCP agents", "install DTM / D.DA / OurSEO", "bootstrap a new machine", "check my MCP agent health", "fix MCP setup", "run agent doctor", mentions "dintel-bootstrap", "dintel-auth install", or wants to register the three D.intelligence custom agents (dtm-agent, dda, ourseo) into ~/.claude/settings.json, verify their prerequisites (1Password signin, gcloud ADC), and confirm each server responds to MCP initialize. Also triggered when a user moves to a new machine, after agent updates, or when MCP agents stop responding.
version: 1.0.0
allowed-tools: Read, Bash, AskUserQuestion
---

# dintel-bootstrap — D.intelligence MCP Agent Installer & Doctor

This skill installs and verifies the three D.intelligence custom MCP agents
(**DTM**, **D.DA**, **OurSEO**) on the user's machine. It wraps the
`dintel-bootstrap` CLI from the `dintel-auth` package — cloning and installing
that package if it is not yet present.

## When to Use

| Situation | Skill Action |
|-----------|--------------|
| New machine setup | Clone `dintel-auth`, run `doctor`, run `install` |
| Existing install | Run `doctor`; install only what is missing |
| MCP agent stopped working | Run `doctor`; report root cause |
| User changes 1Password items or GA property | Re-run `install --force` with updated profile |

## Prerequisites (non-negotiable)

The skill verifies these before touching any config:

1. **1Password CLI** (`op`) installed and signed in — required for OurSEO.
2. **gcloud** Application Default Credentials present — required for D.DA.
3. **Python 3.10+** — required to install `dintel-auth`.
4. **uv** (`~/.local/bin/uv` or on PATH) — recommended for editable install.

If any are missing, STOP and tell the user. Do not proceed with workarounds.

## Workflow

```dot
digraph flow {
  "User request" [shape=doublecircle];
  "Check prereqs" [shape=diamond];
  "dintel-auth installed?" [shape=diamond];
  "Clone + uv pip install -e ." [shape=box];
  "Run doctor --agent all" [shape=box];
  "All green?" [shape=diamond];
  "Run install --agent all" [shape=box];
  "Restart Claude Code" [shape=box];
  "Done" [shape=doublecircle];

  "User request" -> "Check prereqs";
  "Check prereqs" -> "Done" [label="missing → stop"];
  "Check prereqs" -> "dintel-auth installed?" [label="ok"];
  "dintel-auth installed?" -> "Clone + uv pip install -e ." [label="no"];
  "dintel-auth installed?" -> "Run doctor --agent all" [label="yes"];
  "Clone + uv pip install -e ." -> "Run doctor --agent all";
  "Run doctor --agent all" -> "All green?";
  "All green?" -> "Done" [label="yes"];
  "All green?" -> "Run install --agent all" [label="no"];
  "Run install --agent all" -> "Restart Claude Code";
  "Restart Claude Code" -> "Done";
}
```

## Step 1 — Prerequisites Check

Run these, stop on first failure:

```bash
which op                      # must exist
op whoami                     # must succeed (sign in via Touch ID if not)
test -f ~/.config/gcloud/application_default_credentials.json
python3 --version             # >= 3.10
which uv || true              # optional but preferred
```

If `op whoami` fails, tell the user: **"Open the 1Password desktop app, authorize
Touch ID, then run `op signin` in your own terminal. I cannot trigger Touch ID
from a subprocess."**

If ADC is missing: **"Run `gcloud auth application-default login` in your own
terminal to set up Application Default Credentials."**

## Step 2 — Install `dintel-auth` If Missing

```bash
test -x ~/Project/dintel-auth/.venv/bin/dintel-bootstrap || {
  test -d ~/Project/dintel-auth || \
    git clone <dintel-auth repo url> ~/Project/dintel-auth
  cd ~/Project/dintel-auth
  uv venv
  uv pip install -e .
}
```

The `dintel-bootstrap` CLI is then at
`~/Project/dintel-auth/.venv/bin/dintel-bootstrap`.

## Step 3 — Doctor First

Always run doctor before install. It is read-only and tells you exactly what is
wrong:

```bash
~/Project/dintel-auth/.venv/bin/dintel-bootstrap doctor --agent all
```

Exit code 0 = all green. Non-zero = at least one check failed. The output
prints a per-agent pass/fail table including:

- binary exists + executable
- 1Password refs resolve (for OurSEO)
- gcloud ADC present (for D.DA)
- MCP `initialize` handshake succeeds

## Step 4 — Install Only What Is Needed

If any agent is missing from `~/.claude/settings.json`:

```bash
# Dry-run first — show what will change
~/Project/dintel-auth/.venv/bin/dintel-bootstrap install --agent all --dry-run

# Apply
~/Project/dintel-auth/.venv/bin/dintel-bootstrap install --agent all
```

If an agent is registered with a different spec than the profile, the command
fails safely. Re-run with `--force` after confirming with the user.

## Step 5 — Restart Claude Code

MCP server definitions are loaded at Claude Code startup. Tell the user: **"Quit
and relaunch Claude Code to pick up the new MCP servers."**

## Common Failure Modes

| Symptom | Root Cause | Fix |
|---------|------------|-----|
| `op whoami` returns "not signed in" | 1P session expired / biometric not authorized | User runs `op signin` interactively |
| `resolve GOOGLE_CSE_API_KEY` times out | 1P session expired mid-check | Same as above |
| `MCP initialize handshake` timeout for ourseo | `op run` hanging waiting for 1P auth | Same as above |
| `MCP initialize handshake` fails for dda | `gcloud` ADC missing or expired | `gcloud auth application-default login` |
| `binary exists` fails | Agent repo not cloned or venv missing | Clone the agent repo and run its own install script |
| "exists with different config" on install | User edited settings.json manually | Inspect diff, then `install --force` if profile is correct |

## Scope Boundaries

This skill does **NOT**:

- Clone or install the three agent repos (`dintel-gtm-agent`,
  `dintel-data-agent`, `our-seo-agent`). Each has its own install script — run
  those first.
- Modify project-scoped `.mcp.json` files. Only `~/.claude/settings.json` is
  touched.
- Store secrets. All sensitive values stay in 1Password and are resolved at
  MCP launch time via `op run`.
- Trigger interactive authentication. Touch ID, browser OAuth, etc. must be
  handled by the user in their own terminal.

## References

- `dintel-auth/src/dintel/bootstrap/` — Python implementation
- `dintel-auth/src/dintel/bootstrap/profiles/{dtm,dda,ourseo}.json` — declarative MCP specs
- `~/.claude/settings.json` — the target file (symlink)
- `~/.claude.json` — runtime state, **not** the MCP config location