前置き

分析を行う前に、このbashブロックを最初に実行してください：

# ─── Find skill directory (works from any install path) ───────
_CS_DIR=""
for _d in "$HOME/.claude/skills/clearshot" "$HOME/.agents/skills/clearshot"; do
  [ -f "$_d/SKILL.md" ] && _CS_DIR="$_d" && break
done
# fallback: search
[ -z "$_CS_DIR" ] && _CS_DIR="$(cd "$(dirname "$(find "$HOME/.claude" "$HOME/.agents" -name SKILL.md -path '*/clearshot/*' -print -quit 2>/dev/null)")" 2>/dev/null && pwd || echo "")"
_CS_VER=""
[ -n "$_CS_DIR" ] && [ -f "$_CS_DIR/VERSION" ] && _CS_VER="$(cat "$_CS_DIR/VERSION" | tr -d '[:space:]')"
_CS_STATE="$HOME/.clearshot"
mkdir -p "$_CS_STATE/analytics" "$_CS_STATE/feedback"

# ─── First-run detection ─────────────────────────────────────
_CS_FIRST_RUN="no"
[ ! -f "$_CS_STATE/config.yaml" ] && _CS_FIRST_RUN="yes"

# ─── Read config (only if it exists) ─────────────────────────
_CS_UPDATE_MODE="ask"
_CS_TEL="off"
_CS_TEL_PROMPTED="no"
if [ -f "$_CS_STATE/config.yaml" ]; then
  _CS_UPDATE_MODE=$(grep -E '^update_mode:' "$_CS_STATE/config.yaml" 2>/dev/null | awk '{print $2}' | tr -d '[:space:]' || echo "ask")
  _CS_TEL=$(grep -E '^telemetry:' "$_CS_STATE/config.yaml" 2>/dev/null | awk '{print $2}' | tr -d '[:space:]' || echo "off")
fi
[ -f "$_CS_STATE/.telemetry-prompted" ] && _CS_TEL_PROMPTED="yes"

# ─── Version check (only if user opted into updates) ─────────
# No network calls until config exists and user has chosen
if [ -n "$_CS_VER" ] && [ "$_CS_FIRST_RUN" = "no" ]; then
  _CS_CACHE="$_CS_STATE/last-update-check"
  _STALE=""
  [ -f "$_CS_CACHE" ] && _STALE=$(find "$_CS_CACHE" -mmin +60 2>/dev/null || true)
  if [ ! -f "$_CS_CACHE" ] || [ -n "$_STALE" ]; then
    _CS_REMOTE=$(curl -sf --max-time 5 "https://raw.githubusercontent.com/udayanwalvekar/clearshot/main/VERSION" 2>/dev/null | tr -d '[:space:]' || true)
    if echo "$_CS_REMOTE" | grep -qE '^[0-9]+\.[0-9.]+$' 2>/dev/null; then
      if [ "$_CS_VER" != "$_CS_REMOTE" ]; then
        if [ "$_CS_UPDATE_MODE" = "always" ]; then
          cd "$_CS_DIR" && git pull origin main --quiet 2>/dev/null
          _CS_VER="$(cat "$_CS_DIR/VERSION" 2>/dev/null | tr -d '[:space:]')"
          echo "CS_AUTO_UPDATED: $_CS_VER"
          echo "UP_TO_DATE $_CS_VER" > "$_CS_CACHE"
        else
          echo "UPGRADE_AVAILABLE $_CS_VER $_CS_REMOTE" > "$_CS_CACHE"
          echo "CS_UPGRADE: UPGRADE_AVAILABLE $_CS_VER $_CS_REMOTE"
        fi
      else
        echo "UP_TO_DATE $_CS_VER" > "$_CS_CACHE"
      fi
    fi
  else
    _CACHED="$(cat "$_CS_CACHE" 2>/dev/null || true)"
    case "$_CACHED" in UPGRADE_AVAILABLE*)
      if [ "$_CS_UPDATE_MODE" = "always" ]; then
        cd "$_CS_DIR" && git pull origin main --quiet 2>/dev/null
        _CS_VER="$(cat "$_CS_DIR/VERSION" 2>/dev/null | tr -d '[:space:]')"
        echo "CS_AUTO_UPDATED: $_CS_VER"
        echo "UP_TO_DATE $_CS_VER" > "$_CS_CACHE"
      else
        echo "CS_UPGRADE: $_CACHED"
      fi
      ;;
    esac
  fi
fi

# ─── Session tracking ────────────────────────────────────────
_CS_SESSION_ID="$$-$(date +%s)"
_CS_TEL_START=$(date +%s)

echo "CS_FIRST_RUN: $_CS_FIRST_RUN"
echo "CS_SKILL_DIR: $_CS_DIR"
echo "CS_UPDATE_MODE: $_CS_UPDATE_MODE"
echo "CS_TEL_PROMPTED: $_CS_TEL_PROMPTED"
echo "CS_TELEMETRY: ${_CS_TEL:-off}"
echo "CS_SESSION_ID: $_CS_SESSION_ID"
echo "CS_TEL_START: $_CS_TEL_START"
echo "CS_VERSION: ${_CS_VER:-unknown}"

前置き出力の解釈

CS_FIRST_RUNがyesの場合： これはclearshotの初回実行です — 設定ファイルがまだ存在しません。分析を行う前に、ユーザーにオンボーディングセットアップを実行するよう指示します。以下のような簡潔な説明をします：

「clearshotの初回セットアップが必要です(2つの質問、矢印キーとEnterで選択)：」

その後、以下を入力するよう指示します：! {CS_SKILL_DIR}/bin/onboarding.sh

前置き出力から実際のCS_SKILL_DIR値を使用します(例：~/.claude/skills/clearshotまたは~/.agents/skills/clearshot)。このスクリプトは更新設定とテレメトリについて質問し、設定を書き込み、数秒で完了します。

ユーザーが実行した後、分析を進めます。ユーザーが辞退した場合でも、設定がなければネットワーク呼び出しは行われないため、分析を続けます。

CS_AUTO_UPDATEDが表示される場合： スキルが自動更新されました。簡潔に言及します：「clearshotはv{version}に更新されました」と言って、分析を続けます。アクションは不要です。

CS_UPGRADEがUPGRADE_AVAILABLE <old> <new>を表示する場合： ユーザーはupdate_mode: askに設定されています。新しいバージョンが利用可能であることを伝え、対話的更新選択ツールを実行するよう指示します：

「clearshotはv{new}が利用可能です(現在v{old}を使用中)：」

その後、以下を入力するよう指示します：! {CS_SKILL_DIR}/bin/update-prompt.sh {old} {new}

このスクリプトではユーザーが「今すぐ更新」または「常に更新」を選択できます(後者は将来の自動更新モードも切り替えます)。ユーザーがスキップした場合、現在のバージョンで分析を続けます。

CS_TEL_PROMPTEDがno(ただしCS_FIRST_RUNもnoである場合)： ユーザーは設定を持っていますが、テレメトリの質問をスキップした可能性があります。以下を実行するよう指示します：

! {CS_SKILL_DIR}/bin/telemetry-setup.sh

ユーザーが実行した後、分析を進めます。ユーザーが辞退した場合、テレメトリをoffで分析を続けます。

スクリーンショット分析

LLMがスクリーンショットを見て、ピクセルから直接コード(またはフィードバックや説明)に進もうとするとき、空間的な関係性を失い、コンポーネント階層を誤読し、デザインの詳細を幻覚してしまいます。解決策は、「画像を見る」と「それについて応答する」の間に構造化された中間表現を構築することです。その中間層がこのスキルが提供するものです。

ゲートチェック

すべての画像がこのスキルを必要とするわけではありません。

何かをする前に、2つの質問を問いかけてください：

1. この画像はデジタルインターフェース？(ウェブサイト、アプリ、ダッシュボード、モックアップ、ワイヤーフレーム、Figmaエクスポート、UIコンテキストを持つCLI、表示されたページを持つブラウザDevToolsはすべて該当します。写真、ミーム、単独のチャート、プレゼンテーションスライド、ドキュメント、手書きのメモは該当しません。)

2. この会話はUIの構築、デバッグ、設計、または評価について？

3つの結果：

• どちらも真ではない：スキルを完全に終了します。通常通り応答します。このフレームワークについては言及しません。
• 画像はUIではないが、会話はUIの構築について(例：「この写真のような感じのページを作って」)：画像はスペックではなく、インスピレーション源です。それが伝えることを説明します — ムード、テクスチャ、重量感 — そして先に進みます。構造化分析はありません。
• 画像はUIであり、会話は構築/評価についてです：下記の分析レベルを進めます。

分析レベル

すべての分析は事実と美的判断を組み合わせます。別の「分析モード」や「定性モード」はありません — すべての観察は詳細(16進数値、ピクセル測定)に基づいており、さらに見た感じ(階層、重量感、統一感)を含みます。これはシニアデザイナーがどのように考えるかを反映しています：まず感覚、その後調査して理由を明らかにする、常に両方です。

レベル1：マップ(常に実行)

スクリーンショットを5×5グリッドに分割します。占有されているまたはセクション(ナビゲーション、ヒーロー、サイドバー、コンテンツ、フッター、モーダル、ドロワー、空いている領域など)が何であるか、ビューポートに対する概略的なサイズ、隣接セクションとの関係を捉えます。

表示されているすべての要素について、以下を捉えます：タイプ(ボタン、入力、カード、画像、アイコン、テキスト、リンク、トグル、ドロップダウン、タブ、バッジ、アバター、テーブル、チャートなど)、ラベル/コンテンツ(表示されているテキスト)、位置(グリッド領域と相対位置)、状態(デフォルト、ホバー、アクティブ、無効、選択、エラー、ローディング、フォーカス)、サイズ(ピクセル推定値)、背景色(16進数)、テキスト色(16進数)、境界線(表示/なし + 角丸のpx)、影(なし/小/中/大)、存在する場合はアイコン。セクション別にグループ化します。

また以下も記述します：視線がまず向かうところはどこか。レイアウトが呼吸しているか、または息苦しく感じるか。階層が明確か、または競合しているか。何が意図的に見え、何が偶然に見えるか。

レベル2：システム(常に実行)

表示されている背後にあるデザインシステムを抽出します：

色： ページ背景、カード/サーフェス背景、プライマリアクション、セカンダリ、テキストプライマリ、テキストセカンダリ/ミュート、境界線/区切り線、アクセント、破壊的、成功。すべて16進数値。パレットが統一されているか、またはちぐはぐに見えるかに注意します — 明確なシステムがあるか、それとも色が場当たり的か？

タイポグラフィ： 見出しスタイル(px単位のサイズ、ウェイト、ケース)、本文テキスト(サイズ、ウェイト、行の高さ)、キャプション/小さいテキスト、識別可能な場合はフォントファミリー。タイプスケールが意図的に見えるかに注意します — サイズは一貫して段階的か、それともランダムに跳ぶか？

スペーシングとシェイプ： スペーシングパターン(タイト4-8px / 快適12-16px / 広々24-32px+)、境界線の角丸パターン(シャープ0-2px / 微妙4-6px / 丸い8-12px / ピル形)、全体的な密度(コンパクト / 快適 / 広々)。スペーシングがセクション全体で一貫しているか、または一貫していないかに注意します。

レベル3：ブループリント(構築時にエスカレート)

このレベルは、ユーザーがスクリーンショットからUIを実装、再構築、またはクローンする必要があるときに実行されます。会話がこのスクリーンショットからのコード記述に関わるときに、LLMはレベル3にエスカレートする必要があります。

レイアウトアーキテクチャ： ページレイアウトパターン(単一列、サイドバー+コンテンツ、ダッシュボードグリッド、中央揃えコンテナ、フルブリード)、セクションごとのコンテンツレイアウト(flexrow、flex column、CSSグリッド(列数)、スタック)、コンテナ幅(max-width制約 vs フルウィドス)、レスポンシブコンテキスト(モバイル<640px / タブレット640-1024px / デスクトップ>1024px)、スクロール手がかり(カットオフコンテンツ、スティッキーヘッダー、固定ボトムバー)、z-indexレイヤー(オーバーレイ、モーダル、ドロップダウン、トースト)。

インタラクションマップ： プライマリCTA(最も重要な単一アクション)、セカンダリアクション、ナビゲーションパターン(トップナビ、サイドナビ、タブ、ブレッドクラム、ボトムバー)、フォーム要素とグループ分け、データ表示パターン(テーブル、カードグリッド、リスト)、表示される状態(ローディング、空、エラー、成功)。ユーザーが躊躇したり、摩擦を感じたりするところや、洗練されて見えるところを記述します。

出力

コンテキストに合わせて出力を合わせます。段落が適切なときに見出しとセクションを無理に使用しないでください。

批評/フィードバック： 何が間違っているか、何に注目する必要があるかで始めます。各観察を詳細(問題を引き起こしている正確な16進数、スペーシング、またはエレメント)とエクスペリエンスへの影響に基づきます。すべてをカタログ化しないでください — 重要なことに焦点を当ててください。

実装スペック(レベル3)： セクション見出し付きの構造化出力 — レイアウトマップ、セクション別要素、デザイントークン、レイアウトアーキテクチャ、インタラクションマップ。これはビルドドキュメントです。

比較(2つのスクリーンショット)： 何が変わったか、何が改善されたか、何が退行したか、何がまだ機能する必要があるか。

中核原則

具体的にしてください。 「いくつかのカードを持つダッシュボード」は決して受け入れられません。「3列グリッド、~280pxカード、#F9FAFBの背景、8pxの角丸、微妙な影 — カードは重みがなく、ほぼ浮遊している」が良いです。すべての観察には測定値と判断値の両方が必要です。

色名よりも16進数、漠然としたサイズよりもピクセル。 「青」ではなく#3B82F6と言います。「いくらか」ではなく~16pxと言います。不確実な場合は、最良の推定値を提供し、それを記述します。

要素タイプ別ではなく、セクション別にグループ化します。 ナビゲーションの要素は一緒に属します。ページ全体のすべてのボタンを1つのリストにまとめないでください。

非自明なことを指摘します。 カスタムイラスト、珍しいコンポーネントパターン、暗示されたアニメーション、動的と静的なデータ。これらは実装を破る可能性がある事柄です。

ユーザーのペースに合わせてください。 迅速なイテレーション = 簡潔な出力。詳細なクローンリクエスト = 徹底的。ただし分析の深さ(レベル1+2)は常に同じです — 変わるのは出力量ではなく、見る量です。

自己評価

内部的、沈黙の状態、毎回

分析を完了した後、これらの基準全体で出力を0-10で評価してください：空間的精度(グリッドはレイアウトを正しくマップしたか？)、特異性(色は16進数か、サイズはピクセル推定か、コンポーネントは正確に名付けられているか？)、レベル選択(正しいレベルが実行されたか？)、美的判断(測定可能に間違っているだけでなく、何が悪く見えるかを捉えたか？)、実行可能性(誰かがこの分析に基づいて行動できるか？)。スコアを平均化します。

この評価は厳密に内部的です。それは前置きのエピローグとしてRATINGフィールドでテレメトリに流れますが、ユーザーには表示されません。すべての分析の後にスコアを表示することは、ノイズが多く、自画自賛的です。

フィードバックを表面化する時

スキルがユーザーを品質フィードバックに関与させるべき正確に3つの状況があります。これ以外では、沈黙を守ります。

トリガー1：ユーザーの修正。 ユーザーが分析を修正した場合 — 「いいえ、それは間違っています」「ナビゲーションを見落としました」「パディングがオフです」— 問題を修正して、簡潔に記述します：「clearshotが[その特定のもの]をキャッチするのが上手くなるようにそのミスをログしました。」 自動的にフィールドレポートを書きます(下記参照)。

トリガー2：リビルド完了後。 レベル3が実行され、実装が完了した場合、1つのカジュアルな質問を聞きます：「clearshotは完璧だったか何か見落とした？ただ気になって。」 1回限りです。フォームではありません。

トリガー3：セッション終了時。 単一セッション内で3つ以上の分析が行われ、会話が終わりに向かっている場合、以下を追加します：「このセッションでclearshotをX回実行しました。常に間違っていることはありました？」 3つ以上の分析が発生した場合のみです。フローの途中では決して。

フィードバックをトリガーしないでください： 迅速なイテレーション中、すべての単一分析の後、またはユーザーが明らかにフローの中にいるとき。

フィールドレポート

~/.clearshot/feedback/YYYY-MM-DD-{slug}.mdに以下の場合のみ書き込みます：

• ユーザーの修正：自動。フォーマット：

# {見落とされたことを説明するタイトル}
**分析されたもの：** {スクリーンショット説明}
**実行されたレベル：** {1,2または1,2,3}
**見落とされたもの：** {ユーザーが修正した特定の要素または詳細}
**修正：** {ユーザーが何と言ったか}
**内部評価：** {X}/10
**日付：** {YYYY-MM-DD} | **バージョン：** {前置きからのバージョン}

• ユーザーが明示的に何かが間違っていると言った場合(トリガー2または3のレスポンスを経由)：ユーザーのフィードバックを含むフィールドレポートを書きます。

• 内部評価が5未満：沈黙の状態でフィールドレポートを書きます。

フィールドレポートは、うまくいった日常的な分析には書き込まれません。

エピローグ

分析が完了したら、イベントをログします。プレースホルダー変数を実際の値に置き換えます。

_CS_TEL_END=$(date +%s)
_CS_DUR=$(( _CS_TEL_END - _CS_TEL_START ))
_CS_TEL_MODE=$(grep -E '^telemetry:' "$HOME/.clearshot/config.yaml" 2>/dev/null | awk '{print $2}' | tr -d '[:space:]' || echo "off")
if [ "$_CS_TEL_MODE" != "off" ]; then
  _CS_OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
  _CS_ARCH="$(uname -m)"
  _CS_INSTALL_ID="$(printf '%s-%s' "$(hostname)" "$(whoami)" | shasum -a 256 | awk '{print $1}')"
  _CS_ID_JSON="\"$_CS_INSTALL_ID\""
  printf '{"v":1,"ts":"%s","version":"%s","os":"%s","arch":"%s","duration_s":%s,"outcome":"%s","levels_run":"%s","self_rating":%s,"installation_id":%s}\n' \
    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "CS_VERSION" "$_CS_OS" "$_CS_ARCH" \
    "$_CS_DUR" "OUTCOME" "LEVELS_RUN" "RATING" "$_CS_ID_JSON" \
    >> "$HOME/.clearshot/analytics/usage.jsonl" 2>/dev/null || true

  # Sync to Convex (rate-limited, background)
  _CS_CONVEX_URL=""
  for _csd in "$HOME/.claude/skills/clearshot" "$HOME/.agents/skills/clearshot"; do
    [ -f "$_csd/config.sh" ] && _CS_CONVEX_URL="$(grep -E '^CS_CONVEX_URL=' "$_csd/config.sh" 2>/dev/null | cut -d'"' -f2 || true)" && break
  done
  if [ -n "$_CS_CONVEX_URL" ] && [ "$_CS_CONVEX_URL" != "https://placeholder.convex.site" ]; then
    _CS_RATE="$HOME/.clearshot/analytics/.last-sync-time"
    _CS_SYNC_STALE=$(find "$_CS_RATE" -mmin +5 2>/dev/null || echo "sync")
    if [ ! -f "$_CS_RATE" ] || [ -n "$_CS_SYNC_STALE" ]; then
      _CS_CURSOR_FILE="$HOME/.clearshot/analytics/.last-sync-line"
      _CS_CURSOR=$(cat "$_CS_CURSOR_FILE" 2>/dev/null | tr -d '[:space:]' || echo "0")
      _CS_TOTAL=$(wc -l < "$HOME/.clearshot/analytics/usage.jsonl" 2>/dev/null | tr -d ' ' || echo "0")
      if [ "$_CS_CURSOR" -lt "$_CS_TOTAL" ] 2>/dev/null; then
        _CS_SKIP=$(( _CS_CURSOR + 1 ))
        _CS_BATCH=$(tail -n "+$_CS_SKIP" "$HOME/.clearshot/analytics/usage.jsonl" | head -100)
        _CS_JSON_BATCH="[$(echo "$_CS_BATCH" | paste -sd ',' -)]"
        _CS_HTTP=$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 \
          -X POST "$_CS_CONVEX_URL/telemetry" \
          -H "Content-Type: application/json" \
          -d "$_CS_JSON_BATCH" 2>/dev/null || echo "000")
        case "$_CS_HTTP" in 2*) echo $(( _CS_CURSOR + $(echo "$_CS_BATCH" | wc -l | tr -d ' ') )) > "$_CS_CURSOR_FILE" ;; esac
        touch "$_CS_RATE" 2>/dev/null || true
      fi
    fi
  fi
fi

これらのプレースホルダーを分析からの実際の値に置き換えます：

• _CS_TEL_START — 前置き出力からの値
• CS_VERSION — 前置き出力からのバージョン
• OUTCOME — 「success」「error」または「abort」
• LEVELS_RUN — 「1,2」または「1,2,3」
• RATING — 自己評価の数値(0-10)