qmd-knowledge

QMD ナレッジ

できること

• プロジェクトで得た学びや知見を記録し、取得します
• 特定の課題に関するメモや解決策を記録します
• AI で検索できるナレッジベースを段階的に構築します
• プロジェクトのアーキテクチャや決定事項に関するコンテキストを提供します

使用する場面

次のような場合に、このスキルを使用します。

• 学びを記録する：開発中に得た新たな知見、パターン、ベストプラクティスを記録します
• 課題を追跡する：進行中または解決済みの課題にメモを追加します
• ナレッジを検索する：過去の決定事項、学び、解決策を検索します
• コンテキストを維持する：プロジェクトの組織的な記憶を構築します

仕組み

このスキルは、統合されたナレッジ管理システムを提供します。スキルを一度インストールすると、qmd コレクションを使って、すべてのプロジェクトのナレッジを管理します。

# The qmd-knowledge skill (installed to your AI tool's skills directory)
# Location varies by tool: $HOME/.config/opencode/skills/, $HOME/.claude/skills/, or $HOME/.config/amp/skills/
├── SKILL.md              # This file - the skill definition
├── scripts/              # Executable scripts
│   └── record.sh         # Record learnings/issues/notes
└── references/           # Example structure and READMEs

# Project knowledge storage (managed by the skill)
~/.ai-knowledges/
├── <project-name>/       # Collection for your project
│   ├── learnings/
│   └── issues/
└── another-project/      # Collection for another project
    ├── learnings/
    └── issues/

qmd MCP サーバーは、保存されたすべてのナレッジを AI で検索できるようにします。これにより、AI アシスタントが自律的にナレッジベースを検索し、更新できます。

利用可能なスクリプト

ナレッジの記録

重要：ナレッジを記録する前に、qmd がインストールされ、プロジェクトのコレクションが設定されていることを確認してください。事前チェックを実行します。

# Verify qmd is installed
command -v qmd || echo "Install qmd: bun install -g @tobilu/qmd"

# Verify your project collection exists (replace my-project with your actual project name)
qmd collection list | grep my-project

# Record a learning (use the skill's script)
$SKILL_PATH/scripts/record.sh learning "qmd MCP integration"

# Add a note to an issue
$SKILL_PATH/scripts/record.sh issue 123 "Fixed by updating dependencies"

# Record a general note
$SKILL_PATH/scripts/record.sh note "Consider using agent skills for extensibility"

記録後：

• record.sh スクリプトは、ナレッジベースのインデックスを再作成するために、qmd embed を自動的に実行します
• 新しく追加したコンテンツを次回の検索で見つけられるようにするには、この埋め込み処理が必須です
• 自動埋め込みに失敗した場合、またはファイルを手動で追加・編集した場合は、qmd embed を明示的に実行してインデックスを更新してください

ナレッジの検索

Claude または OpenCode から、qmd MCP サーバーのツールを直接使用します。

# Fast keyword search
qmd search "MCP servers" -c <project-name>

# Semantic search with AI embeddings
qmd vsearch "how to configure MCP"

# Hybrid search with reranking (best quality)
qmd query "MCP server configuration"

# Get specific document
qmd get "references/learnings/2024-01-26-qmd-integration.md"

# Search with minimum score filter
qmd search "API" --all --files --min-score 0.3 -c <project-name>

セットアップ

事前チェック：開始する前に、必要なツールが揃っていることを確認してください。

# Check for bun or node
command -v bun || command -v node || echo "Install bun or node.js first"

# Verify git is available (for project detection)
command -v git || echo "Install git for automatic project name detection"

1. qmd をインストールする：

   bun install -g @tobilu/qmd
   

2. スキルをインストールする：

   # The skill is installed to your AI tool's skills directory:
   # - OpenCode: $HOME/.config/opencode/skills/qmd-knowledge/
   # - Claude Code: $HOME/.claude/skills/qmd-knowledge/
   # - Amp: $HOME/.config/amp/skills/qmd-knowledge/
   

3. MCP サーバーを設定する（Claude／OpenCode／Amp のインストール手順を参照してください）

4. プロジェクトのナレッジコレクションを作成する：

   # The skill's record.sh script will auto-detect the project name when executed.
   # For manual setup, use your desired project name consistently in the commands below.
   # Optional: export QMD_PROJECT=<project-name> to override auto-detection
   
   # Create storage directory for your project (replace <project-name> with your project)
   mkdir -p ~/.ai-knowledges/<project-name>/learnings
   mkdir -p ~/.ai-knowledges/<project-name>/issues
   
   # Add qmd collection
   qmd collection add ~/.ai-knowledges/<project-name> --name <project-name>
   qmd context add qmd://<project-name> "Knowledge base for <project-name> project: learnings, issue notes, and conventions"
   
   # Generate embeddings for AI-powered search
   qmd embed
   

ナレッジの構成

• references/learnings/：プロジェクトで得た知見を記録した、日付入りの Markdown ファイル

  • 形式：YYYY-MM-DD-topic-slug.md
  • 学び、パターン、アーキテクチャ上の決定事項を記載します

• references/issues/：特定の課題に関するメモや解決策

  • 形式：<issue-id>.md
  • 特定の課題に関するメモを追記していくログです

qmd MCP サーバーとの連携

qmd MCP サーバーを使うと、Claude は次のことができます。

• ナレッジを検索する：自然言語で検索し、関連するコンテキストを見つけます
• インデックスを自動更新する：ナレッジの追加後に、自動的にインデックスを再作成します
• プロジェクトで絞り込む：--collection フラグを使用して、特定のプロジェクトに検索対象を限定します

ワークフローの例

1. 開発中に、役立つ情報を見つけます。

   「qmd MCP サーバーを使うと、Claude が自律的にツールを使えることがわかりました。」

2. Claude がスキルを認識して実行します。

   $SKILL_PATH/scripts/record.sh learning "qmd MCP autonomous tool use"
   

3. 後で、次のように尋ねます。

   「MCP サーバーについて何を学びましたか？」

4. Claude が qmd MCP ツールを使ってナレッジベースを検索します：

   qmd query --collection <project-name> "MCP servers"
   

プロジェクトの検出

このスキルは、次の優先順位でプロジェクト名を自動的に検出します。

1. QMD_PROJECT 環境変数（最優先）

   export QMD_PROJECT=my-project-name
   

2. Git リモート URL（最も信頼性が高く、origin URL からリポジトリ名を抽出します）

   • 例：https://github.com/user/my-project.git → my-project
   • ローカルフォルダー名が異なっていても機能します

3. Git リポジトリのフォルダー名（フォールバック）

   • Git リポジトリのルートディレクトリ名を使用します
   • Git リポジトリ内のどこにいても機能します
   • 注：フォルダー名が変更されている場合、実際のリポジトリ名と一致しないことがあります

4. 現在のディレクトリ名（最後の手段）

   • 現在の作業ディレクトリ名を使用します
   • Git リポジトリ内にいない場合に使用されます

これにより、プロジェクト名をハードコードせずに、どのプロジェクトでもこのスキルを使用できます。ナレッジベースは ~/.ai-knowledges/<detected-project-name>/ に保存されます。

重要：このスクリプトは Git リモート URL を優先するため、ローカルフォルダー名が変更されている場合や、標準とは異なる場所（2026-01-08-my-ai-tools.qmd-skill のような日付付きフォルダーなど）にある場合でも、プロジェクト名の一貫性が保たれます。

📋 ベストプラクティス

🎨 セッションの振り返り

作業セッションの終わりに、重要な学びについてユーザーに尋ねることを検討してください。

「このセッションで得られた主な発見や決定事項は何でしたか？記録しておきたい学びはありますか？」

🎨 パターンの検出

価値のある知識を記録できる機会を示す次のような表現に注意してください。

• 「〜ということが分かりました」
• 「〜を学びました」
• 「解決策は〜でした」
• 「重要な気づきは〜です」
• 「〜を忘れないでください」
• 「必ず〜してください」

こうしたパターンを検出したら、記録を提案してください。

「役立つ学びのようですね。記録しておきましょうか？」

🎨 自動インデックス更新

記録スクリプトは書き込みのたびに qmd embed を自動実行し、ナレッジベースをすぐに検索できるようにします。新しいコンテンツを検索クエリで利用できるようにするには、この再インデックス処理が必須です。

重要：記録スクリプトを使わずにナレッジファイルを手動で作成または編集した場合は、検索インデックスを更新するために qmd embed を手動で実行する必要があります。

# Manual re-indexing after direct file edits
qmd embed

再インデックスを行わないと、新しく追加または変更されたコンテンツは検索結果に表示されません。