dahatake/skills
コーディングエージェント向けの スキル集 を提供するプラグインです。
GitHub Copilot CLI、Claude Code、Gemini CLI、および APM 対応の各種ハーネスから同じスキルを利用できます。
注意: 各スキルは SKILL.md の配布のみで完結しないものがあります。例えば markdown-query は別途 mdq CLI のインストールが必要です（setup/ スクリプト 参照）。プラグインを入れただけでは動作しない点にご注意ください。
提供スキル
| スキル | 概要 |
|---|
markdown-query | ローカル完結で Markdown 群を横断検索し、ヒットしたチャンクのみを返して Context Window を節約します（BM25 / grep / タグ検索対応）。 |
markdown-query スキル詳細
「初めてこのリポジトリを触る人」向けに、何が用意されているのか / 何ができるのか / どういう場合に使うのか を最初にまとめます。手順だけ知りたい方は 使用方法（markdown-query） まで読み飛ばして構いません。
何ができるのか（What）
markdown-query は、リポジトリ内の Markdown 群（仕様書、設計書、ナレッジ、README など）を ローカル完結で横断検索 し、ヒットした 見出し単位の小さなチャンク（snippet）だけ をエージェントに返すスキルです。
- BM25 検索: 自然言語クエリで関連度順に上位 N 件を返す。
- grep 検索: 完全一致 / 厳密一致したいキーワードに使う。
- タグ / パス絞り込み: frontmatter の
tags や docs/** のような glob で範囲限定。
- 見出し階層の俯瞰:
mdq list でファイル横断の見出し一覧を取得。
- 本文取得:
mdq get --chunk-id <ID> で必要な箇所だけ完全な本文を取り出せる。
なぜ使うのか（Why）
LLM ベースのコーディングエージェントでは、関連 Markdown を 丸ごと Context に投入すると Context Window を大量消費 し、コスト・速度・回答品質（noise）すべてに悪影響が出ます。
- 「全文を
read_file させる」 → 数万トークン消費、関係ない章まで読まれる。
markdown-query 経由 → 該当チャンク数百〜千トークン程度に圧縮されて投入される。
実測結果は 評価方法（ベンチマーク） を参照してください。
どういう場合に使うのか（When）
- 複数の Markdown（仕様書群、ナレッジベース、複数 README）を 横断的に参照したい とき。
- エージェントに「このリポジトリの仕様に従って実装して」と依頼する前に、関連箇所だけを切り出して渡したい とき。
- Context Window を節約しつつ、引用元 (
path:lines) を明示 したいとき。
逆に 使わないケース:
- Markdown を編集・生成したい（このスキルは読み取り専用）。
- クラウド埋め込み / リモートベクトル検索を使いたい（本スキルは外部 API を呼びません）。
- 単一の小さな README を眺めたいだけ（普通に開いた方が速い）。
アーキテクチャ概要
markdown-query の実体は本リポジトリ同梱の mdq/ Python パッケージです。ローカル完結（外部 API を呼び出さず、.mdq/ 配下に SQLite で永続化）であり、CLI・エージェント (Copilot / Claude / Gemini) のいずれからも python -m mdq サブプロセスとして起動されます。
flowchart LR
A["エージェント / ユーザー CLI"] -->|"python -m mdq ..."| B["mdq/cli.py (サブコマンド振り分け)"]
B --> C["indexer.py + strategies*.py<br/>(Chunking)"]
B --> D["query_router.py + search.py<br/>(BM25 検索 + snippet 生成)"]
B --> E["watcher.py (任意, 増分監視)"]
C --> F[(".mdq/index-<lang>-<strategy>.sqlite")]
D --> F
E --> C
B -. "append" .-> G[(".mdq/usage.jsonl")]
主な構成要素:
| 層 | モジュール | 役割 |
|---|
| CLI | mdq/__main__.py, mdq/cli.py | argparse でサブコマンド (index / search / get / list / stats / watch) を振り分け、利用ログを記録 |
| Indexing | indexer.py, strategies.py, strategies_semantic.py, strategies_pageindex.py | Markdown を Chunking Strategy ごとに分割し、SQLite に upsert |
| Search | query_router.py, search.py | クエリを 7 ルールで分類して strategy 選定 → BM25 検索 → snippet 生成 |
| Watcher | watcher.py（任意、watchdog が必要） | ファイル変更を daemon thread で監視し増分索引 |
| Storage | store.py + .mdq/index-<lang>-<strategy>.sqlite | SCHEMA v6。(lang, strategy) の組み合わせごとに独立した DB ファイル |
| Logging | usage_log.py + .mdq/usage.jsonl | 全 CLI 呼び出しを append-only JSONL に記録（任意の統計レポート生成に使用） |
設計上の前提:
- 物理ファイル分離: 索引 DB は
(lang, strategy) の組み合わせごとに別ファイル。検索時に Strategy だけを切り替えれば適切な DB が選択されます。
- 任意拡張:
watchdog（Watcher）、rank_bm25（高速 BM25）、fastembed + nltk + numpy（semantic_paragraph 戦略）はいずれも任意依存。未導入時はフォールバック動作します。
スキルパッケージに含まれるもの
インストール
前提条件
- Git CLI（全インストール経路で必須）
- Node.js 18+ （
npx skills 経由でインストールする場合のみ必須）
- Python 3.11+（
markdown-query の mdq CLI を利用する場合のみ必須）
各エージェント CLI（copilot / claude / gemini / apm）は事前にインストールしておいてください。
APM（複数ハーネス対応）
APM を使うと、1 コマンドで複数のエージェント環境に導入できます。
apm install dahatake/skills
GitHub Copilot CLI
copilot CLI のインタラクティブセッション内で次を実行します（初回のみマーケットプレイス追加）。
/plugin marketplace add dahatake/skills
/plugin install dahatake-skills@dahatake-skills
シェルから直接実行する場合:
copilot plugin marketplace add dahatake/skills
copilot plugin install dahatake-skills@dahatake-skills
更新する場合:
copilot plugin update dahatake-skills
インストール確認:
