mcpField
F
file-handler

file-handler

github.com/paulnsorensenエージェントワークフロー156 回インストール今日更新
リポジトリ

file-handler について

file-handler は、作業ファイルを共有の `.skillz` ディレクトリに保存、取得、検索するためのスキルです。3 つのサブコマンドを備えたスクリプトで、保存名も検証します。

主な機能

  1. 01引数または標準入力から保存
  2. 02保存済みファイルの読み取り
  3. 03タイトルと本文の検索
  4. 04タイプとファイル名の検証
  5. 05SKILLZ_DIR による保存先変更

活用シーン

  1. 01別のスキル用に草稿や計画を保存
  2. 02以前の作業メモを取得
  3. 03スキル間の一時ファイルを検索

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/paulnsorensen/skillz-that-grillz --skill file-handler

インストール後、Claude Code で/file-handlerを入力して読み込まれたか確認します。

同梱ファイルscripts/skillz.sh

詳細

file-handler

このリポジトリ内のすべてのスキルで共通の、ディスク上の規約です。

.skillz/
└── <type>/
    └── <slug>

<type> は成果物を目的別（note、plan、draft、log など）に分類します。<slug> はファイル名です。どちらも検証されます。パス区切り文字、..、先頭のドットは使用できないため、スキルはユーザーが指定したスラッグをサニタイズせずにそのまま渡せます。

このスキルの使い方

別のスキルで作業ファイルを保存または読み込む必要がある場合は、scripts/skillz.sh をシェルから実行します。次の3つのサブコマンドで必要な操作をカバーします。

# write content to .skillz/<type>/<slug>
scripts/skillz.sh save_file note todo "things to do"

# write stdin (preferred for multi-line content)
some_command | scripts/skillz.sh save_file plan release-cut

# read it back
scripts/skillz.sh get_file note todo

# search by title and body, optionally narrowed to a type
scripts/skillz.sh search_files todo
scripts/skillz.sh search_files release --type plan

save_file は成功時に解決済みのパスを出力するため、呼び出し元はそのパスをユーザーに提示できます。対象ファイルや一致項目が存在しない場合、get_file と search_files は終了コード1で終了するため、スキル側で || を使って処理を分岐できます。

保存先のルート

デフォルトでは、ツリーは $PWD/.skillz に配置されます。セッション単位またはリポジトリ単位の場所にしたい場合は、SKILLZ_DIR で上書きします。

SKILLZ_DIR="$HOME/.local/share/skillz" scripts/skillz.sh save_file note hello "hi"

これらの成果物をコミットしない場合は、リポジトリの .gitignore に .skillz/ を追加してください。

呼び出し元の規約

  • 種類を一度決めたら、再利用してください。 成果物ごとに新しい <type> を作らないでください。種類は分類用の箱です（note、plan、draft、log、transcript）。一意にするのはスラッグです。
  • スラッグには、ASCIIのファイル名として安全な文字を使います。 使用可能な文字：[A-Za-z0-9._-]（英字、数字、ドット、アンダースコア、ハイフン。kebab-case が推奨されますが、拡張子用のドットと大文字も使用できます）。それ以外の文字は終了コード2で拒否されます。
  • 拡張子は必須ではありませんが、追加すると（.md、.txt、.json）、ユーザーがファイルを直接開く際に便利です。
  • 複数行の内容では、インラインの内容引数よりも標準入力を優先してください。引用符の扱いがすぐに複雑になります。
  • このスキルを使って、追跡対象のソースファイルを書き込まないでください。 これはスキル用の一時作業領域であり、プロジェクトツリーではありません。

サブコマンドのリファレンス

save_file <type> <slug> [content]

.skillz/<type>/<slug> に書き込みます。content を省略すると、標準入力から読み込みます。親ディレクトリは必要に応じて作成されます。解決済みのパスを出力します。引数が無効な場合は終了コード2です。

get_file <type> <slug>

.skillz/<type>/<slug> の内容を標準出力に出力します。ファイルが存在しない場合は終了コード1、引数が無効な場合は終了コード2です。

search_files <query> [--type <type>]

2段階で検索します。

  1. タイトル — 保存先のルート全体（または --type が指定された場合はその種類のみ）を対象に、大文字と小文字を区別しない find -iname "*<query>*" で検索します。
  2. 本文 — 同じ範囲を対象に、同じクエリを grep -rIn で検索します。バイナリファイルはスキップされます。

出力はセクション（## titles、続いて ## bodies）に分かれています。本文の検索結果は標準的な <path>:<line>:<text> 形式なので、エディターから該当箇所に移動できます。どちらの段階でも結果が見つからない場合は、終了コード1です。

このスキルを共通化する理由

共通の規約がないと、作業状態の保存が必要な各スキルがそれぞれ独自の方法（~/.cache/<skill>/、/tmp/<skill>-*、$PWD 内の隠しファイルなど）を作りがちです。その結果、ユーザーがファイルを探す場所が分散し、スキルをまたぐワークフロー（「前のターンで作成したプラン」など）も難しくなります。.skillz/<type>/<slug> と3つの動詞に一本化することで、ツールキット全体を小さく保てます。

このスキルを使わない場合

  • アプリケーションコード、設定ファイル、またはGitで追跡されるもの。 それらは直接編集してください。このスキルはスキル用の一時作業領域です。
  • シークレット。 .skillz/ はローカルディスク上に平文で保存されます。代わりにシークレットマネージャー（1Password、Bitwarden、age）を使用してください。
  • マシン間の同期。 ファイルはローカルファイルシステムにのみ保存されます。別の場所でも必要な場合は、手動でコピーするか、明示的にコミットしてください。
  • 大きなバイナリファイル。 本文の検索ではバイナリファイルはスキップされますが、この保存形式は大きな成果物向けに最適化されていません。

注意事項

  • SKILLZ_DIR は一度だけエクスポートされるのではなく、呼び出し時に取得されます。 シェルコマンドを実行するたびに再解決されるため、呼び出しの間に環境変数を変更すると、保存先のルートも変わります。
  • スラッグの検証ではスペースが拒否されます。 release cut ではなく、release-cut を指定してください。正規表現は上記に記載されています。
  • 本文の検索には固定文字列マッチング（grep -F）を使用します。 特殊文字（.、*、[）はそのまま文字として照合されます。意図的な仕様です。v1.2.3 を検索すると、正規表現としてではなく、入力したとおりの文字列が検索されます。
  • ロック機構はありません。 2 つのスキルが同じ <type>/<slug> に同時に書き込むと競合し、最後に書き込んだ内容が残ります。並行して作業する場合は、異なるスラッグを使用してください。

コメント

Markdown 対応