dahatake-skills

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-&lt;lang&gt;-&lt;strategy&gt;.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 戦略）はいずれも任意依存。未導入時はフォールバック動作します。

スキルパッケージに含まれるもの

パス	内容
skills/markdown-query/SKILL.md	スキル本体。エージェントが読み込むトリガー定義と手順サマリ。
skills/markdown-query/references/cli-reference.md	mdq CLI の全サブコマンド・全オプション仕様。
skills/markdown-query/references/query-patterns.md	よくあるクエリ例（タグ絞り込み、grep、見出し俯瞰など）。
skills/markdown-query/references/indexing-internals.md	索引のデータモデルとチャンク分割ルール（高度な利用者向け）。
skills/markdown-query/examples/prompt-snippets.md	Copilot Chat / Custom Agent に組み込む際のプロンプト例。
mdq/	スキルが内部で呼び出す Python 製 CLI 本体。
setup/setup-markdown-query.{ps1,sh}	mdq を .venv にインストールするセットアップスクリプト。
tools/markdown-query/	Context 削減効果を数値で確認するためのベンチマーク CLI。

インストール

前提条件

• 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

インストール確認: