>cat/works/agent-tooling/README.md

AIエージェント(Claude Code・Codex等)から自然言語で呼び出せる、構造化出力対応のCLIツール群です。--json フラグで stdout に JSON、stderr に進捗ログを分離して返し、エラー時も code と hint を含む構造体で返却するため、エージェントが結果のパースや自動リトライまで行えます。各パッケージには Claude Code Skill (skills/<name>/SKILL.md) を同梱しており、npm install -g した瞬間からエージェントが自動認識し、自然言語で呼び出せるようになります。

収録ツール

sitesnap — ローカル UI の撮影・検証 CLI

AIエージェントや開発者がローカル UI を撮って・測って・直すための Playwright ベース CLIです。shot（単発撮影）→ check（overflow / console / a11y の合否）→ inspect（要素の数値検証）の開発ループを主用途とし、sitemap からの一括キャプチャやポートフォリオ用のサイト集めにも使えます。出力は JSON + PNG 構成でDB不要。site / page のアーカイブは meta.json を Astro 等の静的サイトジェネレーターから読み込んで公開ポートフォリオに統合できるスキーマを備えています。

撮影前の DOM 操作として --click / --eval / --label で CSS タブや <details> など状態違いを撮り分け、--allow-file で file:// モックをサーバなしで直撮りできます。状態違いを撮り分ける際は --label が必須です（未指定だと同名で上書き）。

Playwright のブラウザコンテキストに prefers-reduced-motion: reduce を送信し、全要素の animation/transition を 0.001s に短縮するCSSを自動注入することで、AOSや wow.js 等のスクロール連動アニメによる撮影漏れを抑えます。それでも真っ白な場合は --force-visible で強制表示。失敗ページは retry で再取得、doctor でキャプチャ結果を診断し再取得案やエージェント向け調査票を生成できます。

コマンド	用途
sitesnap site <sitemap-url>	sitemapから全URL展開 → 全ページキャプチャ
sitesnap page <url>	単一ページのみキャプチャ
sitesnap shot <url>	開発検証用の単発スクリーンショット（ビューポート・要素・フルページ）。--device / --settle でデバイス指定や入場アニメ待機、--out / -o で出力先指定にも対応
sitesnap inspect <url>	要素の computed style・寸法・テキスト・overflow 量を JSON で取得（--props で追加 CSS プロパティ取得可）
sitesnap check <url>	横はみ出し・console エラー・失敗リクエスト・axe-core a11y の合否レポート
sitesnap list	キャプチャ済みサイト一覧（--shots で shot を列挙）
sitesnap clean [host]	溜まった shot を削除（アーカイブには触れない。--older-than / --dry-run 対応）
sitesnap help	ヘルプ表示
sitesnap open <domain>	サイトのフォルダを Finder で開く（macOS）
sitesnap retry <domain>	失敗したページのみ再取得
sitesnap doctor <run-dir>	キャプチャ結果を診断（--agent-task で調査票生成）

出力は sites/<domain>/meta.json にページ一覧と画像パスを、runs/latest/result.json に最新 run の診断サマリを保存します。shot はアーカイブ用の site / page と違い meta.json を更新しません。--out / --out-file を指定しない限り既定の保存先は OS キャッシュ（$XDG_CACHE_HOME/sitesnap、なければ ~/.cache/sitesnap）配下の <host>/shots/（localhost はポートごと、file:// は _file/）で、--out <dir> や -o <path> で任意の出力先にも書けます。list --shots と clean はこの shot 保存先を参照します。shots/ は使い捨て領域で自動削除されないため、clean で明示的に掃除します。--limit --exclude --strict --allow-private などのフラグで取得範囲や CI 向け厳格モードを制御できます。

pdfmint — HTML/Markdown to PDF/PNG

HTML / Markdown を綺麗な日本語PDF（＋任意のPNG）に変換する Puppeteer ベースのCLIです。AIエージェントが生成した原稿を、提出・共有しやすい成果物へコマンド一発で変換することを目的に設計。--json でメタ情報（出力パス・ファイルサイズ・ページ数・処理時間）を構造化出力します。

Markdown入力時は GFM（表・タスクリスト等）に加え、フロントマター除去・脚注・GitHub callout（> [!NOTE] 等）・シンタックスハイライトにも対応。--font sans（既定）で Noto Sans JP、--font serif で Noto Serif JP を同梱フォントとして読み込み、環境差なく同じ見た目で出力。--css でスタイルを固定、--format --margin --landscape --no-background といった用紙オプションに加え、batch で一括変換、--png で高解像度PNG同時生成（--viewport / --scale で解像度指定）、--expect-pages でページ数の品質チェックが可能です。

色・書体・余白・用紙サイズは brand.md（./pdfmint.brand.md → ~/.config/pdfmint/brand.md の順に自動探索）に一度書いておけば Markdown 変換すべてに適用され、毎回フラグ指定が不要です。--brand で明示指定、--no-brand で無効化できます。

コマンド	用途
pdfmint convert <input> <output>	単一HTML/Markdown→PDF（推奨）
pdfmint <input> <output>	上記と同じ（互換 alias）
pdfmint batch <pattern> <out-dir>	バッチ処理（出力名の衝突は変換せず BATCH_OUTPUT_COLLISION で報告）
pdfmint doctor	環境診断

共通設計

• AIエージェントファースト: stdoutにJSON / stderrに進捗ログを分離し、エラーは code + hint 構造体で返してリトライしやすくする
• Bun開発・Node.js配布: bun src/cli.ts でローカル開発しつつ、dist/cli.js として Node.js 22+ 環境に配布するハイブリッド構成
• Claude Code Skill 同梱: パッケージ内に skills/<name>/SKILL.md を含めることで、npm install -g 直後にClaude Codeが自動認識
• DB不要: sitesnap は JSON + PNG、pdfmint は PDF + 任意PNG として成果物をファイル保存

技術スタック

カテゴリ	ツール	選定理由
言語/ランタイム	TypeScript / Bun / Node.js 22+	開発はBunで高速、配布はNode.jsで広い互換性を確保
ブラウザ自動化	Playwright (sitesnap) / Puppeteer (pdfmint)	スクショ精度とPDF印刷品質、それぞれの目的に最適なものを選定
エージェント連携	Claude Code Skill / --json 出力 / AGENTS.md	パッケージ同梱の SKILL.md で自然言語呼び出しを実現
配布	npm (@hayashiii スコープ)	単一コマンドでグローバルインストール可能
開発パッケージマネージャ	Bun	高速インストールと TypeScript 直接実行で開発体験を向上