Andrew Yim
2667304bca
New Claude Skill that wraps the `dintel-bootstrap` CLI from the dintel-auth package to install and diagnose the three D.intelligence custom MCP agents (DTM, D.DA, OurSEO) in ~/.claude/settings.json. Triggers on: "set up MCP agents", "install DTM/D.DA/OurSEO", "run MCP doctor", "bootstrap a new machine", "my MCP agents stopped working". Scope boundaries: - Only registers existing agent installs (does NOT clone agent repos) - Only touches ~/.claude/settings.json (does NOT modify .mcp.json) - Does NOT store secrets; OurSEO profile uses op run wrapper - Does NOT trigger interactive auth; prompts user to run op signin Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
165 lines
6.4 KiB
Markdown
165 lines
6.4 KiB
Markdown
---
|
|
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
|