カスタム出力パス
学習後にできること
-oまたは--outputフラグを使用してスキルを任意の位置の.mdファイルに同期する- ツールが存在しないファイルとディレクトリを自動作成する仕組みを理解する
- 異なるツール（Windsurf、Cursor など）用に異なる AGENTS.md を設定する
- 複数ファイル環境でスキルリストを管理する
- デフォルトの
AGENTS.mdをスキップし、既存のドキュメントシステムに統合する
前提知識
本チュートリアルでは、スキルの基礎同期 の使用方法を既に習得していることを前提としています。まだスキルをインストールしたことがない場合や、AGENTS.md を同期したことがない場合は、先に前提コースを完了してください。
現在の課題
openskills sync がデフォルトで AGENTS.md を生成することに慣れているかもしれませんが、以下のような問題に遭遇する可能性があります：
- ツールが特定のパスを必要とする: 一部の AI ツール（例：Windsurf）は、AGENTS.md をプロジェクトルートではなく特定のディレクトリ（例：
.ruler/）に配置することを期待しています - 複数ツールの競合: 複数のコーディングツールを同時に使用する場合、それぞれが AGENTS.md を異なる位置に期待する可能性があります
- 既存ドキュメントとの統合: すでにスキルリストドキュメントがあり、新しいファイルを作成するのではなく OpenSkills のスキルを統合したい場合
- ディレクトリが存在しない: ネストされたディレクトリ（例：
docs/ai-skills.md）に出力したいが、ディレクトリがまだ存在しない
これらの問題の根本原因は：デフォルトの出力パスがすべてのシナリオを満たせないことです。より柔軟な出力制御が必要です。
この機能を使用するタイミング
カスタム出力パスは以下のシナリオに適しています：
- 複数ツール環境: 異なる AI ツール用に独立した AGENTS.md を設定する（例：
.ruler/AGENTS.mdvsAGENTS.md） - ディレクトリ構造の要件: ツールが AGENTS.md を特定のディレクトリに期待する場合（例：Windsurf の
.ruler/） - 既存ドキュメントとの統合: スキルリストを既存のドキュメントシステムに統合し、新しい AGENTS.md を作成しない
- 組織的な管理: プロジェクトや機能ごとにスキルリストを分類して保存する（例：
docs/ai-skills.md） - CI/CD 環境: 自動化フローで固定パスに出力する
推奨事項
プロジェクトで単一の AI ツールのみを使用し、そのツールがプロジェクトルートの AGENTS.md をサポートしている場合は、デフォルトパスを使用してください。複数ファイル管理が必要な場合や、ツール固有のパス要件がある場合のみ、カスタム出力パスを使用してください。
🎒 開始前の準備
開始する前に、以下を確認してください：
- [ ] 少なくとも1つのスキルのインストール が完了している
- [ ] プロジェクトディレクトリに移動している
- [ ]
openskills syncの基本的な使用方法を理解している
前提チェック
インストール済みのスキルがあることを確認してください：
npx openskills listリストが空の場合は、先にスキルをインストールしてください：
npx openskills install anthropics/skills核心概念：柔軟な出力制御
OpenSkills の同期機能はデフォルトで AGENTS.md に出力しますが、-o または --output フラグを使用してカスタム出力パスを指定できます。
[デフォルト動作] [カスタム出力]
openskills sync → AGENTS.md (プロジェクトルート)
openskills sync -o custom.md → custom.md (プロジェクトルート)
openskills sync -o .ruler/AGENTS.md → .ruler/AGENTS.md (ネストされたディレクトリ)主な機能：
- 任意のパス: 任意の
.mdファイルパス（相対パスまたは絶対パス）を指定可能 - 自動ファイル作成: ファイルが存在しない場合、ツールが自動作成
- 自動ディレクトリ作成: ファイルの親ディレクトリが存在しない場合、ツールが再帰的に作成
- スマートタイトル: ファイル作成時、ファイル名に基づいたタイトルを自動追加（例：
# AGENTS） - 形式検証:
.mdで終わる必要があり、そうでない場合はエラー
なぜこの機能が必要なのか？
異なる AI ツールは異なるパスを期待する可能性があります：
| ツール | 期待されるパス | デフォルトパスは使用可能 |
|---|---|---|
| Claude Code | AGENTS.md | ✅ 使用可能 |
| Cursor | AGENTS.md | ✅ 使用可能 |
| Windsurf | .ruler/AGENTS.md | ❌ 使用不可 |
| Aider | .aider/agents.md | ❌ 使用不可 |
-o フラグを使用することで、各ツールに正しいパスを設定できます。
実践ガイド
ステップ 1：基本用法 - 現在のディレクトリに出力
まず、スキルを現在のディレクトリのカスタムファイルに同期してみましょう：
npx openskills sync -o my-skills.md理由
-o my-skills.md を使用して、ツールにデフォルトの AGENTS.md ではなく my-skills.md に出力するように指示します。
表示される内容：
my-skills.md が存在しない場合、ツールが作成します：
Created my-skills.md次に、インタラクティブ選択インターフェースが起動します：
Found 2 skill(s)
? Select skills to sync to my-skills.md:
❯ ◉ pdf (project) Comprehensive PDF manipulation toolkit...
◉ git-workflow (project) Git workflow: Best practices for commits...
<Space> 選択 <a> 全選択 <i> 反転 <Enter> 確認スキルを選択すると、以下が表示されます：
✅ Synced 2 skill(s) to my-skills.md生成されたファイルの確認
生成されたファイルを確認してください：
cat my-skills.md以下が表示されます：
<!-- ファイルタイトル：# my-skills -->
<skills_system priority="1">
## Available Skills
<!-- SKILLS_TABLE_START -->
<usage>
When users ask you to perform tasks, check if any of available skills below can help...
</usage>
<available_skills>
<skill>
<name>pdf</name>
<description>Comprehensive PDF manipulation toolkit...</description>
<location>project</location>
</skill>
</available_skills>
<!-- SKILLS_TABLE_END -->
</skills_system>最初の行は # my-skills で、これはツールがファイル名に基づいて自動生成したタイトルです。
ステップ 2：ネストされたディレクトリに出力
次に、存在しないネストされたディレクトリにスキルを同期してみましょう：
npx openskills sync -o .ruler/AGENTS.md理由
一部のツール（例：Windsurf）は AGENTS.md を .ruler/ ディレクトリに期待します。ディレクトリが存在しない場合、ツールが自動作成します。
表示される内容：
.ruler/ ディレクトリが存在しない場合、ツールがディレクトリとファイルを作成します：
Created .ruler/AGENTS.md次に、インタラクティブ選択インターフェースが起動します（前のステップと同様）。
操作ガイド：
┌─────────────────────────────────────────────────────────────┐
│ ディレクトリ自動作成の説明 │
│ │
│ 入力コマンド：openskills sync -o .ruler/AGENTS.md │
│ │
│ ツールの実行： │
│ 1. .ruler ディレクトリの存在確認 → 存在しない │
│ 2. .ruler ディレクトリの再帰的作成 → mkdir .ruler │
│ 3. .ruler/AGENTS.md の作成 → # AGENTS タイトルを書き込み │
│ 4. スキル内容の同期 → XML 形式のスキルリストを書き込み │
│ │
│ 結果：.ruler/AGENTS.md ファイルが生成され、スキルが同期されました │
└─────────────────────────────────────────────────────────────┘再帰的作成
ツールは存在しないすべての親ディレクトリを再帰的に作成します。例：
docs/ai/skills.md-docsとdocs/aiが存在しない場合、両方が作成されます.config/agents.md- 隠しディレクトリ.configが作成されます
ステップ 3：複数ファイル管理 - 異なるツール用に設定
Windsurf と Cursor を同時に使用し、それぞれに異なる AGENTS.md を設定する必要があると仮定します：
<!-- Windsurf 用に設定（.ruler/AGENTS.md を期待） -->
npx openskills sync -o .ruler/AGENTS.md
<!-- Cursor 用に設定（プロジェクトルートの AGENTS.md を使用） -->
npx openskills sync理由
異なるツールは AGENTS.md を異なる位置に期待する可能性があります。-o を使用することで、各ツールに正しいパスを設定し、競合を回避できます。
表示される内容：
2つのファイルがそれぞれ生成されます：
<!-- Windsurf の AGENTS.md を確認 -->
cat .ruler/AGENTS.md
<!-- Cursor の AGENTS.md を確認 -->
cat AGENTS.mdファイルの独立性
各 .md ファイルは独立しており、独自のスキルリストを含みます。異なるファイルで異なるスキルを選択できます：
.ruler/AGENTS.md- Windsurf 用に選択したスキルAGENTS.md- Cursor 用に選択したスキルdocs/ai-skills.md- ドキュメント内のスキルリスト
ステップ 4：カスタムファイルへの非インタラクティブ同期
CI/CD 環境では、インタラクティブ選択をスキップし、すべてのスキルをカスタムファイルに直接同期する必要がある場合があります：
npx openskills sync -o .ruler/AGENTS.md -y理由
-y フラグはインタラクティブ選択をスキップし、すべてのインストール済みスキルを同期します。-o フラグと組み合わせることで、自動化フローでカスタムパスに出力できます。
表示される内容：
Created .ruler/AGENTS.md
✅ Synced 2 skill(s) to .ruler/AGENTS.mdCI/CD 使用シナリオ
CI/CD スクリプトで使用する場合：
#!/bin/bash
<!-- スキルのインストール -->
npx openskills install anthropics/skills -y
<!-- カスタムファイルへの同期（非インタラクティブ） -->
npx openskills sync -o .ruler/AGENTS.md -yステップ 5：出力ファイルの検証
最後に、出力ファイルが正しく生成されたことを確認します：
<!-- ファイル内容を表示 -->
cat .ruler/AGENTS.md
<!-- ファイルが存在することを確認 -->
ls -l .ruler/AGENTS.md
<!-- スキル数を確認 -->
grep -c "<name>" .ruler/AGENTS.md表示される内容：
- ファイルに正しいタイトルが含まれている（例：
# AGENTS） - ファイルに
<skills_system>XML タグが含まれている - ファイルに
<available_skills>スキルリストが含まれている - 各
<skill>に<name>、<description>、<location>が含まれている
出力パスの確認
現在の作業ディレクトリが不明な場合は、以下を使用できます：
<!-- 現在のディレクトリを表示 -->
pwd
<!-- 相対パスがどこに解決されるかを表示 -->
realpath .ruler/AGENTS.mdチェックポイント ✅
上記のステップを完了したら、以下を確認してください：
- [ ]
-oフラグを使用してカスタムファイルに正常に出力した - [ ] ツールが存在しないファイルを自動作成した
- [ ] ツールが存在しないネストされたディレクトリを自動作成した
- [ ] 生成されたファイルに正しいタイトル（ファイル名に基づく）が含まれている
- [ ] 生成されたファイルに
<skills_system>XML タグが含まれている - [ ] 生成されたファイルに完全なスキルリストが含まれている
- [ ] 異なるツール用に異なる出力パスを設定できる
- [ ] CI/CD 環境で
-yと-oの組み合わせを使用できる
上記のチェック項目がすべて合格した場合、おめでとうございます！カスタム出力パスの使用方法を習得し、スキルを任意の位置に柔軟に同期できるようになりました。
トラブルシューティング
問題 1：出力ファイルが markdown ではない
現象：
Error: Output file must be a markdown file (.md)原因：
-o フラグを使用する際、指定したファイルの拡張子が .md ではありませんでした。ツールは AI ツールが正しく解析できるように、markdown ファイルへの出力を強制しています。
解決方法：
出力ファイルが .md で終わることを確認してください：
<!-- ❌ 誤り -->
npx openskills sync -o skills.txt
<!-- ✅ 正しい -->
npx openskills sync -o skills.md問題 2：ディレクトリ作成の権限エラー
現象：
Error: EACCES: permission denied, mkdir '.ruler'原因：
ディレクトリの作成を試みた際、現在のユーザーに親ディレクトリへの書き込み権限がありませんでした。
解決方法：
- 親ディレクトリの権限を確認してください：
ls -ld .- 権限が不足している場合は、管理者に連絡するか、権限のあるディレクトリを使用してください：
<!-- プロジェクトディレクトリを使用 -->
cd ~/projects/my-project
npx openskills sync -o .ruler/AGENTS.md問題 3：出力パスが長すぎる
現象：
ファイルパスが長く、コマンドの可読性と保守性が低下しています：
npx openskills sync -o docs/ai/skills/v2/internal/agents.md原因：
ネストされたディレクトリが深すぎて、パスが管理しにくくなっています。
解決方法：
- 相対パスを使用する（プロジェクトルートから開始）
- ディレクトリ構造を簡素化する
- シンボリックリンクの使用を検討する（シンボリックリンクサポート を参照）
<!-- 推奨：フラットなディレクトリ構造 -->
npx openskills sync -o docs/agents.md問題 4：-o フラグの使用を忘れた
現象：
カスタムファイルへの出力を期待したが、ツールはデフォルトの AGENTS.md に出力しました。
原因：
-o フラグの使用を忘れたか、スペルミスがありました。
解決方法：
- コマンドに
-oまたは--outputが含まれていることを確認してください：
<!-- ❌ 誤り：-o フラグを忘れた -->
npx openskills sync
<!-- ✅ 正しい：-o フラグを使用 -->
npx openskills sync -o .ruler/AGENTS.md--output完全形式を使用する（より明確）：
npx openskills sync --output .ruler/AGENTS.md問題 5：ファイル名に特殊文字が含まれている
現象：
ファイル名にスペースや特殊文字が含まれており、パス解析エラーが発生しています：
npx openskills sync -o "my skills.md"原因：
一部のシェルは特殊文字の処理方法が異なり、パスエラーの原因となる可能性があります。
解決方法：
- スペースと特殊文字の使用を避ける
- どうしても使用する必要がある場合は、引用符で囲む：
<!-- 推奨しない -->
npx openskills sync -o "my skills.md"
<!-- 推奨 -->
npx openskills sync -o my-skills.md本レッスンのまとめ
本レッスンでは、以下を学びました：
-oまたは--outputフラグの使用 - スキルをカスタムの.mdファイルに同期する- ファイルとディレクトリの自動作成 の仕組み - 手動でディレクトリ構造を準備する必要なし
- 異なるツール用に異なる AGENTS.md を設定 - 複数ツールの競合を回避
- 複数ファイル管理のテクニック - ツールや機能ごとにスキルリストを分類して保存
- CI/CD 環境での使用 -
-yと-oの組み合わせで自動化同期を実現
核心コマンド：
| コマンド | 作用 |
|---|---|
npx openskills sync -o custom.md | プロジェクトルートの custom.md に同期 |
npx openskills sync -o .ruler/AGENTS.md | .ruler/AGENTS.md に同期（ディレクトリ自動作成） |
npx openskills sync -o path/to/file.md | 任意のパスに同期（ネストされたディレクトリ自動作成） |
npx openskills sync -o custom.md -y | カスタムファイルへの非インタラクティブ同期 |
重要なポイント：
- 出力ファイルは
.mdで終わる必要がある - ツールは存在しないファイルとディレクトリを自動作成する
- ファイル作成時、ファイル名に基づいたタイトルを自動追加する
- 各
.mdファイルは独立しており、独自のスキルリストを含む - 複数ツール環境、ディレクトリ構造要件、既存ドキュメント統合などのシナリオに適している
次のレッスンの予告
次のレッスンでは シンボリックリンクサポート を学びます。
学習内容：
- git ベースのスキル更新を実現するシンボリックリンクの使用方法
- シンボリックリンクの利点と使用シナリオ
- ローカル開発でのスキル管理方法
- シンボリックリンクの検出と処理メカニズム
カスタム出力パスによりスキルリストの位置を柔軟に制御できるようになりましたが、シンボリックリンクはより高度なスキル管理方式を提供し、特にローカル開発シナリオに適しています。
付録：ソースコード参照
クリックしてソースコードの位置を表示
更新日：2026-01-24
| 機能 | ファイルパス | 行号 |
|---|---|---|
| sync コマンドエントリ | src/commands/sync.ts | 18-109 |
| CLI オプション定義 | src/cli.ts | 66 |
| 出力パス取得 | src/commands/sync.ts | 19 |
| 出力ファイル検証 | src/commands/sync.ts | 22-26 |
| 存在しないファイルの作成 | src/commands/sync.ts | 28-36 |
| 再帰的ディレクトリ作成 | src/commands/sync.ts | 31-32 |
| 自動タイトル生成 | src/commands/sync.ts | 34 |
| インタラクティブプロンプトでの出力ファイル名使用 | src/commands/sync.ts | 70 |
重要な関数：
syncAgentsMd(options: SyncOptions)- 指定された出力ファイルにスキルを同期options.output- カスタム出力パス（オプション、デフォルト 'AGENTS.md'）
重要な定数：
'AGENTS.md'- デフォルト出力ファイル名'.md'- 強制されるファイル拡張子
重要なロジック：
- 出力ファイルは
.mdで終わる必要があり、そうでない場合はエラーで終了（sync.ts:23-26） - ファイルが存在しない場合、親ディレクトリ（再帰的）とファイルを自動作成（sync.ts:28-36）
- ファイル作成時、ファイル名に基づいたタイトルを書き込む：
# ${outputName.replace('.md', '')}（sync.ts:34） - インタラクティブプロンプトで出力ファイル名を表示（sync.ts:70）
- 同期成功メッセージで出力ファイル名を表示（sync.ts:105, 107）