> ## Documentation Index
> Fetch the complete documentation index at: https://factory-docs-model-update-cl-824.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# プラグインの構築
> Droid向けにスキル、コマンド、ツールを含む共有可能なプラグインを作成する。
このガイドでは、Droidのプラグイン作成方法を説明します。プラグインは、スキル、コマンド、ツールを共有可能なパッケージにまとめ、プロジェクトやチーム間で利用できるものです。
## クイックスタート
```bash theme={null}
mkdir -p my-plugin/.factory-plugin
```
`my-plugin/.factory-plugin/plugin.json`を作成します:
```json theme={null}
{
"name": "my-plugin",
"description": "A helpful plugin description",
"version": "1.0.0"
}
```
`my-plugin/commands/hello.md`を作成します:
```markdown theme={null}
---
description: Greet the user with a friendly message
---
Greet the user warmly and ask how you can help them today.
```
テストのためローカルディレクトリからインストールします:
```bash theme={null}
droid plugin marketplace add ./my-plugin
droid plugin install my-plugin@my-plugin
```
次に`/hello`を実行してテストします。
## プラグインマニフェスト
`.factory-plugin/plugin.json`にあるマニフェストファイルは、プラグインのメタデータを定義します：
```json theme={null}
{
"name": "my-plugin",
"description": "What this plugin does",
"version": "1.0.0",
"author": {
"name": "Your Name",
"email": "you@example.com"
},
"homepage": "https://github.com/you/my-plugin",
"repository": "https://github.com/you/my-plugin",
"license": "MIT"
}
```
### 必須フィールド
| フィールド | 説明 |
| ------------- | ------------------------ |
| `name` | 一意の識別子。小文字、数字、ハイフンを使用。 |
| `description` | プラグインマネージャーに表示される短い説明。 |
| `version` | セマンティックバージョン（例：`1.0.0`）。 |
### オプションフィールド
| フィールド | 説明 |
| ------------ | ------------------------------- |
| `author` | `name`と任意の`email`を含むオブジェクト。 |
| `homepage` | プラグインドキュメントのURL。 |
| `repository` | GitリポジトリのURL。 |
| `license` | ライセンス識別子（例：`MIT`、`Apache-2.0`）。 |
## スキルの追加
スキルはモデルによって呼び出される機能です。`skills/`ディレクトリに作成してください：
```
my-plugin/
└── skills/
└── code-review/
└── SKILL.md
```
### スキル形式
```markdown theme={null}
---
name: code-review
description: ベストプラクティスと潜在的な問題についてコードをレビューする。コードレビュー、PR確認、コード品質分析で使用します。
---
コードをレビューするときは、以下を確認します:
1. コードの整理と構造
2. エラーハンドリング
3. セキュリティ上の懸念
4. テストカバレッジ
行参照付きで具体的かつ実行可能なフィードバックを提供します。
```
### スキルのフロントマター
| フィールド | 必須 | 説明 |
| -------------------------- | --- | ------------------------------------ |
| `name` | はい | スキルの一意識別子 |
| `description` | はい | このスキルをいつ使用するか（モデルがいつ呼び出すかを判断するのに役立つ） |
| `disable-model-invocation` | いいえ | ユーザー専用にするには`true`を設定 |
| `allowed-tools` | いいえ | スキルが使用できるツールを制限 |
## コマンドの追加
コマンドはスラッシュ記法でユーザーによって呼び出されます。`commands/`ディレクトリに作成してください：
```
my-plugin/
└── commands/
└── review-pr.md
```
### コマンド形式
```markdown theme={null}
---
description: 現在のPRに問題がないかレビューする
disable-model-invocation: true
---
# PRレビューコマンド
現在のプルリクエストをレビューします。以下を確認します:
1. コードの正確性とロジックエラー
2. テストカバレッジ
3. ドキュメント更新
4. 破壊的変更
ユーザーが引数を指定した場合: $ARGUMENTS
引数を使用してレビュー対象を特定の領域に絞ります。
```
`commands/review-pr.md`にあるコマンドは`/review-pr`になります。
### コマンド引数
ユーザー入力を取得するには`$ARGUMENTS`を使用します：
```markdown theme={null}
---
description: Greet a user by name
---
Greet the user named "$ARGUMENTS" warmly.
```
使用方法：`/greet Alice`
## エージェントの追加
`droids/`ディレクトリに特殊化されたサブエージェントを定義します：
```
my-plugin/
└── droids/
└── security-reviewer.md
```
### エージェント形式
```markdown theme={null}
---
name: security-reviewer
description: Reviews code for security vulnerabilities
model: inherit
tools: ["Read", "Grep", "Glob"]
---
You are a security expert. Review the code for:
1. Injection vulnerabilities (SQL, command, XSS)
2. Authentication/authorization issues
3. Sensitive data exposure
4. Insecure cryptography
5. Security misconfigurations
Report findings with severity levels and remediation steps.
```
完全なエージェント設定オプションについては[Custom Droids](/jp/cli/configuration/custom-droids)を参照してください。
## フックの追加
`hooks/hooks.json`でライフサイクルフックを定義します：
```
my-plugin/
└── hooks/
├── hooks.json
└── format-check.sh
```
### フック設定
```json theme={null}
{
"PostToolUse": [
{
"matcher": "Create|Edit|ApplyPatch",
"hooks": [
{
"type": "command",
"command": "${DROID_PLUGIN_ROOT}/hooks/format-check.sh",
"timeout": 30
}
]
}
]
}
```
### 環境変数
| 変数 | 説明 |
| ----------------------- | -------------------------------------------- |
| `${DROID_PLUGIN_ROOT}` | プラグインディレクトリへの絶対パス |
| `${CLAUDE_PLUGIN_ROOT}` | `${DROID_PLUGIN_ROOT}`のエイリアス（Claude Code互換性） |
プラグインフックは`/hooks import`ではインポートできません。プラグインのルートパスを解決できるインストール済みプラグイン内でのみ機能します。
## MCPサーバーの追加
プラグインルートの`mcp.json`でMCPサーバーを設定します：
```json theme={null}
{
"mcpServers": {
"my-api": {
"command": "npx",
"args": ["-y", "@example/mcp-server"],
"env": {
"API_KEY": "${MY_API_KEY}"
}
}
}
}
```
## プラグインのテスト
### ローカルテスト
開発中のテストには、ローカルディレクトリからインストールします：
```bash theme={null}
droid plugin marketplace add ./my-plugin
droid plugin install my-plugin@my-plugin
```
### 検証チェックリスト
プラグインを共有する前に：
* [ ] マニフェストに必須フィールドがある（`name`、`description`、`version`）
* [ ] すべてのスキルのフロントマターに`name`と`description`がある
* [ ] コマンドが引数ありでもなしでも動作する
* [ ] ハードコードされたパスや機械固有の設定がない
* [ ] READMEですべてのコマンドと機能が文書化されている
## プラグインの配布
### マーケットプレースの作成
マーケットプレースは、利用可能なプラグインをリストするマニフェストを含むGitリポジトリです：
```
my-marketplace/
├── .factory-plugin/
│ └── marketplace.json
├── plugin-one/
│ └── .factory-plugin/
│ └── plugin.json
└── plugin-two/
└── .factory-plugin/
└── plugin.json
```
### マーケットプレースマニフェスト
`.factory-plugin/marketplace.json`を作成します：
```json theme={null}
{
"name": "my-marketplace",
"description": "A collection of useful plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "plugin-one",
"description": "Description of plugin one",
"source": "./plugin-one"
},
{
"name": "plugin-two",
"description": "Description of plugin two",
"source": "./plugin-two"
}
]
}
```
| フィールド | 必須 | 説明 |
| ----------------------- | --- | -------------------------------------------------------------------------- |
| `name` | はい | マーケットプレース識別子 |
| `description` | いいえ | マーケットプレースを閲覧時に表示 |
| `owner` | いいえ | 連絡先情報 |
| `plugins[].name` | はい | プラグイン識別子 |
| `plugins[].source` | はい | プラグインの取得元。相対パス文字列または source オブジェクトです。[プラグインソース](#plugin-sources)を参照してください。 |
| `plugins[].description` | いいえ | プラグインブラウザに表示 |
| `plugins[].category` | いいえ | プラグインを整理するため |
プラグインソース
各プラグインエントリの `source` フィールドは、Droid にプラグインの取得元を伝えます。既定の形式である `"./plugin-one"` のような相対パス文字列は、マーケットプレースリポジトリ内のディレクトリを指します。別の場所にあるプラグインには、source オブジェクトを使用します。
固定方法はソースタイプによって異なります。Git ベースのソース（`github`、`url`、`git-subdir`）は、`ref`（ブランチまたはタグ）または `sha` によりプラグインごとに固定されます。相対パスのプラグインは、それらが含まれているマーケットプレースソースを固定することで固定されます。`npm` プラグインは `version` フィールドで固定され、npm のバージョン解決に従います。
| ソースタイプ | フィールド | 使用する場面 |
| :----------- | :----------------------------------------------------- | :--------------------------------------------------------------- |
| 相対パス | `"./path/to/plugin"` | プラグインがマーケットプレースリポジトリ内にある場合。 |
| `github` | `repo`, `ref?`, `sha?` | プラグインが専用の GitHub リポジトリでホストされている場合。 |
| `url` | `url`, `ref?`, `sha?` | プラグインが GitHub 以外の git ホスト（GitLab、Bitbucket、セルフホストなど）でホストされている場合。 |
| `git-subdir` | `url`, `path`, `ref?`, `sha?` | モノレポなどの大きな git リポジトリ内のサブディレクトリにプラグインがある場合。 |
| `npm` | `package`, `version?`, `registry?`, `authTokenEnvVar?` | プラグインが npm パッケージとして公開されている場合。 |
#### npm パッケージ
すでにプライベートレジストリ（Artifactory、CodeArtifact、GitHub Packages、Verdaccio など）へ配布しており、その経路を Droid プラグインにも再利用したい場合は、プラグインを npm パッケージとして配布します。npm レジストリ上の公開パッケージも同様に動作します。npm ソースでは、固定と更新は `version` フィールドによる npm のバージョン解決に従います。[バージョン管理](#version-management) にある Git コミットハッシュの指針は、Git ベースのソースにのみ適用されます。
`npm` がインストールされ、`PATH` から利用できる必要があります。利用できない場合、CLI は明確なエラーを表示します。
```json theme={null}
{
"name": "pr-triage",
"source": {
"source": "npm",
"package": "@your-org/droid-pr-triage"
}
}
```
特定のバージョンまたは範囲に固定するには:
```json theme={null}
{
"name": "pr-triage",
"source": {
"source": "npm",
"package": "@your-org/droid-pr-triage",
"version": "2.4.0"
}
}
```
プライベートレジストリからインストールするには:
```json theme={null}
{
"name": "pr-triage",
"source": {
"source": "npm",
"package": "@your-org/droid-pr-triage",
"version": "^2.0.0",
"registry": "https://npm.your-org.example"
}
}
```
トークンが必要なプライベートレジストリ（たとえば JFrog Artifactory、AWS CodeArtifact、GitHub Packages）で認証するには:
```json theme={null}
{
"name": "pr-triage",
"source": {
"source": "npm",
"package": "@your-org/droid-pr-triage",
"registry": "https://acme.jfrog.io/artifactory/api/npm/npm-virtual/",
"authTokenEnvVar": "JFROG_NPM_TOKEN"
}
}
```
ユーザーは Droid を起動する前に、指定された環境変数を設定しておく必要があります:
```bash theme={null}
# bash/zsh
export JFROG_NPM_TOKEN="your-token-here"
```
```powershell theme={null}
# PowerShell
$env:JFROG_NPM_TOKEN="your-token-here"
```
トークンをソース管理にコミットしたり、マーケットプレース JSON に貼り付けたりしないでください。`authTokenEnvVar` フィールドには、シークレットそのものではなく環境変数名だけが保存されます。
| フィールド | 必須 | 説明 |
| :---------------- | :-- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `package` | はい | npm パッケージ名。スコープ付きパッケージ（`@scope/name`）にも対応します。 |
| `version` | いいえ | npm のバージョン、範囲、または dist-tag（例: `2.4.0`、`^2.0.0`、`latest`）。既定値は `latest` です。tarball URL、`file:` パス、`git+...` 指定、`npm:` エイリアスは拒否されます。ソースは設定済みレジストリ経由で解決される必要があります。 |
| `registry` | いいえ | カスタムレジストリ URL。既定ではシステムの npm レジストリを使用します。認証情報、クエリ文字列、フラグメントを埋め込まない `https://` URL である必要があります。これにより、シークレットはマーケットプレース JSON ではなくレジストリクライアント設定に保持されます。この設定はインストール実行時にのみ適用され、グローバルな `~/.npmrc` に書き込まれることはありません。 |
| `authTokenEnvVar` | いいえ | プライベートレジストリ用の認証トークンを保持する環境変数名（例: `JFROG_NPM_TOKEN`）。有効なシェル変数名（`[A-Za-z_][A-Za-z0-9_]*`）である必要があります。`registry` も設定されている場合にのみ有効です。インストール時に、Droid はこの変数からトークンを読み取り、一時的な `.npmrc` にレジストリパス単位の `_authToken` エントリを書き込みます。この `.npmrc` はインストール後にクリーンアップされます。変数が設定されていない場合、インストールは明確なエラーを出して早い段階で失敗します。 |
**レイアウト要件。** 公開パッケージのルートにはプラグインマニフェストが含まれている必要があります。Droid ネイティブのレイアウト（`.factory-plugin/plugin.json`、`droids/`、`mcp.json`）と Claude Code のレイアウト（`.claude-plugin/plugin.json`、`agents/`、`.mcp.json`）の両方を受け付けます。Claude Code レイアウトは、パッケージがプラグインキャッシュにコピーされる際に Droid 形式へ変換されます。
一般的な公開パッケージの構成は次のとおりです:
```
@your-org/droid-pr-triage/
├── .factory-plugin/
│ └── plugin.json
├── package.json
├── skills/
│ └── classify/
│ └── SKILL.md
├── droids/
│ └── triage-reviewer.md
└── README.md
```
プラグイン本体だけが配布されるよう、`package.json` の `files` フィールドを設定します:
```json theme={null}
{
"name": "@your-org/droid-pr-triage",
"version": "2.4.0",
"files": [
".factory-plugin",
"skills",
"droids",
"mcp.json",
"hooks",
"README.md"
]
}
```
**ハードニング。** Droid はプラグインごとの一時ディレクトリで `npm install` を `--ignore-scripts`、`--no-save`、`--no-audit`、`--no-fund` とともに実行します。ライフサイクルスクリプト（`postinstall`、`preinstall` など）は実行されず、グローバルな npm 設定も参照・変更されません。ライフサイクルスクリプトはスキップされるため、`postinstall` のビルドステップに依存するパッケージでは利用可能な内容が配布されません。事前ビルド済み成果物を公開し（`npm publish` の前にビルドを実行し）、`files` の許可リスト配下の内容をそのまま利用できる状態にしてください。
`npm:` は有効なマーケットプレースソースではありません。Droid が `npm` を受け付けるのは、マーケットプレースの `marketplace.json` 内にあるプラグインごとのソースとしてのみです。完全なマーケットプレースリポジトリを用意せずに、npm で公開した単一プラグインをチームに配布したい場合は、最小のラッパーマーケットプレースを公開してください（以下を参照）。
##### 単一の npm プラグイン向けラッパーマーケットプレース
専用のマーケットプレースリポジトリなしで npm 公開済みプラグインを 1 つ配布するには、任意のフォルダに小さな `marketplace.json` をコミットします。フォルダ名がそのままマーケットプレース名になります。
```
your-org-plugins/
└── .factory-plugin/
└── marketplace.json
```
```json theme={null}
{
"name": "your-org-plugins",
"owner": { "name": "Your Org Platform Team" },
"plugins": [
{
"name": "pr-triage",
"description": "Triage and label new pull requests for the on-call rotation",
"source": {
"source": "npm",
"package": "@your-org/droid-pr-triage",
"version": "^2.0.0"
}
}
]
}
```
チームメイトは、他のローカルマーケットプレースと同様に追加できます:
```bash theme={null}
droid plugin marketplace add ./your-org-plugins
droid plugin install pr-triage@your-org-plugins
```
バージョン管理
ドキュメント目的でプラグインマニフェストではセマンティックバージョニングを使用します：
* **メジャー**（1.0.0 → 2.0.0）：破壊的変更
* **マイナー**（1.0.0 → 1.1.0）：新機能、後方互換性あり
* **パッチ**（1.0.0 → 1.0.1）：バグ修正
Git ベースのプラグインソース（相対パス、`github`、`url`、`git-subdir`）では、Droid はセマンティックバージョンではなく Git コミットハッシュでプラグインバージョンを追跡します。デフォルトでは、プラグインを更新するとマーケットプレースから最新のコミットを取得します。プラグインを特定のバージョンに固定するには、マーケットプレースソースに `ref`（ブランチまたはタグ）または `sha`（フルコミット SHA）を設定して、プラグインが含まれるマーケットプレースを固定してください。詳細は[マーケットプレースをrefまたはコミットに固定する](/jp/cli/configuration/plugins#%E3%83%9E%E3%83%BC%E3%82%B1%E3%83%83%E3%83%88%E3%83%97%E3%83%AC%E3%82%A4%E3%82%B9%E3%82%92ref%E3%81%BE%E3%81%9F%E3%81%AF%E3%82%B3%E3%83%9F%E3%83%83%E3%83%88%E3%81%AB%E5%9B%BA%E5%AE%9A%E3%81%99%E3%82%8B)を参照してください。`npm` プラグインソースでは、代わりにプラグインごとの `version` フィールドに従って固定されます。
## Claude Code互換性
DroidはClaude Codeプラグインと完全に互換性があります。Claude Codeプラグインを見つけた場合、直接インストールでき、Droidが自動的に形式を変換します。
## ベストプラクティス
プラグインは単一の目的またはワークフローを中心に設計します。すべてを行う巨大なプラグインより、複数の小さなプラグインを優先してください。
READMEには以下を含めます:
* プラグインの内容
* インストール手順
* 利用可能なすべてのコマンドと使い方
* 設定オプション
* 例
更新がワークフローを壊す可能性があるタイミングをユーザーが把握できるよう、semver規約に従います。
該当する場合は、プラグインがmacOS、Linux、Windowsで動作することを確認します。移植性のあるシェルコマンドを使用し、プラットフォーム固有のパスを避けます。
スクリプトはユーザーをブロックせず、適切に失敗するべきです。エラーはログに記録し、セッションをクラッシュさせないでください。
明示的な同意なしにテレメトリを収集したりデータを送信したりしないでください。プラグインが行うネットワークリクエストは文書化してください。
## 例：完全なプラグイン
コードレビュープラグインの完全な例です：
```
code-review-plugin/
├── .factory-plugin/
│ └── plugin.json
├── commands/
│ └── review.md
├── skills/
│ └── review-patterns/
│ └── SKILL.md
├── droids/
│ └── reviewer.md
└── README.md
```
**`.factory-plugin/plugin.json`:**
```json theme={null}
{
"name": "code-review",
"description": "Automated code review with multiple specialized reviewers",
"version": "1.0.0",
"author": { "name": "Your Team" }
}
```
**`commands/review.md`:**
```markdown theme={null}
---
description: Run comprehensive code review on staged changes
---
Review the staged git changes using the review-patterns skill.
Focus on: $ARGUMENTS
If no focus area specified, perform a general review.
```
**`skills/review-patterns/SKILL.md`:**
```markdown theme={null}
---
name: review-patterns
description: Use when reviewing code to check for common issues and best practices.
---
以下についてコードを確認します:
- ロジックエラーとエッジケース
- エラーハンドリングの完全性
- セキュリティ脆弱性
- パフォーマンス上の懸念
- テストカバレッジの不足
```
**`droids/reviewer.md`:**
```markdown theme={null}
---
name: reviewer
description: 専門のコードレビュアーサブエージェント
model: inherit
tools: read-only
---
あなたはシニアコードレビュアーです。提供されたコードを分析して報告します:
Summary: <1行の評価>
Issues:
- <重大度> <説明>
Suggestions:
- <改善案>
```
## 次のステップ
プラグインのインストールと管理について学びます。
強力なスキルの作成を詳しく学びます。
ユーザー起動のスラッシュコマンドを作成します。
プラグイン用の専門サブエージェントを作成します。