diff --git a/custom-skills/94-dintel-bootstrap/.claude-plugin/plugin.json b/custom-skills/94-dintel-bootstrap/.claude-plugin/plugin.json new file mode 100644 index 0000000..68f689d --- /dev/null +++ b/custom-skills/94-dintel-bootstrap/.claude-plugin/plugin.json @@ -0,0 +1,24 @@ +{ + "name": "dintel-bootstrap", + "version": "1.0.0", + "description": "Install and verify D.intelligence custom MCP agents (DTM, D.DA, OurSEO) in ~/.claude/settings.json. Bootstraps a new machine or diagnoses a broken install. Delegates to the `dintel-bootstrap` CLI from the dintel-auth package; clones and installs dintel-auth if missing.", + "author": { + "name": "D.intelligence", + "email": "dev@dintelligence.co.kr" + }, + "keywords": [ + "bootstrap", + "mcp", + "dtm", + "dda", + "ourseo", + "claude-code", + "install", + "doctor", + "authentication", + "1password", + "gcloud", + "setup" + ], + "license": "MIT" +} diff --git a/custom-skills/94-dintel-bootstrap/README.md b/custom-skills/94-dintel-bootstrap/README.md new file mode 100644 index 0000000..3c5950f --- /dev/null +++ b/custom-skills/94-dintel-bootstrap/README.md @@ -0,0 +1,51 @@ +# 94-dintel-bootstrap + +**Claude Skill for installing and verifying D.intelligence custom MCP agents.** + +Wraps the `dintel-bootstrap` CLI (shipped in the `dintel-auth` Python package) +so Claude Code can install, verify, and diagnose the three custom MCP agents +used across D.intelligence work: + +| Agent | Role | +|-------|------| +| **DTM** (`dtm-agent`) | Google Tag Manager tag/trigger/variable management | +| **D.DA** (`dda`) | Google Analytics 4 + Search Console analytics | +| **OurSEO** (`ourseo`) | SEO crawler, audit, KG/CSE search, schema tools | + +## Activation Triggers + +The skill activates automatically when the user says things like: + +- "Set up MCP agents on this machine" +- "Install DTM / D.DA / OurSEO" +- "Run MCP doctor" +- "My MCP agents stopped working" +- "Bootstrap a new laptop" + +## What It Does + +1. Checks prerequisites (`op`, `gcloud` ADC, Python 3.10+, `uv`). +2. Installs `dintel-auth` if not already present. +3. Runs `dintel-bootstrap doctor --agent all` (read-only diagnosis). +4. On failure, runs `dintel-bootstrap install --agent all` to repair + `~/.claude/settings.json`. +5. Prompts the user to restart Claude Code. + +## What It Does NOT Do + +- **Does not install the three agent repos themselves.** Each has its own + install script (`install` / `setup.sh` in the agent's repo). Run those + first; this skill only registers existing installs in MCP config. +- **Does not modify project-scoped `.mcp.json` files.** Only touches + `~/.claude/settings.json`. +- **Does not store secrets.** All sensitive values remain in 1Password; + the OurSEO profile uses `op run` to inject them at MCP launch time. +- **Does not trigger interactive auth.** `op signin`, `gcloud auth login`, + and Touch ID confirmations must happen in the user's own terminal. + +## Related + +- `dintel-auth` — the Python package that owns the `dintel-bootstrap` CLI and + the MCP profile JSONs. +- `91-multi-agent-guide` — multi-agent collaboration framework (different + scope: project-level agent coordination, not machine bootstrap). diff --git a/custom-skills/94-dintel-bootstrap/skills/dintel-bootstrap/SKILL.md b/custom-skills/94-dintel-bootstrap/skills/dintel-bootstrap/SKILL.md new file mode 100644 index 0000000..a62665c --- /dev/null +++ b/custom-skills/94-dintel-bootstrap/skills/dintel-bootstrap/SKILL.md @@ -0,0 +1,164 @@ +--- +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 ~/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