skill-rails

Skill Rails

小規模で標準的なソースパッケージとして、単独で動作するスキルを設計し、ユーザーから依頼されたらビルドします。意味を伝える必要がある内容は文章にし、AI またはユーザーに委ねます。厳密に判定できる内容は、宣言するツールに委ねます。

作業サイクル

start or resume
 ├─ new package ──→ references/new-package.md: where the source goes, whether to keep maintenance documents, how the work will run
 └─ existing package ──→ read the project's recorded state
        │
        ▼
SOURCE  design and refine with the user, over as many passes as needed; nothing is built      § Author or change one target
        ├─ a change alters what another AI decides or does ──→ REVIEW   § Review before you conclude
        │     read it as its user would and hold it to this skill
        │     a finding ──→ fix at the owner, then REVIEW again from the entry
        │     a pass that finds nothing left to fix ──→ back to SOURCE
        │  the user asks to build or test                                § Build, test, and deliver when the user asks
        ▼
ROUTE   recorded? ── no ──→ references/delivery.md: user chooses among routes A–D ──→ record it
        │
        ▼
BUILD   source ──→ the standalone skill folder the route needs      references/build-and-test.md
        │  build or check returns ERROR ──→ stop and follow its nextAction
        │  when a test was asked
        ▼
TEST    put it in place on this machine by the route ──→ a fresh AI uses it
        │  the run falls short ──→ keep what it showed and resolve the cause at its owner; a source fix returns to SOURCE
        ▼
back to SOURCE: a later change is a source change; built and installed copies stay behind until they are rebuilt and put in place again, so say so

ユーザーがいる段階からサイクルを始めます。ユーザーが推奨される保守用ドキュメントを選択した場合、または後からその作成を依頼した場合は、references/project-docs.md を使って準備します。作成または保守に関する判断をする前に、references/skillEvolutionMethod.md（手法）の §§0–0.1 を読み、判断内容に応じてルーティングテーブルから追加のセクションを選び、§2 に従って調査の深さを決めます。生成された skillEvolutionMethod.index.json はバイト範囲の位置を示すだけであり、意味やタスクリストを定義するものではありません。

正規ソースから作業する

• 振る舞いを所有するマニフェスト、ターゲット記述子、エントリ、モジュール、リファレンス、ツール、またはレコードファイルを変更し、生成物やランタイム状態は変更しません。.skill-rails-build.json を含むフォルダーは生成物であり、手作業で編集してはいけません。
• ターゲットが実際に使用するモジュール、リファレンス、ツール、レコードファイルのみを宣言します。ビルドでは、未知のフィールド、未宣言のパス、ルート外への参照、出力の衝突があると処理を失敗させます。マニフェストのパスはマニフェストからの相対パスであり、そのディレクトリがすべてのソースパスが収まるべきルートです。記述子のファイルパスはその記述子からの相対パス、レコードの宣言された入力と出力はプロジェクトからの相対パスです。フィールドは scripts/skill-rails-cli/contracts/ のクローズドスキーマで定義されています。
• ID とパスは正確に指定します。ソースに宣言されていない要件、チェック、効果、因果関係を推測してはいけません。
• 後の判断で以前に読んだソースに依拠する前、またはそれを確定事項として報告する前に、根拠としたソースファイルを再読し、現在も有効であることを確認します。読んでからファイルに変更がない場合に限り、再読を省略できます。古くなった入力や出力によって回答が無効になる場合は、以前の回答を流用せず、最新のソースを読み直します。

1つのターゲットを作成または変更する

1. 編集前に調査します。パッケージが存在する場合は、CLI の inspect（リポジトリ操作）を使って、正確な ID でパッケージまたはターゲットを照会してから、変更する対象の所有者とその利用者を確認します。ターゲットが宣言されていないものを実際に読み取り、実行、または書き込みする場合は、その宣言を正規の所有者に追加します。
2. 取り除くべきユーザーの負担、AI またはユーザーが担うべき意味、観察可能な結果、対象外とするものを明確にします。
3. 目的を達成する最小限の形式を選び、ツールに担わせることを決める、作業を分割する、別の AI が実行できる文章を書くに従って記述します。目的、ルール、宣言、ツール、根拠の主張は、それぞれ1つの正規の所有者に集約します。
4. あるターゲットの文章が、成果物、判断、復旧、クリーンアップ、または次の担当者の責任を、別のターゲットのアクターに引き渡す場合は、関係する各ターゲットのエントリを読み、受け手側の義務が、受け手自身のエントリ、リファレンス、またはインポートしたモジュールからたどれることを確認します。共有インポートがこの条件を満たすのは、そのモジュール自体に義務が記載されている場合に限ります。これらの文章に記載されていない引き渡しは、推測で補わず、存在しないものとして扱います。
5. 結論を出す前のレビューに従って変更をレビューします。レビューの「実施条件」に該当する変更は、どれほど小さく見えても、レビューを実施するまで完了していません。報告では、誰がレビューし、何が確認されたかを述べます。

ツールに任せる範囲を決める

ツールとは、ソースに書き込むスクリプトです。ビルド時にスキルの scripts/ フォルダーに格納され、AI が読み取るのではなく実行します。結果をツールが読み取れる、または受け取れる入力（ファイル、git の状態、AI がすでに持っている値）だけから正確に決められ、結果を誤ると、書き込まれる内容、次のステップ、または作業が受け入れられるかどうかが変わる場合は、そのステップをツールに任せます。目的、どのケースに当たるか、完了しているか、十分な品質か、アクションが安全か許可されているか、トレードオフなど、意味の判断が必要なことは文章で説明します。1つのステップで両方が必要な場合は、そこで分けます。AI が判断してツールに渡し、ツールが残りを正確に処理します。たとえば、AI が分類した内容の合計を計算したり、AI が決めたステータスを書き込んだりします。ツールは一貫性を保ちますが、間違いがないとは限りません。ツールが確定できるのは、チェックする内容だけです。

ツールによってなくなる作業と、増える作業を比較します。ツールによってなくなるのは、AI が手作業で行うはずだった正確さが求められる作業です。たとえば、多数のファイルの確認、件数の集計、厳密な形式への照合、ID の生成、完成したファイルと固定ルールとの照合などです。また、誤った形式、項目の見落とし、古い内容での上書き、同じルールが別々の場所で食い違うといった、その作業に伴うミスも防げます。一方で、正しく保守するコード、実行するコマンド、文章で対処方法を示す必要のあるエラーが増えます。ユーザーや既存ファイルに変更を強いる移行も、増える作業に含まれます。また、ツールが便利だからといって、利用者が頼りにしている形式を変更してよいわけではありません。依頼にすでに含まれていない限り、そのような移行はユーザーの同意を得てください。正確な結果に依存する項目、実行回数、利用者が多く、ミスの代償が大きいほど、ツールを使う理由は強まります。何千ものファイルを一度だけ処理する場合でも、毎日繰り返す場合と同じようにツールの導入が妥当なことがあります。反対に、慎重に読めば正しく処理できる程度に結果の自由度が高い場合は、ツールを使う理由は弱まります。AI が判断を言い直して入力を埋める必要があり、その結果として自分で作れた以上のものが返ってこないなら、ツールは確実性を高めず、単に手順を増やします。

たとえば、ステージ間で受け渡す固定フィールド形式の状態ファイルは、記入漏れが次のステージに誤解を招く場合、共通のチェッカーを用意するとよいでしょう。固定の不変条件がない自由形式のテキストには、チェッカーは不要です。50件の領収書を集計するスキルでは、集計をツールに任せ、各領収書の分類は AI が判断します。

ツールはマニフェストの tools で宣言し、それを含める各ターゲットに記載します。判断した結果を、他の人も編集するファイルに変更を失わずに反映する必要がある場合は、代わりにターゲットのコアとなる record が適していることがあります。ツールや record、またはそれを呼び出すステップを書いたり変更したりする前に、references/tools.md を開いてください。

作業を分割する

エントリーは、常に読み込むものとして、最小限の完全な契約に保ちます。すべての分岐を解釈するために必要な背景と意図、目的、使用するタイミングと運用上の境界、すべての分岐で使うルール、または正規の管理元への無条件の参照、現在の入力、完了の証拠、そしてほかの各ファイルについては、現在のタスクから開く前に判断できる、開くための正確な条件を含めます。その条件は、次のアクション、確定した状態、または質問であり、エントリー内の言葉で記述します。作業を段階的に進める場合は、その流れを示すマップを最初に置きます（別の AI が実行できる文章を書く）。フロントマターの description には、スキルの機能と、どのような依頼で開始すべきかを、ユーザーの言葉で記述し、隣接するスキルと区別できるだけの情報を含めます。ワークフローは本文に置きます。

実行中に現在のタスクや段階から、そのブロックがまだ必要ないと判断できる場合は、読み込みの節約がナビゲーションや再読にかかるコストを上回ることを条件に、そのブロックを独立したファイルに移します。たとえば、その段階が始まる前の段階の詳細や、まれなケースへの対応です。長さにかかわらず、まとめて判断する必要があるものは分割しません。

このターゲットだけが読み、管理する内容は、ディスクリプターの references にターゲット相対パスで宣言するターゲット管理のリファレンスであり、references/<file name> として提供します。ほかのターゲットも読む内容、またはこのターゲットの外で管理される内容は、ID でインポートするパッケージモジュールです。2 つ目のターゲットがリファレンスを必要とする場合は、モジュールに昇格させ、参照元を付け替えます。各インストール済みスキルが単独で動作できるよう、ビルド時にモジュールは利用する各スキルにコピーされます。コンテキストは内容を読んだときに消費されるため、同じ会話で別のスキルを通じてモジュールを再度読むと、その分も再び消費されます。すべての利用者が常に読むモジュールは完全かつ小さく保ち、一部の利用者だけが必要とする部分は、手順で必要になったときに開くモジュールに移します。

独自のトリガー、独自のセッション、またはレビュー対象の作業を行っていないセッションによるレビューなど、確認対象の作業とは別に実施する必要がある確認を持つ責務は、別々のスキルにします。常に同じセッション内で続けて実行し、独自のエントリーポイントも、そのような独立した確認も必要としない段階は、1 つのスキルにまとめ、各段階の詳細はその段階を始めるときに読み込みます。別のスキルに引き継ぐ場合は、そのスキル名と、そこで見つけるべき成果物を示します。フォルダー内のパスは示しません。

別の AI が実行できる文章を書く

新たに作業を始める AI に、目的地、それが重要である理由、自分で進め方を選ぶための基準と境界を伝えます。順序、状態、外部への影響、または承認によって結果が変わる場合に限り、固定の手順を示します。本質的な理由とともに、してはならないことを伝え、閉じたリストにはしません。また、誤った進め方を食い止める仕組みを設けます。それはツールによるチェックでも、レビュアーがテストできる境界でもかまいません。読者は列挙された手順や項目をすべて義務として受け取り、負荷がかかると一部を省き、該当するケースが列挙されていないと推論の手掛かりを失います。

1 つの判断に必要なもの、つまり目的、基準、境界、例があればその例を、判断を下す場所にまとめます。それぞれのものには全体を通して同じ名前を使い、これや必要に応じてのような言葉が何を指すのかを明記します。読者は、散在する言及から意図を確実に組み立てられず、2 つの名前を別々のものと解釈し、曖昧な言葉を独自に推測して補います。

文書、計画、レビューなど、スキルの成果物が基準から逸脱する可能性がある場合は、完了を報告する前に、その基準に照らして成果物を確認して作業を終えます。ツールが管理すべきものを決めるで確認手段が示されている場合はそのツールを使い、それ以外は基準に照らして読み直します。逸脱を防ぐ仕組みは、逸脱が起きる場所に置きます。 部分を説明する前に、全体を示してください。読者はファイルを先頭から読み込み、最初の画面だけを見ることもあり、目に見える順序をそのまま受け取ります。ファイルの各部分がひとつの全体を成す場合――順に進む、戻る、または後のセッションで再開する段階、互いに作業を引き継ぐスキル、ひとつの手順の各ステップ、相互に依存する部分など――は、個々の部分を説明する前に、その全体を短いマップで示してください。各部分について、そのルールを定めるセクションまたはファイルを記載し、レビューや検証など、作業が通過しなければならないチェックも、それぞれ独立した部分として含めます。また、各遷移については、失敗時の遷移も含め、どこから始まり、何がきっかけとなり、どこへ進むのかを言葉で明記してください。テキストの図は読者が一行ずつ読むため、行や矢印の配置だけに頼って経路を示してはいけません。その後、マップの順序どおりに、マップで使った名前を見出しにして各セクションを並べてください。こうすることで、マップは各セクションの横に要約を添えるのではなく、セクションを索引します。各遷移は、詳細と例外を定めるセクションを指し、その条件で禁止されている移動を指示してはいけません。複数の部分に共通するルールは、その前に一度だけ置くか、それらの部分から参照させてください。短いリストひとつに収まる全体なら、そのリストだけで十分であり、別途マップは不要です。段落に散らばった順序は、読者ごとに異なる形で組み立て直され、最後のステップであることが多いチェックは、真っ先に抜け落ちます。

各ブロックは、その内容が読者に求める形式にしてください。目的、理由、判断には文章、順序を守る必要がある場合に限り番号付きリスト、順序のない項目群には箇条書き、同じ属性で複数の項目を比較する場合は表、マップ、テンプレート、厳密な形式にはコードブロックを使います。また、読者が位置を見失ってはいけない長い手順には、読者が自分の作業にコピーしてチェックを付けるチェックリストを使ってください。1つのセクションでは、1つの段階または1つの判断を扱い、本文のほかの箇所でも使われている言葉で、そのセクションが何を決定し、何を行うかを見出しにしてください。パッケージ全体で、見出し、ラベル、強調の表記を統一してください。読者は最初に開くファイルからレイアウトを学び、次のファイルにも同じものを探します。また、すべてを強調すると何も強調されないため、見落とすと動作が変わる内容に限って強調してください。条件に応じて開かれるファイルは、何を扱い、いつ読むのかを述べる1行から始めてください。長いファイルは、読者が冒頭だけをプレビューすることもあるため、先頭にセクション一覧を記載してください。スキルが後の読者向けに作成するドキュメントにも、以下の形式を通じて、スキル内で同じように形を与えてください。

読者は、指示された内容よりも目にした内容を忠実にコピーするため、同じ形式が繰り返される箇所では、実例を示してください。

parallel kinds of one thing  → a block per kind, the same fields in each      none gets merged or dropped
a result that needs judgment → one example, with what in it is fixed marked   a small template
a result that must match     → the form itself, its fields and order fixed    a large template, or the tool that prints it

たとえば、2つのモードを持つスキルでは、両方を1つの段落で説明するのではなく、それぞれに専用のブロックを設けます。## Review と ## Fix のようにします。各ブロックには、When、Produces、Stops when など、同じフィールドを設けます。それらのフィールド名は、そのスキル固有のものです。

各タイミングでさらに記述を加える前に、references/skillEvolutionMethod.md の§5、§§8.3–8.4、§9を適用してください。対象となるタイミングは、ガイダンスをケース一覧に変える前、失敗への対処としてルール、例外、またはツールを追加する前、同じ文に3回目の修正が必要になったとき、およびレビューで「混乱するかもしれない」以外の失敗場面が挙げられていないときです。

完了とする前にレビューする

草稿は、書きやすかった内容へと逸れがちです。また、書き手は、次の AI が持たない意図をもって草稿を読みます。変更を完了とする前、あるいはビルドする前に、このスキルの基準を改めて確認し、壁として機能させます。

• タイミング：別の AI の判断や行動を変える変更の後です。新しい対象、変更された基準や境界、新規または変更されたツールやそれを呼び出すステップ、ファイル境界の移動が該当します。対象、権限、動作を変えないスペルや表現の修正は不要ですが、読み取り、書き込み、実行される内容を変えるパスの変更は必要です。
• そのユーザーの立場で読むこと。これは、この手法の読み取りテスト（§8.4）です。自分で読みます。変更された対象の正式なエントリから始め、その対象を使う AI が持つ入力だけを用いて、宣言された読み取り条件に沿って進みます。現実的なタスクを一つか二つ選び、ソースがその AI に何をするよう指示し、何を省略し、何を未知のままにしているかをたどります。実際に行に書かれている内容だけを根拠とし、意図した内容を根拠にしません。この読み取りは、記述されたソースを対象とするもので、ビルドやインストールは不要です。これは変更を完了するための作業の一部であり、ユーザーが求めるテストではありません。そのため、ユーザーがビルドやテストを行わないよう求めた場合でも実施します。たどった動作が意図から逸れている場合、ソースには条件、理由、または担当者が不足しています。
• このスキルに照らして確認すること：変更を ツールが担うべき役割を決める、作業を分割する、別の AI が行動に移せる文章を書く の各項目に照らして確認します。また、どのセクションも単独では担っていない問題も確認します。たとえば、同じステップを異なる方向へ導く箇所が二つある、あるいは別の箇所で求められていることを妨げる文がある、といった問題です。
• 指摘には、その箇所、そこから生じる誤読や失敗、そしてその理由を明記します。具体的な状況を示さずに「混乱を招く可能性がある」と述べても指摘にはなりません。また、指摘がないことも有効な結果です。
• 症状が現れた箇所ではなく、原因となる箇所を修正します。不足している条件は、それを必要とするステップに追加します。読み手が誤解した事実は、ツール側に記載するのが適切な場合があります。ルールを追加するより、削除または明確化する方が効果的です。修正後は、上記のとおりエントリから改めてレビューします。修正が触れていない文章にも影響する可能性があるためです。レビューで修正箇所が見つからなくなるまで続けます。同じ文を三度目に修正する必要がある場合は、書き換えを続けるのではなく、手法§9.2に沿って何が不足しているのかを判断します。
• 別のレビュアー：ユーザーから求められた場合は、サブエージェント、またはユーザーが実行するコーディネーターを通じて起動した別のエージェントにもレビューを依頼します。誤った変更の代償が大きい場合や、同じ前提に基づく修正が何度も失敗する場合は、依頼されていないエージェントを起動するのではなく、報告でその利用を推奨します。手法§10の説明に従って背景と意図をすべて伝え、指摘を評価します。期待する結果や懸念する問題は決して伝えず、ソースと入力だけを使ってタスクをたどってもらいます。
• ビルド検証と、ツールが維持する開発テストは、それぞれ該当する部分を確認するための壁です。このレビューでは、AI がそれらをどのように使うかを確認します。どちらも、インストール済みのスキルを検証するテストの代わりにはなりません。そのテストはユーザーが求めた場合に実施します。

ユーザーから依頼された場合にビルド、テスト、納品する

ビルド済みフォルダーがないソースパッケージも、必要な回数だけユーザーとやり取りを重ねて洗練させた、作成の完全な成果物です。スキルの動作を変更する依頼は、ビルド済みフォルダーやインストール済みコピーがある場合でも、ソースの変更にあたります。ビルドと、それに依存するテストや納品は、ユーザーから依頼があった場合にのみ開始し、変更を完了させるために行うことはありません。ビルドの依頼には、その依頼とともに求められた作業が含まれますが、ユーザーが継続的な指示として指定しない限り、後の変更には引き継がれません。それまでは、ビルド済みまたはインストール済みのコピーはすべてソースより遅れた状態です。変更によってその状態になった場合は、その旨を伝え、ビルドで何を証明できるかはunprovenのままにします。テストでは納品済みのスキルを使うため、テストの依頼があったときにルートが記録されていなければ、まずルートを確定し、その後ビルドして、このマシン上でそのルートに沿って作業を進め、テストします。変更の影響を受ける対象だけを再ビルドし、失敗したチェックや観察結果の記録は残します。ビルドと整合性チェックで証明できるのは、チェック対象の特性のみです。ソースが最新であることを証明できるのは、現在のソースと照合した場合に限られます。動作やホストに関する証拠が不足している場合は、unprovenのままです。

ビルド、checkの実行、テスト、納品済みとの表明、証拠が対象とする範囲の説明を行う前、および採用やリリースを決定する際は、references/build-and-test.mdを開いてください。プロジェクトにルートの記録がない状態でビルドする前と、ユーザーが納品ルートの選択、変更、実行を希望する場合は、references/delivery.mdを開いてください。

リポジトリの操作

インストール済みのスキルには、閉じた作成用CLIが1つ含まれています。<skill-root>には、このSKILL.mdを含むディレクトリを指定します。作業ディレクトリは、ソースパッケージを含むプロジェクトルート（このスキルを使って開始したパッケージの場合はsource/を含むフォルダー）に保ち、引数なし、help、または--helpを指定してnode "<skill-root>/scripts/skill-rails-cli/src/core/cli.mjs"を実行すると、inspect、overview、build、checkの現在の形式を確認できます。コマンドの引数が無効な場合、タスク固有のnextActionを含むJSONが返されます。パッケージ全体についての質問には、overviewを使って、そのソースパッケージから最新の非権威的なビューを生成してください。これを別の信頼できる情報源として保存してはいけません。