install-grimoire

name	install-grimoire
description	Use when the user wants to install or uninstall grimoire skills by domain or individual skill, upgrade grimoire to the latest version, clean up broken symlinks, list what skills are available, or run a health check on the grimoire installation.
source	Package manager UX patterns (Homebrew, npm, apt); grimoire scripts/grimoire
tags	["uninstall","upgrade","clean","doctor","health","diagnostics","skills","setup"]

Install Grimoire

Install, uninstall, or upgrade grimoire skills — a guided interface over the grimoire CLI.

Why This Is Best Practice

Adopted by: Every major package manager (Homebrew, npm, apt, pip) provides a guided CLI with confirmation prompts before destructive operations and clear output of what was changed. The pattern of "show command → confirm → execute → report" is universal because it prevents silent failures and makes installs auditable. Impact: Silent install failures (wrong path, broken symlink, permission error) are the primary cause of "the skill isn't working" confusion. Explicit confirmation before uninstall and clear post-install reporting (what was installed, where, how many) eliminates the ambiguity. Homebrew's brew install output format — listing each installed path — is the gold standard for install UX. Why best: Running grimoire directly requires knowing the exact flags. A guided skill extracts intent from natural language ("install the engineering skills for Claude"), constructs the correct command, confirms before running, and surfaces the result in plain language.

Sources: Homebrew documentation; npm CLI documentation; grimoire CLI

Steps

Step 1: Detect operation

User signal	Operation
"install", "add", "set up"	install
"uninstall", "remove", "delete"	uninstall
"upgrade", "update", "get latest skills"	upgrade
"clean", "fix broken links"	clean
"list", "what's available", "show domains"	list
"doctor", "health check", "status", "is everything working"	doctor
"init", "initialize project", "create settings"	init
"update grimoire binary", "upgrade grimoire CLI", "self-update"	self-update
"add registry", "remove registry", "list registries", "manage skill sources"	registry
"list presets", "what presets are available", "show presets"	preset-list
"wizard", "setup wizard", "interactive setup", "guided setup"	wizard
"set up MCP", "configure Claude Code", "connect to AI assistant", "MCP"	mcp-setup

---

Step 2: Gather parameters

For install and uninstall, determine scope:

# Install all skills
grimoire install                                                        # installs everything

# Install one domain
grimoire install --domain engineering                                   # only engineering skills

# Install one subdomain
grimoire install --domain engineering --subdomain development           # one subdomain

# Install one skill
grimoire install --skill engineering/development/apply-kiss-principle   # one skill

For install, also determine target agent:

grimoire install --domain engineering --target all      # all detected agents (default)
grimoire install --domain engineering --target claude   # Claude Code only
grimoire install --domain engineering --target codex    # Codex only
grimoire install --domain engineering --target gemini   # Gemini CLI only

Install mode — symlink (default) vs copy:

grimoire install --domain engineering                   # symlink (default) — updates automatically on grimoire update
grimoire install --domain engineering --copy            # copy files — use when symlinks are unsupported (e.g. some CI, Windows without admin)

Copy-mode installs write a .grimoire-managed marker inside each skill directory. Grimoire uses this marker to safely identify and remove its own copies during uninstall and clean — it will never delete a directory it didn't create.

If scope or target is ambiguous, ask one question before proceeding.

---

Step 3: Show command and confirm

Construct the grimoire command and show it before running. Use a platform-aware confirm:

• Claude Code: use AskUserQuestion — options: "Continue (Recommended)" and "Cancel"
• OpenCode: use question — same schema as AskUserQuestion
• Gemini CLI: use ask_user — type: "confirm"
• All other platforms: show the block below and wait for [y/n]

Install example (other platforms):

Will run:
  grimoire install --domain engineering --target claude

This will install all engineering skills (~101 skills) to Claude Code.
Continue? [y/n]

For uninstall, flag it explicitly (same platform-aware confirm — Claude Code/OpenCode/Gemini CLI use their native tool):

Will run:
  grimoire uninstall --domain business --target all

This will REMOVE all business skills from all agents. Cannot be undone without re-installing.
Continue? [y/n]

For upgrade (same pattern):

Will run:
  grimoire update

This will pull the latest grimoire from GitHub and refresh all symlinks.
Continue? [y/n]

For init (no confirmation needed — non-destructive):

grimoire init                                     # current directory
grimoire --project-dir /path/to/project init      # specific directory

For self-update (check-only by default, confirm before applying):

Will run:
  grimoire self-update --yes

This will replace the grimoire binary with v1.2.3.
Continue? [y/n]

For registry operations:

grimoire registry list                                      # no confirmation needed
grimoire registry add <name> <url>                          # confirm before cloning (owner/repo, git URL, or local path)
grimoire registry remove <name>                             # confirm — deletes local clone
grimoire registry update                                    # confirm if changes expected
grimoire registry update <name>                             # update one registry
grimoire registry set <ref>                                 # set official registry to a fork/mirror; run grimoire update after
grimoire registry reset                                     # revert official registry to default (grimoire-hub)
grimoire registry validate [path]                           # validate registry structure before publishing

For preset-list:

grimoire preset list                                        # no confirmation needed

For wizard:

grimoire wizard                                             # interactive setup — guides through registry, profile, and settings

---

Step 4: Execute

Run the confirmed command via Bash. Stream or capture output.

---

Step 5: Report result

Partial-failure handling: After running the install command, verify each requested component installed successfully. If some domains installed and others failed:

1. List what succeeded and what failed with error reason
2. Do not report 'installation complete' if any component failed
3. Offer retry for failed components: 'Retry failed installs? [y/n]'
4. If a domain fails due to network/permission error vs. not-found error, distinguish them — not-found means the domain name is wrong; network/permission means retry may work.

Terminal conditions:

• Max retries: 2 per failed component
• After 2 failures: mark component as FAILED, continue with remaining components
• Error type routing:
  • 404 / not found / unknown domain: wrong name — do NOT retry; ask user to verify the domain name
  • network timeout / 503: transient — retry up to 2×
  • 403 / permission denied: stop retrying; output manual install command: grimoire install --skill [failed-component]
  • Any other error: retry once; if still failing, mark FAILED and continue

✅ Installed 101 skills from engineering domain to Claude Code.

Installed at: ~/.claude/skills/

Domains installed:
  engineering/development        (18 skills)
  engineering/architecture       (12 skills)
  engineering/testing            (9 skills)
  ... (and 8 more sub-domains)

For upgrade:

✅ Grimoire upgraded to latest.

  Previous: commit abc1234 (2026-05-01)
  Current:  commit def5678 (2026-06-09)

  New skills: 14
  Updated skills: 7
  Symlinks refreshed: 202

For list:

Show available domains and skill counts. For subdomain or skill scope, show names.

For doctor:

Run grimoire doctor directly (read-only, no confirmation needed). Output shows 3 sections:

Grimoire health check

  Source
    ✅  git repo:    /path/to/grimoire (commit abc1234, 2026-06-09)
    ✅  grimoire:  executable

  Installed skills
    ✅  claude:   312 skills, 0 broken symlinks
    ⚠️   codex:    88 skills, 3 broken symlinks  → run: grimoire clean --target codex
    ⬜  gemini:  (not detected — skipped)

  Config
    ✅  project personal (.grimoire/settings.local.toml) — present, valid TOML
    ⬜  project shared (.grimoire/settings.toml) — not found
    ⬜  global (~/.config/grimoire/settings.toml) — not found

  Summary: 1 warning.

For full ground truth beyond health check, run grimoire context — it shows resolved settings, active profiles with expanded skills, compliance status, and all structural findings in one output.

For init:

✅ Grimoire initialized.

  Created: /path/to/project/.grimoire/settings.toml
  Profile: engineering (auto-detected)

  Next steps:
    1. Ask your AI to run /check-best-practice-compliance
    2. Run grimoire check to see your compliance score

For self-update: output shows current/latest version and upgrade status. For registry: output shows each registry name, URL, skill count, and operation result.

Step 6 (mcp-setup): Configure MCP server

After successful install, offer MCP setup:

Connect grimoire to your AI assistant natively via MCP? This lets the AI call grimoire
tools automatically at session start without manual commands. [y/n]

If yes, determine the target assistant (ask if ambiguous), then run:

grimoire mcp config --target <assistant>
# Supported: claude, cursor, windsurf, cline

Show the printed config snippet and guide the user to add it to their assistant's MCP config file.

If the AI assistant runs outside the project root (common with desktop apps like Claude Code Desktop), pin the project directory so grimoire reads the right settings and compliance reports:

{
  "mcpServers": {
    "grimoire": {
      "command": "grimoire",
      "args": ["--project-dir", "/absolute/path/to/project", "mcp", "serve"]
    }
  }
}

Alternatively via environment variable: GRIMOIRE_PROJECT_DIR=/absolute/path/to/project.

Confirm that a restart is needed. Once connected, all 29 grimoire MCP tools are available (see configure-grimoire for the full list).

For uninstall: also offer to remove the MCP server config block if the user is fully removing grimoire.

---

When NOT to Use

• Changing preferences or settings: use configure-grimoire or pin-best-practice-preference.
• Resolving skill conflicts: use resolve-best-practice-conflict.
• Writing a new skill: use write-best-practice-skill.

Common Mistakes

Uninstalling instead of upgrading: if the user says "update my skills," that almost always means --upgrade (refresh to latest), not --uninstall. Confirm the intended operation before running.

Wrong target agent: defaulting to --target all is usually correct, but if the user only uses one agent, installing to all wastes disk space with unused symlinks. Ask if ambiguous.

Skipping confirmation on uninstall: always show the uninstall command and warn it's destructive before running. Never auto-run uninstall without explicit user confirmation.