---
locale: ja
title: エージェントスキル
description: 現在の作業に関係するとき検索されるポータブルな指示を q に追加します。
sectionLabel: ガイド
toc:
  - id: 検索の仕組み
    label: 検索の仕組み
  - id: 検出場所
    label: 検出場所
  - id: スキルを書く
    label: スキルを書く
  - id: スキルを管理
    label: スキルを管理
  - id: 更新とインデックス
    label: 更新とインデックス
---

## 検索の仕組み

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

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

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

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

## 検出場所

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

```text
~/.agents/skills/
~/.q/skills/
<nearest-git-root>/.agents/skills/
<workspace>/.agents/skills/
<workspace>/.q/skills/
```

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

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

## スキルを書く

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

```markdown
---
name: release-check
description: 公開前にリリース候補を検証します。
---

# リリース確認

リリースマニフェストを読み、文書化された検証を実行し、根拠を報告してください。
```

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

## スキルを管理

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

```text
GLOBAL    -> ~/.q/skills/<skill-name>
WORKSPACE -> <workspace>/.q/skills/<skill-name>
```

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

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

## 更新とインデックス

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

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