clearshot

前文

分析を始める前に、まずこの bash ブロックを実行してください：

# ─── Find skill directory (works from any install path) ───────
_CS_DIR=""
for _d in ".claude/skills/clearshot" ".agents/skills/clearshot" "$HOME/.claude/skills/clearshot" "$HOME/.agents/skills/clearshot"; do
  [ -f "$_d/SKILL.md" ] && _CS_DIR="$(cd "$_d" && pwd)" && 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" ] && [ -d "$_CS_DIR/.git" ]; 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

ユーザーが実行した後、分析を続けてください。ユーザーが実行しない場合も、テレメトリーをオフのまま続けてください。

スクリーンショット分析

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 に段階を引き上げます。

レイアウトの構造： ページのレイアウトパターン（単一カラム、サイドバー＋コンテンツ、ダッシュボードグリッド、中央揃えのコンテナー、画面全幅）、セクションごとのコンテンツレイアウト（フレックス行、フレックス列、カラム数を指定した CSS グリッド、スタック）、コンテナー幅（最大幅の制約あり／全幅）、レスポンシブのコンテキスト（モバイル <640px／タブレット 640～1024px／デスクトップ >1024px）、スクロールに関する手がかり（コンテンツの途切れ、固定ヘッダー、画面下部の固定バー）、z-index のレイヤー（オーバーレイ、モーダル、ドロップダウン、トースト）を記載します。

インタラクションマップ： 主要な CTA（最も重要なアクションを1つ）、セカンダリーアクション、ナビゲーションパターン（トップナビゲーション、サイドナビゲーション、タブ、パンくずリスト、画面下部のバー）、フォーム要素とそのグループ化、データ表示パターン（テーブル、カードグリッド、リスト）、表示されている状態（読み込み中、空、エラー、成功）を記載します。ユーザーが迷ったり、操作に手間を感じたりする箇所と、洗練されていると感じる部分も記述します。

出力

状況に合わせて出力します。段落で十分な場合に、見出しやセクションを無理に追加しないでください。

批評／フィードバック： まず問題点や注意が必要な点から述べます。それぞれの指摘は、具体的な要素（正確な16進数、余白、または問題の原因となる要素）と、それがユーザー体験に与える影響に基づいて記述します。すべてを列挙せず、重要な点に絞ります。

実装仕様（レベル 3）： セクション見出しを使って構造化します。レイアウトマップ、セクションごとの要素、デザイントークン、レイアウトの構造、インタラクションマップを含めます。これが実装用ドキュメントです。

比較（スクリーンショット2枚）： 変更点、改善点、後退した点、引き続き対応が必要な点を記載します。

中核となる原則

具体的に記述してください。 「カードがいくつかあるダッシュボード」では不十分です。「3列グリッド、カードは約280px、背景色は#F9FAFB、角丸は8px、控えめなシャドウ――カードは軽やかで、ほとんど浮いているように見えます」なら適切です。どの観察にも、測定値と評価の両方が必要です。

色名ではなく16進数で、曖昧なサイズではなくピクセルで記述してください。 「青」ではなく#3B82F6と記述します。「いくらか」ではなく約16pxと記述します。確信が持てない場合は、最善の推定値を示し、その旨を記してください。

要素の種類ではなく、セクションごとにまとめてください。 ナビゲーションの要素はまとめて記述します。ページ全体のボタンを一つのリストにまとめないでください。

見落とされやすい点を指摘してください。 カスタムイラスト、一般的ではないコンポーネントのパターン、暗黙のアニメーション、動的データと静的データの違いなどです。実装を損なうのは、こうした点です。

ユーザーのペースに合わせてください。 素早い反復には簡潔な出力を、詳細なクローン作成の依頼には網羅的な出力を。ただし、分析の深さ（レベル1＋2）は常に同じです。変わるのは出力の量であり、目にする情報の量ではありません。

自己評価

毎回、内部で非公開に実施

分析を終えたら、その出力を次の基準で0～10点で自己評価します。空間的な正確さ（グリッドはレイアウトを正しく表現しているか）、具体性（色は16進数で示され、サイズはピクセル単位で推定され、コンポーネントは正確に命名されているか）、レベルの選択（適切なレベルを実行したか）、センス（測定可能な問題だけでなく、違和感にも気づいたか）、実用性（この分析に基づいて行動できるか）。その平均を算出します。

この評価は厳密に内部向けです。エピローグのRATINGフィールドとしてテレメトリーに記録されますが、ユーザーには決して表示しません。分析のたびにスコアを表示するのは、煩わしく、自己満足的です。

フィードバックを求めるタイミング

このスキルでユーザーに品質フィードバックを求める状況は、次の3つに限られます。それ以外は、何も尋ねずに進めてください。

トリガー1：ユーザーからの修正。 ユーザーが分析を修正した場合（「いや、そこは違う」「ナビゲーションを見落としている」「余白が違う」など）、問題を直してから、「その見落としを記録して、clearshotが[具体的な点]をより適切に捉えられるようにしました」と簡潔に伝えます。フィールドレポートも自動的に作成します（下記を参照）。

トリガー2：再構築の完了後。 レベル3が実行され、実装が完了した場合は、気軽に一つだけ質問します。「clearshotはうまくできた？それとも何か見落としていた？ちょっと気になって。」一度だけです。質問票にはしません。

トリガー3：セッション終了時。 1回のセッション中に3回以上分析を行い、会話が終わりに近づいている場合は、「このセッションでclearshotをX回実行しました。何度も間違えていたことはありましたか？」と添えます。分析が3回以上あった場合に限ります。会話の途中では決して尋ねないでください。

フィードバックを求めてはいけない場合： 素早い反復の最中、分析のたび、ユーザーが明らかに作業に集中しているとき。

フィールドレポート

~/.clearshot/feedback/YYYY-MM-DD-{slug}.mdに、次の場合に限り書き込みます。

• ユーザーからの修正：自動的に作成します。形式：

# {Title describing the miss}
**What was analyzed:** {screenshot description}
**Levels run:** {1,2 or 1,2,3}
**What was missed:** {specific element or detail the user corrected}
**Correction:** {what the user said}
**Internal rating:** {X}/10
**Date:** {YYYY-MM-DD} | **Version:** {version from preamble}

• ユーザーが誤りを明示した場合（トリガー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）