エージェントスキル

検索の仕組み

q はポータブルな SKILL.md Agent Skills 形式をオンデマンド検索層として実装します。完全なカタログとスキル本文はベースプロンプトに含めません。

新しいユーザーターン、task_start、ask_to_user の回答で、q はスキルのメタデータを検索し、未提示の候補ヒントを最大四件追加します。ヒント自体は指示ではありません。モデルは従う前に get_skill を呼ぶ必要があります。

スキルツールを持つロールは、新しい情報から追加のガイダンスが必要になったとき search_skills を呼べます。

字句ランキングはスキル名、タグ、説明の順に重みを付けます。埋め込みが設定されている場合、q は BM25 とベクトル候補を融合します。意味候補の信頼度が高く、字句スコアがノイズ程度なら、弱い BM25 の寄与を外して言語の不一致が強い意味結果を埋もれさせないようにします。意味の信頼度が十分でない場合は字句分岐をすべて残します。

検出場所

q は低い優先順位から次の場所を読みます。

最寄りの Git ルートはアクティブなワークスペースと異なる場合だけ使われます。サブディレクトリから起動してもファイルツール境界を広げず、リポジトリのポータブルスキルを利用できます。

限定された両方の結果に同じスキル名があれば、ワークスペース定義が優先されます。

スキルを書く

SKILL.md を含むディレクトリを作ります。

frontmatter の name は正規名ですが、ディレクトリ名と一致する必要はありません。description は任意です。結果を実質的に変える作業だけに適用されるよう本文の範囲を絞ってください。

スキルを管理

/skills を開くか q skills を実行します。二つのパネルは q が管理する場所に対応します。

左右または Tab でスコープを切り替え、上下で選択します。A は Git リポジトリのクローン、U は fast-forward 更新、D は確認後の削除、R は全ルートの再検出とインデックス調整を行います。

.agents/skills のスキルも一覧に出ますが、q の所有ディレクトリではないため読み取り専用です。管理対象リポジトリはルートに SKILL.md が必要で、配置名は URL ではなく検証済み frontmatter から決まります。

更新とインデックス

埋め込みモデルがなければ BM25 メタデータ検索のみです。/model で割り当てると BM25 と HNSW ベクトル結果を組み合わせます。新しい埋め込みモデルの割り当てでベクトルプロジェクションを再構築し、バックフィルします。

q の実行中、前回確認から 30 秒以上経過していれば、スキル利用時にワークスペースのスキルルートを再調整します。/skills で q 管理スキルを操作し、明示的な再インデックスも行えます。