1仕組みと動作原理
本バッチの中でも珍しい「実コードを伴う」スキルです。SKILL.mdの核となる指示は1つだけで、SKILL.mdが存在するディレクトリで `python3 -m scripts <絶対パス>` を実行することであり、すべての圧縮ロジックは同梱されたPythonパッケージ内に実装されています。
skills/caveman-compress/SKILL.md
The compression scripts live in `scripts/` (adjacent to this SKILL.md). If the path is not immediately available, search for `scripts/__main__.py` next to this SKILL.md. 2. From the directory containing this SKILL.md, run: python3 -m scripts <absolute_filepath>
ここでの処理内容：「LLMによる圧縮」を再実行可能なCLIとしてパッケージ化しています。scripts/__main__.pyはわずか2行（from .cli import main; main()）で構成され、cli.pyが引数・存在・型の検証を行った後、compress.pyのcompress_file()を呼び出します。
圧縮処理はファイル本文をClaudeに送信して行われます。Anthropic SDK（ANTHROPIC_API_KEYが必要）を優先し、利用できない場合はローカルの `claude --print` CLIサブプロセス（デスクトップのユーザー認証を使用）にフォールバックします。
skills/caveman-compress/scripts/compress.py
api_key = os.environ.get("ANTHROPIC_API_KEY") if api_key: try: import anthropic client = anthropic.Anthropic(api_key=api_key, timeout=CLAUDE_CALL_TIMEOUT_SECONDS) msg = client.messages.create( model=os.environ.get("CAVEMAN_MODEL", "claude-sonnet-4-5"),
決定的な証拠：これが本スキル唯一の外部ネットワーク出口です。フォールバック処理は固定引数リストを使用しstdin経由でプロンプトを渡すため、シェルは介在しません（claude_bin = shutil.which("claude") or "claude"、argsは [claude_bin, "--print", "--setting-sources", "", "--strict-mcp-config"]）。モデルはCAVEMAN_MODELで上書き可能（デフォルトはclaude-sonnet-4-5）。1回の呼び出しタイムアウトは LOCK_WAIT_SECONDS/(MAX_RETRIES+1) = 300秒です。
コードブロックはモデル送信前に解読不能なマーカーへ置換され、復元時に「各マーカーが厳密に1度だけ出現する」ことを検証します。違反した場合は書き込み全体を拒絶します。これは圧縮によるコマンド破損を防ぐ中核メカニズムです。
skills/caveman-compress/scripts/compress.py
def restore_code_blocks(text: str, blocks: List[Tuple[str, str]]) -> str: """Restore markers exactly; fail closed if model removed, copied, or altered one."""
マーカー形式は @@CAVEMAN_PRESERVED_CODE_<n>_<sha256の先頭16文字>@@（CODE_MARKER_PREFIX）です。入力自体にこのプレフィックスが含まれる場合は直ちにValueErrorとなり、復元後に未知のマーカーが残留している場合も拒絶されます。モデルに許可されているコードブロック操作は「そのままの配置」のみで、内容の改変はできません。
書き込み完了後も処理は終わりません。構造バリデータ（validate.py）が見出し、コードブロック、URL、パス、箇条書き、インラインコードを原文と圧縮稿で比較検証し、失敗した場合はエラー箇所のリストをClaudeに渡して「指摘されたエラーのみ修正」を最大2回再試行します。
skills/caveman-compress/scripts/validate.py
validate_headings(orig, comp, result) validate_code_blocks(orig, comp, result) validate_urls(orig, comp, result) validate_paths(orig, comp, result) validate_bullets(orig, comp, result) validate_inline_codes(orig, comp, result)
極めて厳密な検証：見出しテキストの改変はエラー（文内アンカーリンクの破損を防ぐため）、単なるレベルの変更は警告とみなされます。4スペースインデントのコードブロックも照合対象です（コメントでは `kubectl delete pod --all -n prod` が `-n dev` に改変されて検証を通過しユーザーファイルを上書きしてしまう反例が挙げられています）。圧縮稿はまず <file>.caveman-staged に書き出され、検証通過後に初めて実ファイルに上書きされます。
書き込みは「事前バックアップ、読み戻し検証、アトミック置換、権限ビットおよび改行スタイルの保持」という一連のチェーンで行われ、過去のデータ消失障害の修正を反映した実装となっています。
skills/caveman-compress/scripts/compress.py
write_bytes_atomic(backup_path, original_raw) if backup_path.read_bytes() != original_raw: print(f"❌ Backup write verification failed: {backup_path}")
バックアップはバイト単位の完全複製（再レンダリングではない）であり、作成後に読み戻して照合されます。write_bytes_atomicはmkstemp+fsync+os.replaceを用い、元の権限ビットを維持します（コメントではissue #655の0バイト障害に言及）。read_sourceは厳密にUTF-8デコードを行い非UTF-8は即座に拒絶し（issue #686）、多数派の行判定に基づきCRLF/LFをそのまま保持して書き戻します（issue #762）。
厳格な入力ゲートが設けられています。500KBを超えるファイル、認証情報やキーを疑わせるファイル名、空ファイルは拒絶され、既存バックアップが存在する場合は上書き防止のため中断されます。
skills/caveman-compress/scripts/compress.py
MAX_FILE_SIZE = 500_000 # 500KB
機密ファイル名の拒絶リスト（SENSITIVE_BASENAME_REGEX）は .env*、.netrc、credentials*、secret(s)*、password(s)*、id_rsa/ed25519、authorized_keys、*.pem/key/p12/pfx/crt/cer/jks/keystore/asc/gpg などを網羅。パス要素やトークン正規化マッチング（.ssh/.aws/.gnupg/.kube/.docker、api-keys → apikeys など）も備えます。コメントでは「これらを圧縮するとAnthropic API（サードパーティのデータ境界）に生バイトを送信することになる」と理由が明記されています。
並行処理制御にはOSネイティブのファイルロック（POSIX fcntl.flock / Windows msvcrt.locking）が用いられ、ロックキーはバックアップパスのsha256先頭16文字です。ロック非対応のファイルシステムでは警告を出して非協調実行にフォールバックし、ロックディレクトリやロックファイル内のシンボリックリンクは拒絶されます。
skills/caveman-compress/scripts/compress.py
return _state_base_dir("locks") / f"{digest}.lock"
LOCK_WAIT_SECONDS = 900（コメントにて最悪ケースの実行時間：MAX_RETRIES+1回の呼び出し × 300秒より長く設定する必要があると説明）。EOPNOTSUPP/ENOSYSは「ファイルシステム非対応」として警告出力後に処理を継続しますが、ENOLCKは意図的に除外されています（一時的なロック枯渇の可能性があり、誤判定により競合発生時にロックなしで実行されるのを防ぐため）。
非膨張不変条件：frontmatterを除いた本文ベースで比較し、圧縮結果は原文より厳密に短くなければならず、満たさない場合は元ファイルを変更せず処理を中止します。この規則は修復パスにも適用されます。
skills/caveman-compress/scripts/compress.py
if not _is_smaller_than_body(compressed_body, body): print(" Original file is untouched (no backup created).") return False
コメントにてissue #776に言及：旧バージョンでは構造のみ検証していたため、より長くなった「圧縮」結果でも通過して原文を上書きしていました。frontmatterは個別に分離され、そのまま結合されます（モデルによるfrontmatter改変を防ぐため）。
圧縮対象はdetect.pyの拡張子ホワイトリスト/ブラックリストと、拡張子のないファイルに対する内容スニッフィングによって判定されます。.original.md バックアップが二重に圧縮されることはありません。
skills/caveman-compress/scripts/detect.py
COMPRESSIBLE_EXTENSIONS = {".md", ".mdc", ".txt", ".markdown", ".rst", ".typ", ".typst", ".tex"}
SKIP_EXTENSIONSは py/js/ts/json/yaml/toml/env/lock/css/html/go/sh などを除外します。拡張子がない場合はshebang（→code）、JSON/YAML判定（→config）、コード行比率40%超（→code）を確認し、それ以外をnatural_languageと判定します。コメント記載の通り、リスト外の拡張子はすべてunknownとなり圧縮されません（fail-closed）。
2コア機能
01自然言語のメモリファイル（CLAUDE.md / todo / preferences）をその場でcaveman文風に圧縮し、セッションごとの入力トークン消費を削減
02コードブロック、インラインコード、URL、パス、見出し、リスト構造の「そのまま保持」を保証（マスキングと検証の二重保護）
03スキルのローダーによる再読み込みを防ぐため、ソースディレクトリ外（$XDG_DATA_HOME/caveman-compress/backups/<parent-dir-name>/、Windowsでは %LOCALAPPDATA%）に自動バックアップを作成
04フェイルセーフ設計：検証失敗 → 最大2回のピンポイント修復再試行 → それでも失敗した場合はエラーを出力し元ファイルを無変更で保護（作成されたバックアップもクリーンアップ）
05機密ファイルの事前拒絶：認証情報、秘密鍵、PIIを含むと疑われるファイル名は読み込み前に拒絶（サードパーティAPIへデータを送信しない）
06並行処理の安全性：同一対象ファイルに対するクロスセッション相互排他制御（OSネイティブロック + 900秒待機とタイムアウト時の明確な通知）
07徹底した互換性配慮：CRLF/LFの維持、権限ビットの保持、アトミック書き込み（中断時の0バイトファイル化防止）、厳密なUTF-8検証（不正バイトのサイレント破棄を防止）
08ベンチマークツールの同梱：benchmark.pyがtiktoken（任意インストール）を使用してオリジナルと圧縮版のトークン削減率を計算し、同一の検証テストを実行
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| api | Anthropic Messages API（经 anthropic Python SDK） |
| cli | claude CLI（Claude Code / Claude desktop 认证） |
| package | anthropic（Python SDK，可选） |
| package | tiktoken（可选，仅 benchmark.py） |
| cli | python3（运行时不带第三方依赖；仅标准库 contextlib/errno/hashlib/os/re/shutil/stat/subprocess/tempfile/time/pathlib，Windows 用 msvcrt、POSIX 用 fcntl） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: python3 -m scripts <absolute_filepath>（SKILL.mdで指定された唯一の実行手段）
- 网络端点: 外部ネットワークアクセスの宣言: anthropic SDK（client.messages.create）経由でのAnthropic APIアクセス（ANTHROPIC_API_KEY 設定時のみ）
- 本地工作目录: ファイルI/Oおよび成果物出力: 対象ファイル自体（圧縮後の内容によるインプレース上書き）
監査ノート： 理由：① 同梱されたPythonスクリプトを実行しサブプロセスを起動するため；② ANTHROPIC_API_KEY 環境変数を読み取るため（認証情報の取り扱い）；③ ファイル本文をサードパーティのモデルAPI（Anthropic、外部データ境界。ソースコメントでも'third-party data boundary'と明記）に送信するため；④ ユーザーファイルをインプレースで上書きするため（バックアップ、アトミック書き込み、検証機能あり）。オプション依存として外部パッケージ（anthropic、tiktoken）を含みます。リスク緩和要因（中/低リスクへ引き下げていない理由）：shell=Trueの非使用、固定引数、機密ファイル名の事前除外、バックアップ読み戻し検証、非膨張不変条件、失敗時のロールバックを備えていますが、SECURITY.md内でSnykによるHigh Risk判定が言及されています。トリガー条件：ユーザーが明示的に /caveman-compress を実行するか、特定メモリファイルの圧縮を要求した場合にのみ上記動作が発生します。
5二重目の独立検証
- [ok] SKILL.md 提到的脚本路径与运行方式 — `python3 -m scripts <file>` 成立：scripts/__main__.py 导入 cli.main 并调用；cli.py 校验参数个数与文件存在/类型后执行 compress_file。SKILL.md 提示的 'search for scripts/__main__.py' 与实际文件名一致。
- [ok] Anthropic 为唯一网络出口 — 六个脚本中无 urllib/requests/socket/curl/wget 命中；网络仅经 anthropic SDK client.messages.create 或 claude CLI 子进程。SDK 端点在源码中未硬编码，故 external_deps.endpoint 留空（不臆测）。
- [ok] 「subprocess 无 shell 注入」这一说法 — subprocess.run([claude_bin, "--print", "--setting-sources", "", "--strict-mcp-config"], input=prompt, ...) 为列表参数 + stdin，无 shell=True；SECURITY.md 亦声明 'Does not use shell=True or string interpolation in subprocess calls'。
- [ok] 「备份在源目录之外」是否属实（SKILL.md / Purpose 段） — backup_dir_for() 返回 _state_base_dir("backups")/filepath.parent.name，其中 _state_base_dir 为 $XDG_DATA_HOME/caveman-compress 或 ~/.local/share/caveman-compress（Windows 用 %LOCALAPPDATA%），确实不在源文件旁；注释给出理由（skill auto-loader 会二次读入 .original.md）。
- [ok] 敏感文件拒绝覆盖面的自评（第一遍称「覆盖 .env/credentials/密钥」） — 逐条核对 SENSITIVE_BASENAME_REGEX 与 SENSITIVE_PATH_COMPONENTS/SENSITIVE_NAME_TOKENS：.env*、.netrc、credentials*、secret(s)*、password(s)*、id_rsa/dsa/ecdsa/ed25519(.pub)、authorized_keys、known_hosts、*.pem|key|p12|pfx|crt|cer|jks|keystore|asc|gpg；路径组件含 .ssh/.aws/.gnupg/.kube/.docker 与 credential(s)/secret(s)；名字 token 含 secret/credential/password/passwd/apikey/accesskey/token/privatekey。属启发式 denylist（可被改名绕过），已在 analysis 注记，未夸大。
- [ok] 固定大小上限 500KB — compress_file 内 MAX_FILE_SIZE = 500_000 且在任何 API 调用之前检查；SECURITY.md 亦声明 'Files larger than 500KB are rejected before any API call is made'。
- [ok] 「校验不过则原文件不动」 — 压缩候选先写 <file>.caveman-staged 并对其跑 validate；只有 is_valid 才 _write_target(filepath, ...)，两次重试用尽后 unlink 暂存与备份并打印 'Failed after retries: original left untouched'。
- [ok] SKILL.md 压缩规则 vs 脚本提示词是否一致（有无文档吹牛） — SKILL.md 的 Remove/Preserve/Compress 规则与 build_compress_prompt 的 STRICT RULES 同向（保代码块、保行内代码、保 URL、保标题、保路径命令），脚本还把「不要给整体套一层 ```markdown 围栏」写进提示词，并有 strip_llm_wrapper 兜底剥离。无夸大。
6結論
最適な用途： 毎セッション読み込まれるメモリファイル（CLAUDE.md、TODO、設定等）を長期管理しており、コンテンツがAnthropic APIを経由することに同意できるチームや個人に最適です。特に入力トークン削減のためcavemanスタイルを導入済みのユーザーに適しています。同一ファイルを繰り返し編集・更新する環境において、外部バックアップと非膨張不変条件が意図しないファイル破壊リスクを大幅に低減します。
不向きな用途： 以下には適していません：① 認証情報、顧客データ、コンプライアンス対象データを含むファイル（本文がサードパーティAPIへ送信されます）；② Anthropicの認証情報やclaude CLIがない環境（スクリプトが失敗します）；③ 完全な「意味の無損失」圧縮を求める用途（構造のみが厳密に保持されます）；④ コードや設定ファイルの圧縮（許可リスト外は拒絶されます）；⑤ 500KBを超えるドキュメント。なお、明示的に /caveman-compress を実行した場合にのみ動作し、自動的にファイルを圧縮することはありません。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload caveman-compress.tar.gz
sha256:
Option B · Copy Guide for Agent52e12dda463f9c55…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 15581d1400.