スキルをローカライズする
生成されるもの
単独で動作するアーティファクト1つと、その作成過程の記録。
<skill-name>/ 通常のスキル。そのまま実行可能。
SKILL.md 値が書き込まれ、{{スロット}}やTODOはない状態
references/… scripts/… 同様に、全体に値が反映されている
<org>.context.yml 埋め込まれたコンテキスト。後で再ローカライズするために保持
<org>.profile.yml 組織全体の回答。将来のすべてのスキルで再利用
LOCALIZE-NOTES.md 導出されたもの、質問したもの、デフォルト値を使用したもの、未確認のもの
ローカライズ後のスキルは、実行時にコンテキストファイルを読み込みません。値はすべて本文に直接埋め込まれます。コンテキストをロードして自身のフィールド名を知る必要があるスキルは、呼び出しのたびにそのコストを支払い、ファイルが移動すると混乱を招く失敗を起こします。コンテキストは決定の記録であり、実行時の依存関係ではありません。
ファイル形式については references/contract.md、何か質問する前には references/asking.md、成果物を返す前には references/verify.md を読んでください。
重要な失敗
質問の数ではありません。採用担当者が答えられない質問です。
町の職員にデータセットIDとスキーマフィールド名を尋ねるスキルは、ゆっくり埋められるのではなく、放棄されます。その放棄は、設計上の欠陥ではなく、関心の欠如に見えます。これがエクスチェンジを大規模に機能させなくする原因であり、これは質問の性質の問題であり、採用担当者の問題ではありません。
したがって、導出できるものは導出し、スキル自体ではなく組織について質問し、組織がすでに回答した内容を、その後採用するすべてのスキルで再利用させます。
2つ目の失敗はより静かです。もっともらしいが間違った値が埋め込まれたスロットは、実行され、数値を返し、間違っているスキルを生み出します。確認されていない値を exact: true のスロットに書き込んではいけません。 ブロックする空白は回復可能ですが、誤解を招く埋め込みは回復不可能です。
手順
1. 何よりも先に contract_version を確認します。 これはコンテキストファイルの最初のキーです。references/contract.md のバージョンと比較します。
一致している場合は通常のケースです — そのまま進め、特に何も言いません。ファイルが古い場合は、変更履歴に従ってマイグレーションし、どのエントリが変更されたかを記録します。ファイルがこのスキルが理解できるより新しい場合は、停止します。 スロットには何も埋め込みません。未知の破壊的変更がある場合、ファイル内のどの値も誤って読み取られる可能性があり、誤って読み取られた値は、実行され数値を返すスキル内で、もっともらしい間違った値になります。ギャップを具体的に挙げ、新しい localize-skill を要求します。
contract_version がない場合、1 と仮定しないでください。バージョン管理以前に書かれたファイルは、古い形状ではなく、未知の形状を持ちます。何が作成したのかを尋ねてください。
2. scope を読み、それを声に出して伝えます。 どんな質問よりも先に、このスキルがどの階層で動作し、どの程度まで一般化されて流通可能かを、一文で採用担当者に伝えます：これは都市向けに書かれ、他の米国の都市や町向けに一般化されました。
彼らがその範囲内に該当するかどうかは判断であり、ルックアップではないため、テストするのではなく彼らに委ねます。範囲外の採用担当者は、埋めるのではなく再一般化するべきです：スロットだけが移植可能にされており、残されたものはここからは見えません。それらのスロットを埋めると、完成したように見え、彼らが持っていない国、法制度、政府形態を静かに前提とするスキルが生成されます。
保持された値が彼らにとってローカルに見える場合（区レベルのスキルに都市名があるなど）、それは reach が機能しているのであり、見落としではありません。彼らが修正しようとする前に、その旨を伝えてください。
3. 既にわかっていることをロードします。 何か質問する前に、手元にある回答を集めます。
<org>.profile.yml（この組織が以前にスキルを採用した場合）。管轄区域、承認責任者、オープンデータポータル、会計年度は、彼らが今後採用するすべてのスキルで同じです。二度質問することは、2つ目のスキルで人を失う方法です。- 別のスロットから暗黙的に導かれる値。ポータルのベースURLとデータセットIDは、独立した2つの質問ではありません。
scopeによって確定されるデフォルト値 — 国、通貨、郵便形式、法定制度 — これらは階層とリーチによってすでに固定されています。
4. 導出できるものを導出し、それを確認します。 公開ソースがある値（データセットID、スキーマフィールド名、ポータルエンドポイント、部署名）については、それらを調べて提案します。あなたの311の開始日カラムは case_opened_dt のようです。正しいですか？ は誰でも答えられる質問です。あなたの311の開始日カラムは何ですか？ はほとんど誰も答えられない質問です。
導出した値を確認することも質問ですが、それは別の種類の質問です：想起ではなく認識を尋ねるものであり、認識こそがデータを構築しなかった人でも使用可能にするものです。導出は決して exact: true の値に対する確認を不要にするものではありません。負担を移動するのであって、チェックをなくすわけではありません。
5. 残りの質問を、一度に尋ねます。 一度にまとめて、少しずつではありません。採用担当者が最もよく知っている順に並べます：最初に組織、最後にデータ。ステップ2で既に回答済みのものや、この採用担当者が使用しないスキルの分岐に関するスロットはスキップします — オプションのスロットを熱心に尋ねると、必須のものと区別がつかなくなります。
質問を exact に合わせます。false の場合は、デフォルト値を提示し、大まかな回答で構わないと伝えます。非公式にやっています、いる人に聞きます は実際の回答です。true の場合は、値が正確に一致しなければならない理由を説明し、推測が選択肢ではないことを明確にします。references/asking.md に機能する質問の形があります。
6. 値を書き込みます。 本文、参考文献、スクリプト、ファイル名、コメント全体にわたって置換します。その後、フロントマターを復元します：description、civic.use-when、civic.avoid-when には、コンテキストからの組織固有のバージョンを設定します。エージェントはコンテキストがロードされる前にこれらを読み取るため、中立的なスキルがローカルなリクエストで発動しなくなります。
civic.localization: localized と civic.jurisdiction を組織に設定します。スキルディレクトリから context.template.yml を削除します。出荷されるものは、誰かがこの組織のために書いたスキルに見えるべきです。なぜなら、それが今やそうであるからです。
7. 記録を書きます。 <org>.context.yml にはすべての値とその出所（プロファイル、導出、質問、デフォルト）を記録します。<org>.profile.yml は組織全体の内容で更新し、次のスキルが大部分埋まった状態から開始できるようにします。LOCALIZE-NOTES.md には、確認なしでデフォルト値を使用したもの、未使用としてスキップしたもの、採用担当者が確信を持てなかったものを記録します。出所の記録は、後で間違った数値を監査する際にインタビューをやり直さずに済ませるためのものです。
8. 返却する前に検証します。 references/verify.md。{{slot}} や TODO が残っているスキルは完成しておらず、値が一度も確認されなかったスキルは、明らかに未完成のスキルよりも悪質です。
完了前に
- コンテキストファイルの
contract_versionがチェックされ、このスキルが理解できるよりも新しいファイルからのスロット埋め込みは行われていません。 {{placeholder}}やTODOが、スクリプト、参考文献、ファイル名、コメントを含め、どこにも残っていません。- すべての
exact: trueの値は、人によって確認されるか、組織自身のシステムから取得されました。推測で黙って書き込まれたものはありません。 description、civic.use-when、civic.avoid-whenは組織を指定し、ローカルなリクエストで発動します。- スキルはコンテキストファイルを読み込まずに実行できます。
LOCALIZE-NOTES.mdには確認されていない値やデフォルト値がすべてリストされ、採用担当者はそのリストを確認済みです。<org>.profile.ymlには組織全体の設定が保持され、次のスキルでは尋ねる質問が減ります。