tool-hooks-doctor

Q: How do I install tool-hooks-doctor?

Run npx skills add https://github.com/heyvhuang/ship-faster --skill tool-hooks-doctor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tool-hooks-doctor/ (personal) or .claude/skills/tool-hooks-doctor/ (project).

by heyvhuangMarketing & SEO

Detect whether Claude Code evolution hooks are installed/enabled, and print a copy-paste fix. Use when you expect runs/evolution artifacts but nothing is being written. Triggers: hooks, evolution, runs/evolution, settings.json, PreToolUse, PostToolUse.

Installs: 49
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/heyvhuang/ship-faster --skill tool-hooks-doctor

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads tool-hooks-doctor automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Hooks Doctor (Claude Code)

Goal: quickly verify whether Claude Code hooks for skill-evolution are installed and enabled.

This is an atomic diagnostic tool used by other workflows so they can warn early when the evolution loop is not active.

Scope

Applies to: Claude Code hook installation / configuration
Does not apply to: Cursor/OpenCode/etc that do not support Claude-style hooks

What "healthy" looks like

Hook scripts exist at:

~/.claude/skills/skill-evolution/hooks/

Settings enable the hooks in either:

Project settings: <repo_root>/.claude/settings.json
Or global settings: ~/.claude/settings.json

A session produces artifacts under:

<project_root>/runs/evolution/<run_id>/...

Check (read-only)

Run these checks and report status as: OK / PARTIAL / MISSING.

1) Are the hook scripts installed?

ls -la ~/.claude/skills/skill-evolution/hooks/ 2>/dev/null || true

Required files:

pre-tool.sh
post-bash.sh
post-tool.sh
session-end.sh

If missing: user must install/update the skill-evolution skill first.

2) Are hooks enabled in settings?

Check both locations:

test -f .claude/settings.json && echo "project settings: .claude/settings.json" || true
test -f ~/.claude/settings.json && echo "global settings: ~/.claude/settings.json" || true

grep -n "skill-evolution/hooks/pre-tool.sh" .claude/settings.json ~/.claude/settings.json 2>/dev/null || true
grep -n "skill-evolution/hooks/post-bash.sh" .claude/settings.json ~/.claude/settings.json 2>/dev/null || true
grep -n "skill-evolution/hooks/post-tool.sh" .claude/settings.json ~/.claude/settings.json 2>/dev/null || true
grep -n "skill-evolution/hooks/session-end.sh" .claude/settings.json ~/.claude/settings.json 2>/dev/null || true

Interpretation:

If none of the grep checks match: hooks are not enabled.
If only some match: configuration is PARTIAL and should be fixed.

3) Quick runtime smoke test (optional)

If user confirms, run a harmless bash command in the project and then check:

ls -la runs/evolution 2>/dev/null || true

Fix (write; require confirmation)

If hooks are not enabled, recommend installing project-level hooks (safer than global).

Before applying, tell the user exactly which file will be written:

Project-level: <repo_root>/.claude/settings.json (recommended)
Global: ~/.claude/settings.json

Then wait for explicit confirmation.

Install project-level hooks (recommended)

python3 - <<'PY'
import json
from pathlib import Path

settings = Path('.claude') / 'settings.json'
settings.parent.mkdir(parents=True, exist_ok=True)

data = {}
if settings.exists():
    data = json.loads(settings.read_text() or '{}')
if not isinstance(data, dict):
    data = {}

hooks = data.get('hooks')
if not isinstance(hooks, dict):
    hooks = {}

desired = {
  'PreToolUse': [{
    'matcher': 'Bash|Write|Edit',
    'hooks': [{'type':'command','command':'bash ~/.claude/skills/skill-evolution/hooks/pre-tool.sh'}]
  }],
  'PostToolUse': [
    {
      'matcher': 'Bash',
      'hooks': [{'type':'command','command':'bash ~/.claude/skills/skill-evolution/hooks/post-bash.sh "$TOOL_OUTPUT" "$EXIT_CODE"'}]
    },
    {
      'matcher': 'Write|Edit',
      'hooks': [{'type':'command','command':'bash ~/.claude/skills/skill-evolution/hooks/post-tool.sh "$TOOL_OUTPUT" "$EXIT_CODE"'}]
    }
  ],
  'Stop': [{
    'matcher': '',
    'hooks': [{'type':'command','command':'bash ~/.claude/skills/skill-evolution/hooks/session-end.sh'}]
  }]
}

def has_command(arr, matcher, command):
    for item in arr:
        if not isinstance(item, dict):
            continue
        if item.get('matcher') != matcher:
            continue
        hs = item.get('hooks')
        if not isinstance(hs, list):
            continue
        for h in hs:
            if isinstance(h, dict) and h.get('command') == command:
                return True
    return False

for event, items in desired.items():
    arr = hooks.get(event)
    if not isinstance(arr, list):
        arr = []
    for it in items:
        cmd = it['hooks'][0]['command']
        if not has_command(arr, it['matcher'], cmd):
            arr.append(it)
    hooks[event] = arr

data['hooks'] = hooks

if settings.exists():
    backup = settings.with_suffix(settings.suffix + '.bak')
    backup.write_text(settings.read_text())

settings.write_text(json.dumps(data, indent=2, ensure_ascii=True) + '\n')
print('Installed hooks into:', settings)
PY

Install global hooks (optional)

Same as above, but write to ~/.claude/settings.json.

FAQ

What does the tool-hooks-doctor skill do?

How do I install tool-hooks-doctor?

Run npx skills add https://github.com/heyvhuang/ship-faster --skill tool-hooks-doctor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tool-hooks-doctor/ (personal) or .claude/skills/tool-hooks-doctor/ (project).

Which AI agents can use tool-hooks-doctor?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is tool-hooks-doctor safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains tool-hooks-doctor?

It is published by heyvhuang in heyvhuang/ship-faster. It has 49 recorded installs.

More from heyvhuang/ship-faster

View all →

mcp-stripe

heyvhuang/ship-faster

Stripe MCP transaction operations skill. Execute transaction operations via Stripe MCP server (https://mcp.stripe.com): customer management, products/prices, invoices, payment links, subscriptions, refunds, dispute handling, balance queries. Triggers: user requests Stripe operations including create customer, create product, create invoice, generate payment link, query transactions, process refunds, manage subscriptions, view disputes, check balance, etc.

Backend & APIs747 installs

mcp-supabase

heyvhuang/ship-faster

Execute database operations via Supabase MCP (query/write/migration/logs/type generation). Triggers: query/statistics/export/insert/update/delete/fix/backfill/migrate/logs/alerts/type generation. Does not trigger for: pure architecture discussion or code planning. Write operations require confirmation; UPDATE/DELETE without WHERE is refused.

Data & Databases87 installs

review-doc-consistency

heyvhuang/ship-faster

Documentation consistency reviewer that checks alignment between code implementation and documentation. Use when user requests reviewing documentation vs code consistency, checking if README/docs are outdated, verifying API documentation accuracy. Applicable for (1) reviewing README vs implementation consistency (2) checking if docs/ directory content is outdated (3) verifying API/config documentation accuracy (4) generating documentation consistency reports. Trigger words include doc review, documentation consistency, check outdated docs, verify docs.

Docs & Writing66 installs

tool-ast-grep-rules

heyvhuang/ship-faster

Write AST-based code search and rewrite rules using ast-grep YAML. Create linting rules, code modernizations, and API migrations with auto-fix. Use when the user mentions ast-grep, tree-sitter patterns, code search rules, lint rules with YAML, AST matching, or code refactoring patterns.

Code Quality & Workflow65 installs

tool-openclaw

heyvhuang/ship-faster

Help users install, configure, operate, and migrate OpenClaw (gateway, channels, nodes, plugins, model/auth setup). Use when answering OpenClaw setup/debug questions or model migration questions; use the local docs snapshot bundled with this skill as the source of truth. Triggers: openclaw, clawdbot, clawd, clawdhub, gateway, onboard, channels login, whatsapp, telegram, discord, mattermost, pairing, nodes, sandboxing, tailscale, provider migration, Claude to GPT, model swap.

Code Quality & Workflow64 installs

tool-ui-ux-pro-max

heyvhuang/ship-faster

Use when you need concrete UI/UX inputs (palette, typography, landing patterns, UX/a11y constraints) to drive design or review. Searchable UI/UX design intelligence (styles, palettes, typography, landing patterns, charts, UX/a11y guidelines + stack best practices) backed by CSV + a Python search script. Triggers: UIUX/uiux, UI/UX, UX design, UI design, design system, design spec, color palette, typography, layout, animation, accessibility/a11y, component styling. Actions: search, recommend, review, improve UI.

Frontend & Design61 installs

Popular marketing & seo skills

View category →

reddit-automation

flowkit-labs/skills

Find Reddit threads where people are genuinely asking for what you offer, then draft short, genuinely helpful replies — disclosing your affiliation honestly and naming your product only when it truly answers the question. Two moves: discovery — scan the right subreddits for real needs (recommendation asks, expressed pain, competitor mentions) and rank the few threads where you can actually help; drafting — write from real experience, respect each community's self-promo rules, and keep a human in the loop to review and post. This markets on Reddit the honest way: contribute value, disclose who you are, never astroturf. Distilled from the playbook behind doany.ai's Reddit agent. Triggers on "find reddit opportunities", "reddit marketing", "reddit automation", "reply on reddit for my product", "reddit community engagement", "reddit lead gen", or any ask to turn Reddit threads into genuine, disclosed marketing replies.

Marketing & SEO1.1M installs

twitter-automation

101-skills/superpowers

Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet

Marketing & SEO880K installs

twitter-automation

magentosh/superpowers

Marketing & SEO771.7K installs

twitter-automation

qu-skills/superpowers

Marketing & SEO564.3K installs

product-launch-video

heygen-com/hyperframes

Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.

Marketing & SEO538.7K installs

twitter-automation

skills-shell/superpowers

Marketing & SEO453.7K installs

tool-hooks-doctor

Install

Install

Describe the task

Review the result

SKILL.md

Hooks Doctor (Claude Code)

Scope

What "healthy" looks like

Check (read-only)

1) Are the hook scripts installed?

2) Are hooks enabled in settings?

3) Quick runtime smoke test (optional)

Fix (write; require confirmation)

Install project-level hooks (recommended)

Install global hooks (optional)

FAQ

More from heyvhuang/ship-faster

Popular marketing & seo skills