EastDong314/agent-skills

Obsidian Notes

Operating Context

ローカルボールト ${OBSIDIAN_VAULT:-$HOME/workspace/notes} を使用します。これはユーザー所有のナレッジベースかつ Markdown コードベースとして扱い、無関係な編集は保存し、要求がない限り一括書き換えは避け、ノートのファイル名とリンクは Obsidian に適した形式を維持します。

このボールトは通常エージェントのワークスペースルートであるため、通常のノート作業では組み込みのファイルツール（Codex: read/apply_patch; DSH と pi: read/edit/write）を使用できます。ボールト外の操作については、書き込み前に確認してください。

このスキルは Codex、pi、DSH で共有されるバンドルです。現在のエージェントに合わせたベースディレクトリを選択し、以下のすべてのコマンドで $HELPER を使用します。

# DSH (canonical source copy)
export SKILL_DIR="$HOME/.dsh/skills/obsidian-notes"
# Codex
# export SKILL_DIR="$HOME/.codex/skills/obsidian-notes"
# pi
# export SKILL_DIR="$HOME/.pi/agent/skills/obsidian-notes"

export HELPER="$SKILL_DIR/scripts/obsidian_notes.py"
python3 "$HELPER" --help

SKILL_DIR が現在のシェルでエクスポートされていない場合は、コマンドごとに再度エクスポートするか、このスキルに対してハーネスが報告するスキルベースディレクトリからの相対パスで scripts/obsidian_notes.py を解決します。python3 を使用してください（ヘルパーは標準ライブラリのみに依存しており、python3 がない場合のみ python にフォールバックします）。

決定論的な CRUD、インデックス、ログ、lint、Bases、Canvas 操作には、このバンドルされたヘルパーを推奨します。デフォルトでボールトを対象とし、外部のパスへのアクセスを拒否します。

有用な場合は、ローカルの Obsidian アプリまたは obsidian:// URI スキームを使用してノートを開きます。Linux Flatpak ではアプリ ID は md.obsidian.Obsidian です。通常、PATH 上に obsidian バイナリはありません。

このスキルは kepano/obsidian-skills のパターンをローカルボールト向けに拡張したものです：Obsidian Flavored Markdown、Bases、JSON Canvas、CLI 使用法、クリーンな Web 抽出などです。これらのドメインを1つのワークフローにまとめ、ボールト操作が ${OBSIDIAN_VAULT:-$HOME/workspace/notes} の範囲内に収まるようにします。

Knowledge Base Model

より大規模なナレッジワークには3層モデルを使用します。

• Raw sources: ユーザー提供の記事、PDF、クリッピング、ミーティングノート、スクリーンショット、またはトランスクリプト。これらは真実のソースとして扱い、明示的に要求されない限り書き換えや削除は行いません。
• Wiki notes: エージェントが作成・管理する構造化された Markdown ページ。要約、統合、クロスリンク、更新を行います。
• Schema: このスキルとボールト内のローカル規約ノート（技術/00-System/ 以下および Obsidian ガイダンスフォルダ）。重要な変更の前に、ボールトの使用法、分類法、Obsidian 規約に関するノートを検索します。

事前に読む価値のあるボールトローカルのスキーマノート：AGENTS.md（ボールトルート、ボールト全体のルール）、技術/AGENTS.md（技術/ のローカルルール）、技術/00-System/目録構造説明.md、技術/00-System/全局維護規則.md、技術/00-System/分類與標籤規範.md、技術/00-System/知識庫使用説明.md、技術/00-System/文檔模板説明.md、および 技術/10-個人效率與環境/Obsidian/Obsidian知識管理使用規範.md。

尊重すべき既知のボールト規約：

• コンテンツは中国語で記述されます。ノートは YAML frontmatter を含む Markdown で、少なくとも tags と related を含み、通常 title/aliases/created/updated/type/status/source も含まれます。
• ルートフォルダは AI/（メインナレッジベース、番号付きセクション）、さらに 開発/、日記/、零星想法/、項目/ です。
• 分類が不明なものは 98-待整理 に属し、非推奨のコンテンツは 99-归档 に属します。これらのフォルダは実際に必要になった場合のみ作成します。
• 既存の価値の高いノートを上書きするよりも更新を優先します。安全なマージが不可能な場合は、「待合并」サフィックスを付けて新しいファイルを作成します。

重要な作業の前には、関連するスキーマノートを読んでください。目標は知識を蓄積することです。既存のページ、リンク、インデックスエントリ、ログを更新し、後続のセッションで同じコンテキストをゼロから再発見する必要がないようにします。

Workflow

1. ユーザーのリクエストから操作を明確にします。作成、読み取り、更新、削除、検索、取り込み、クエリ、lint、整理、開く、Base 作成、Canvas 作成、Web ソースのクリップ、Obsidian の動作デバッグ。
2. 変更前に既存のノートを検査します。
   • Bash で rg を使用するか、エージェント自身のコンテンツ/パス検索ツールを使用して、コンテンツとパスを検索します。
   • ヘルパーの search、read、list コマンドをボールトスコープのパスに使用します。
   • 構造、分類法、長期的なメンテナンスが重要な場合は、ボールトスキーマノートを読みます。
   • アプリ設定が重要な場合のみ .obsidian/ を確認します。
3. Obsidian のセマンティクスを維持します。
   • 内部参照には [[Target Note]] や [[Target Note|Alias]] のような Wiki リンクを使用します。
   • ユーザーが正確な参照を必要とする場合は、見出しリンク [[Target Note#Heading]] やブロックリンク [[Target Note#^block-id]] を使用します。
   • 安定した分類には frontmatter でタグを使用し、#tags のインライン使用は散文の一部である場合のみにします。
   • メタデータ、日付、エイリアス、ステータス、ソース、プロジェクト、エリア、モデル、ホスト、次のアクションについては YAML frontmatter を維持します。
   • 構造化フィールドには Obsidian Properties および Bases 互換の frontmatter を優先してください。ユーザーが明示的に Dataview クエリ、インラインフィールド、Dataview ダッシュボードを要求した場合のみ、status:: active のような Dataview インラインフィールドを使用します。
   • ボールトコンテンツを埋め込む場合は、相対埋め込み ![[file.png]] または ![[Note#Heading]] を優先します。
   • 視覚的な強調が有効なコンテンツ（要約、警告、例、決定、TODO、質問）にのみ callout を使用します。
4. エージェントのパッチ/編集ツール（Codex: apply_patch; DSH と pi: edit）でスコープ指定した編集を行うか、ノート全体の作成または置換には write/ヘルパーを使用します。編集や置換の前にファイルを読みます。
5. 永続的な変更の場合は、インデックスを更新または再生成し、ログエントリを追加します。
6. 編集後、変更したファイルを読み、リンク/検索結果を確認し、.base や .canvas ファイルがあれば検証し、必要に応じて Obsidian でノートを開いて確認します。

Note Quality Rules

新しいノートについては、単なる Markdown ダンプではなく、Obsidian 内で有用なノートを作成します。

• ターゲットフォルダに明確に異なる慣習がない限り、YAML frontmatter から始めます。
• 概念に別名がある場合は aliases を含めます。
• 可能な限り既存のボールト分類法に一致する tags を含めます。
• ノートが何であるかを示す簡潔な最初の段落を追加します。
• バックリンクを可能にする見出しを持つセクションを追加します。
• ## 関連リンク または ## Links を、関連する既存のノートへの Wiki リンクとともに追加します。ターゲットフォルダがすでに使用しているローカライズされた見出しに一致させます。番号付きの AI/ フォルダは ## 相關連結、プロジェクトノートはどちらかを使用する場合があります。
• 構造化フィールドはデフォルトで YAML frontmatter に配置し、Obsidian Properties と Bases が編集、ソート、フィルタリングできるようにします。ユーザーが Dataview インラインフィールドを要求しない限り、同じフィールドを frontmatter と本文の key:: value の両方に重複して配置しないでください。
• プロジェクトまたはタスクノートの場合は、アクション可能なステータスと次のステップフィールドを含めます。
• 永続的な知識ノートの場合は、主張をソースノートおよび関連概念にリンクします。

新しいノートテンプレートの作成、ノート構造の修復、frontmatter、タグ、バックリンク、Dataview、インデックスファイル、ログ、ソース取り込みの使用方法の決定には、$SKILL_DIR 以下の references/obsidian-patterns.md を読んでください。

Obsidian Markdown Features

これらの構文機能は、ノートを Obsidian 内でより有用にする場合に使用します。

• ウィキリンク: [[Note]]、[[Note|Alias]]、[[Note#Heading]]、[[Note#^block-id]]、[[#Same-note heading]]。
• 埋め込み: ![[Note]]、![[Note#Heading]]、![[image.png|300]]、![[document.pdf#page=3]]、![[Canvas.canvas]]、![[View.base#View Name]]。
• Callout: > [!note]、> [!warning] Title、> [!todo]- Collapsed。コンテンツにはネストされた引用行を使用します。
• コメント: %%hidden text%% またはブロックコメント。エージェント専用の注釈で、レンダリングされるべきではありません。
• ハイライト/数式/図: ==highlight==、インライン $math$、ブロック $$math$$、フェンス付き mermaid。
• 脚注: [^1] 参照、定義、インライン脚注。

ノートを過度にフォーマットしないでください。Obsidian 拡張機能がナビゲーション、検索、レンダリングを向上させる場合を除き、通常の Markdown を優先します。

Bases

ユーザーがノートのデータベースライクなビュー、タスクリスト、読書リスト、プロジェクトダッシュボード、フィルタリングされたインデックス、またはプロパティ駆動のテーブル/カード/リスト/マップを希望する場合は、.base ファイルを使用します。

Base ファイルは YAML です。以下を中心に構築します。

• filters: file.hasTag("project")、file.inFolder("Daily Notes")、status == "active" などのグローバルおよびビュー固有の式。
• formulas: 期日までの日数、ステータスラベル、単語見積もり、派生リンクなどの計算フィールド。
• properties: ノート、ファイル、数式フィールドの表示名と設定。
• summaries: Average、Sum、Min、Max、Latest、Checked、Empty、Filled、Unique などの集計計算式。
• views: 明示的な order を持つテーブル、カード、リスト、マップビュー。

ルール:

• フィルターと数式の式は、特に :、#、ブラケット、比較演算子、ネストされた引用符を含む場合は引用符で囲みます。
• 二重引用符を含む数式は一重引用符で囲みます: 'if(done, "Yes", "No")'。
• 日付の減算は期間を返します。数値関数の前に .days、.hours などにアクセスします。
• オプションのプロパティは if(property, expression, fallback) でガードします。
• 編集後に検証: python3 "$HELPER" validate-base "Dashboards/Projects.base"。

JSON Canvas

ユーザーがビジュアルマップ、リサーチボード、フローチャート、依存関係マップ、プロジェクト概要、またはキャンバスを要求した場合は、.canvas ファイルを使用します。

Canvas ファイルは JSON で、トップレベルの nodes と edges 配列を持ちます。

• ノードには id、type、x、y、width、height が必要です。
• ノードタイプは text、file、link、group です。
• エッジには id、fromNode、toNode が必要です。オプションの側面は top、right、bottom、left です。
• ユニークな16文字の小文字16進数 ID を生成します。
• JSON 文字列値にはリテラルの \n ではなく実際の改行を使用します。ただし、テキストにそれらの文字を表示する必要がある場合は除きます。
• ノード間は50〜100px 空け、グリッドに揃え、グループノードは子を収容できる大きさに保ちます。
• 編集後に検証: python3 "$HELPER" validate-canvas "Maps/Topic.canvas"。

Web Clipping And Source Extraction

ユーザーがボールトに取り込む URL を提供した場合:

• ローカルに defuddle コマンドが存在する場合は、defuddle parse <url> --md を優先します。これは読み取り可能な Markdown を抽出し、ナビゲーションのノイズを除去します。
• defuddle はここではデフォルトでインストールされていません。まず確認し、そうでなければエージェントの Web フェッチ/検索ツールを使用し、ボールトには永続的な事実とリンクのみを保存します。
• 既に生の Markdown を指している URL には Defuddle を使用しないでください。
• ソース URL、著者/日付（利用可能な場合）、取得日、処理ステータスを frontmatter に保存します。
• 長いソースの場合は、ソースサマリーノートを作成し、永続的な概念/プロジェクト/エンティティノートを更新します。Wiki レイヤーに記事全体をダンプしないでください。

Obsidian CLI And App

Obsidian が実行中で obsidian コマンドが利用可能な場合、アプリ認識アクションに使用します:

obsidian help
obsidian read file="My Note"
obsidian search query="term" limit=10
obsidian property:set name="status" value="done" file="My Note"
obsidian backlinks file="My Note"
obsidian daily:append content="- [ ] Follow up"

プラグインやテーマのデバッグには、コード変更後にアプリ認識コマンドを優先します:

obsidian plugin:reload id=my-plugin
obsidian dev:errors
obsidian dev:console level=error
obsidian dev:screenshot path=screenshot.png
obsidian dev:dom selector=".workspace-leaf" text

CLI がインストールされていない場合や Obsidian が実行されていない場合は、ボールトファイル操作と obsidian:// URI スキームにフォールバックします。ヘルパーの open コマンドは Flatpak アプリと URI フォールバックを既に処理しています:

python3 "$HELPER" open "技術/00-System/index.md"

Ingest, Query, and Lint

ユーザーがソースを提供したり、外部のアーティファクトから知識を追加するよう依頼した場合、取り込み（ingest）動作を使用します:

• ソースを読み、永続的な事実、決定、概念、エンティティ、未解決の質問、矛盾を特定します。
• 新しいページを作成する前に、ボールト内の既存のページを検索します。
• 後で有用になる場合のみ、ソースサマリーノートを作成します。
• 新しいソースページだけでなく、関連する既存の概念/プロジェクト/エンティティノートも更新します。
• 新しい知識が既存のノートから到達可能になるように、バックリンクと related エントリを追加します。
• 取り込んだ内容とどのページが変更されたかを説明するログエントリを追加します。

ボールトから回答する場合、クエリ動作を使用します:

• 利用可能な場合は、最初にインデックス/スキーマノートを読みます。
• 回答する前に、関連するノートを検索して読みます。
• 回答では、ローカルノートを Wiki リンクまたはパスで引用します。
• 回答が永続的な統合を生み出す場合は、それをノートとして書き戻すか、既存のノートを更新することを提案します。

メンテナンスには lint 動作を使用します:

• 欠落している frontmatter、欠落している関連セクション、孤立ノート、重複タイトル、古い主張、不正なリンク、ページがない重要な概念をチェックします。
• 広範囲のクリーンアップを行う前に、焦点を絞った修復計画を報告することを優先します。
• 要求されたクリーンアップの場合は、リンクとメタデータを小バッチで修復し、パスをログに記録します。

Helper Commands

ヘルパーはデフォルトで ${OBSIDIAN_VAULT:-$HOME/workspace/notes} を対象とし（--vault で上書き可能）、ボールト外のパスへのアクセスを拒否します。完全なコマンド一覧は python3 "$HELPER" --help を実行してください。

# タイトルとコンテンツを検索
python3 "$HELPER" search "query"

# 相対パスでノートを読む
python3 "$HELPER" read "AI/example.md"

# 親フォルダも含めてノートを作成
python3 "$HELPER" create "AI/example.md" --title "Example" --tags project,active --body $'# Example\n\n...'

# ノートを検査した後に置換
python3 "$HELPER" update "AI/example.md" --body "...full markdown..."

# ユーザーが明示的に要求した場合のみ削除
python3 "$HELPER" delete "AI/old-note.md" --yes

# Obsidian でノートを開く
python3 "$HELPER" open "AI/example.md"

# Base を作成して検証
python3 "$HELPER" create-base "技術/00-System/active-projects.base" --name "Active Projects"
python3 "$HELPER" validate-base "技術/00-System/active-projects.base"

# Canvas を作成して検証
python3 "$HELPER" create-canvas "AI/Maps/project-overview.canvas"
python3 "$HELPER" validate-canvas "AI/Maps/project-overview.canvas"

# Wiki スタイルのインデックスを技術/00-System/index.md に再生成
python3 "$HELPER" index