utility-setup

Utility Setup

Installs three components that make every Claude session — including spawned agent worktrees — automatically aware of available utilities:

1. SessionStart hook — injects a compact utility index at the start of every session so agents know what skills and tools exist before planning any task. Fires deterministically (not probabilistic).

2. UserPromptSubmit hook — keyword-matches each incoming message and emits a 1-line skill hint when relevant. Silent otherwise — zero noise when no match.

3. codebase-nav skill — a project-level growing library of pre-built search patterns. Common grep/find tasks become one tool call instead of five. Grows automatically as new patterns are discovered.

Instructions

Step 1: Create hooks directory

mkdir -p ~/.claude/hooks

Step 2: Write session-bootstrap.sh

Create ~/.claude/hooks/session-bootstrap.sh:

#!/bin/bash
# Injected at every session start (including agent worktrees).
# Outputs compact utility index before Claude plans any task.

CWD=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
AGENT_COUNT=$(find "$CWD/.claude/agents" -name "*.md" \
  -not -name "README*" 2>/dev/null | wc -l | tr -d ' ')
HAS_REFS=$([ -d "$CWD/.claude/refs" ] && echo "yes" || echo "no")
HAS_NAV=$([ -f "$CWD/.claude/skills/codebase-nav/SKILL.md" ] \
  && echo "yes" || echo "no")

cat <<EOF
<utility-index>
Available utilities — check BEFORE writing custom bash/grep/scripts.
Rule: if a skill covers your task, invoke it via the Skill tool first.

Global skills: github-cli · gstack · review · investigate · ship · qa
  careful · guard · learn · office-hours · freeze · canary · checkpoint
  document-release · land-and-deploy · retro · design-review · health

Global tools: ~/.claude/tools/atlassian (Jira/Confluence, no MCP)
  ~/.claude/skills/gstack/bin/ — QA/browser CLI tools
EOF

if [ "$HAS_NAV" = "yes" ]; then
  echo "Codebase search: codebase-nav skill — pre-built grep patterns"
fi

if [ "$HAS_REFS" = "yes" ]; then
  REFS=$(ls "$CWD/.claude/refs/"*.xml 2>/dev/null \
    | xargs -I{} basename {} .xml | tr '\n' ' · ' | sed 's/ · $//')
  echo "Refs (.claude/refs/): $REFS"
fi

if [ "$AGENT_COUNT" -gt 0 ] 2>/dev/null; then
  echo "Agents (.claude/agents/): $AGENT_COUNT specialist agents"
fi

cat <<EOF

Project skills (.claude/skills/): check directory for available skills
</utility-index>
EOF