skills

Imported from daiksud/agents (skills/AGENTS.md). Install upstream with npx skills add daiksud/agents --skill skills. Copyright stays with the author.

スキルの作成・更新

このディレクトリ以下のスキルと同梱資料を作成・更新するときに適用する。 このファイルはリポジトリの編集指示であり、個々のスキルが実行時に読む前提にはしない。編集前に記入の指針を読み、条件と行動、必要な理由と例を明確にする。形式と配布の規則は以下を使う。

作成前の確認

• 利用者が実現したい状態、スキルを使う場面、期待する成果物と成功条件を明確にする。
• 既存スキルの目的と適用範囲を確認し、新規作成と既存スキルの改善のどちらが必要か判断する。
• 作成・改善の手順には、利用可能な skill-creator の SKILL.md を読んで適用する。APMの外部依存として導入する方法はREADMEを参照する。
• 成果物や適用範囲を左右する不明点は、既存の指示と会話を確認したうえでユーザーに確認する。
• Issue・PR・レビューの手順は task-workflow、文書の形式は okf-docs、実行コードの追加・変更は bdd-tdd に従う。

配置と形式

• 原本は skills/<name>/SKILL.md に置く。gh skill の標準探索を維持するため、隠しディレクトリに移さない。
• SKILL.md は Agent Skills仕様¹に従い、YAML frontmatterに name と description を記載する。
• name はディレクトリ名と一致させ、小文字英数字とハイフンで1〜64文字とする。先頭・末尾のハイフンと連続するハイフンは使わない。
• description は1〜1024文字の範囲で、実際に担当する依頼と紛らわしい対象外を短く具体的に書く。関連する話題への言及だけを発火条件にせず、過剰な強調や工程の説明を入れない。
• 既存スキルの更新では、依頼に必要な変更がない限り名前と適用範囲を保持する。
• 本文と説明は日本語を基本とし、コマンド・識別子・固有名詞は元の表記を保つ。
• このAGENTS.mdと同梱する通常概念はOKF v0.2に従う。仕様必須の type に加え、自作時の追加条件として title・description を記載する。index.md・log.md は予約形式とし、SKILL.md のfrontmatterはAgent Skills仕様を用いる。
• Bundleの境界、出典・確認履歴の保持と更新、検証の判断は okf-docs に従う。原本検査でのBundleはリポジトリルートとし、対象を明示して固有形式を除く。

内容と同梱資料

• 配布本文には利用先で必要な判断・手順だけを置く。agentsの原本配置・同期・導入検証履歴はローカルAGENTS.mdまたは保守ガイドへ置き、共通本文から管理手順に依存させない。
• 本文には利用先の判断基準、手順、成果物と確認方法を書く。
• 共通指示や他スキルの手順を複製せず、必要な場面と参照先を示す。利用環境にそのスキルがあることを前提にする場合は依存関係を明記する。
• SKILL.md は適用境界・重要な判断・完了条件と工程別の参照導線を中心にする。詳細・例・コマンドは読む条件を付けて references/ 等へ分ける。500行未満だけを簡潔さの証明にせず、通常タスクが無関係な工程まで読まないか確認する。
• 繰り返し実行する処理は scripts/、成果物に使うひな形などは assets/ に置く。必要な資源だけを同梱する。
• 同梱資料は参照元ファイルからの相対リンクで結ぶ。スキル外の資料は導入先に存在する前提にせず、公開URLや明示した依存先を使う。
• 指示中の docs/ などが作業対象リポジトリを指す場合は、その基準を明記する。原本・配布先・作業対象のパスを混同しない。
• 一時ファイルや実測していない評価結果をスキル本文に残さない。

評価と改善

• 新規作成や振る舞いの変更では、現実的な依頼と期待する結果を evals/evals.json に保存する。適用する例に加え、適用しない例や境界となる例を含める。
• 評価データの形式と評価・比較の手順は skill-creator に従う。変更した適用条件・手順に合わせて既存の評価例も更新する。
• 評価では期待する行動と成果物を確認し、問題があれば原因を修正して再評価する。評価例だけに合う例外を増やさない。
• 評価のために実際のIssue作成・送信・マージなどを行わず、隔離環境や読み取り専用の模擬タスクを用いる。
• 参照を分割・移動したらリンク元も更新し、代表タスクで適用・非適用と必要資料への到達を確認する。共通の品質・権限・完了境界を短縮のために落とさない。
• 模擬評価と実行検証、性能比較を区別して結果を記録する。実行できない検証は理由と未確認範囲を報告する。
• 誤字・リンク・形式のみの変更は、その変更に対応する文書・リンク検証を行う。振る舞いを変えた場合は評価を省略しない。

配布と完了の確認

• Markdownの作成・更新はGitHub向けMarkdownの品質に従い、共通設定で投稿・更新前に整形・チェックする。
• YAML・JSONの構文、必須項目、名前、相対リンク、記載したパスとコマンドを確認し、rumdlと git diff --check で文書を検証する。
• スキルの追加・削除・名前・配置・同梱資源を変更した場合は、gh skill install . --from-local の非対話での列挙と、一時ディレクトリへの導入で対象スキルと必要な資料が揃うことを確認する。
• 配布構成を変更した場合は、APMでの導入・更新・共通指示生成も隔離環境で確認する。実ユーザーのグローバル配布先を検証用に書き換えない。
• スキルの構成や導入方法を変更した場合はREADMEの案内を更新する。検証とレビューの結果はIssue・PRに記録する。