プラグインの構築 - Factory Documentation

このガイドでは、Droidのプラグイン作成方法を説明します。プラグインは、スキル、コマンド、ツールを共有可能なパッケージにまとめ、プロジェクトやチーム間で利用できるものです。

クイックスタート

プラグインディレクトリを作成

mkdir -p my-plugin/.factory-plugin

マニフェストを作成

my-plugin/.factory-plugin/plugin.jsonを作成します:

{
  "name": "my-plugin",
  "description": "A helpful plugin description",
  "version": "1.0.0"
}

コマンドを追加

my-plugin/commands/hello.mdを作成します:

---
description: Greet the user with a friendly message
---

Greet the user warmly and ask how you can help them today.

プラグインをテスト

テストのためローカルディレクトリからインストールします:

droid plugin marketplace add ./my-plugin
droid plugin install my-plugin@my-plugin

次に/helloを実行してテストします。

プラグインマニフェスト

.factory-plugin/plugin.jsonにあるマニフェストファイルは、プラグインのメタデータを定義します：

{
  "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

スキル形式

---
name: code-review
description: ベストプラクティスと潜在的な問題についてコードをレビューする。コードレビュー、PR確認、コード品質分析で使用します。
---

コードをレビューするときは、以下を確認します:
1. コードの整理と構造
2. エラーハンドリング
3. セキュリティ上の懸念
4. テストカバレッジ

行参照付きで具体的かつ実行可能なフィードバックを提供します。

スキルのフロントマター

フィールド	必須	説明
`name`	はい	スキルの一意識別子
`description`	はい	このスキルをいつ使用するか（モデルがいつ呼び出すかを判断するのに役立つ）
`disable-model-invocation`	いいえ	ユーザー専用にするには`true`を設定
`allowed-tools`	いいえ	スキルが使用できるツールを制限

コマンドの追加

コマンドはスラッシュ記法でユーザーによって呼び出されます。commands/ディレクトリに作成してください：

my-plugin/
└── commands/
    └── review-pr.md

コマンド形式

---
description: 現在のPRに問題がないかレビューする
disable-model-invocation: true
---

# PRレビューコマンド

現在のプルリクエストをレビューします。以下を確認します:
1. コードの正確性とロジックエラー
2. テストカバレッジ
3. ドキュメント更新
4. 破壊的変更

ユーザーが引数を指定した場合: $ARGUMENTS

引数を使用してレビュー対象を特定の領域に絞ります。

commands/review-pr.mdにあるコマンドは/review-prになります。

コマンド引数

ユーザー入力を取得するには$ARGUMENTSを使用します：

---
description: Greet a user by name
---

Greet the user named "$ARGUMENTS" warmly.

使用方法：/greet Alice

エージェントの追加

droids/ディレクトリに特殊化されたサブエージェントを定義します：

my-plugin/
└── droids/
    └── security-reviewer.md

エージェント形式

---
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を参照してください。

フックの追加

hooks/hooks.jsonでライフサイクルフックを定義します：

my-plugin/
└── hooks/
    ├── hooks.json
    └── format-check.sh

フック設定

{
  "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サーバーを設定します：

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

プラグインのテスト

ローカルテスト

開発中のテストには、ローカルディレクトリからインストールします：

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を作成します：

{
  "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 オブジェクトです。プラグインソースを参照してください。
`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?`	プラグインが npm パッケージとして公開されている場合。

npm パッケージ

すでにプライベートレジストリ（Artifactory、CodeArtifact、GitHub Packages、Verdaccio など）へ配布しており、その経路を Droid プラグインにも再利用したい場合は、プラグインを npm パッケージとして配布します。npm レジストリ上の公開パッケージも同様に動作します。npm ソースでは、固定と更新は version フィールドによる npm のバージョン解決に従います。バージョン管理にある Git コミットハッシュの指針は、Git ベースのソースにのみ適用されます。 npm がインストールされ、PATH から利用できる必要があります。利用できない場合、CLI は明確なエラーを表示します。

{
  "name": "pr-triage",
  "source": {
    "source": "npm",
    "package": "@your-org/droid-pr-triage"
  }
}

特定のバージョンまたは範囲に固定するには:

{
  "name": "pr-triage",
  "source": {
    "source": "npm",
    "package": "@your-org/droid-pr-triage",
    "version": "2.4.0"
  }
}

プライベートレジストリからインストールするには:

{
  "name": "pr-triage",
  "source": {
    "source": "npm",
    "package": "@your-org/droid-pr-triage",
    "version": "^2.0.0",
    "registry": "https://npm.your-org.example"
  }
}

フィールド	必須	説明
`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` に書き込まれることはありません。

レイアウト要件。 公開パッケージのルートにはプラグインマニフェストが含まれている必要があります。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 フィールドを設定します:

{
  "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

{
  "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"
      }
    }
  ]
}

チームメイトは、他のローカルマーケットプレースと同様に追加できます:

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またはコミットに固定するを参照してください。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:

{
  "name": "code-review",
  "description": "Automated code review with multiple specialized reviewers",
  "version": "1.0.0",
  "author": { "name": "Your Team" }
}

commands/review.md:

---
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:

---
name: review-patterns
description: Use when reviewing code to check for common issues and best practices.
---

以下についてコードを確認します:
- ロジックエラーとエッジケース
- エラーハンドリングの完全性
- セキュリティ脆弱性
- パフォーマンス上の懸念
- テストカバレッジの不足

droids/reviewer.md:

---
name: reviewer
description: 専門のコードレビュアーサブエージェント
model: inherit
tools: read-only
---

あなたはシニアコードレビュアーです。提供されたコードを分析して報告します:

Summary: <1行の評価>
Issues:
- <重大度> <説明>
Suggestions:
- <改善案>

次のステップ

プラグイン概要

プラグインのインストールと管理について学びます。

スキル

強力なスキルの作成を詳しく学びます。

カスタムコマンド

ユーザー起動のスラッシュコマンドを作成します。

カスタムDroid

プラグイン用の専門サブエージェントを作成します。

​クイックスタート

​プラグインマニフェスト

​必須フィールド

​オプションフィールド

​スキルの追加

​スキル形式

​スキルのフロントマター

​コマンドの追加

​コマンド形式

​コマンド引数

​エージェントの追加

​エージェント形式

​フックの追加

​フック設定

​環境変数

​MCPサーバーの追加

​プラグインのテスト

​ローカルテスト

​検証チェックリスト

​プラグインの配布

​マーケットプレースの作成

​マーケットプレースマニフェスト

​プラグインソース

​npm パッケージ

単一の npm プラグイン向けラッパーマーケットプレース

​バージョン管理

​Claude Code互換性

​ベストプラクティス

​例：完全なプラグイン

​次のステップ

プラグイン概要

スキル

カスタムコマンド

カスタムDroid

クイックスタート

プラグインマニフェスト

必須フィールド

オプションフィールド

スキルの追加

スキル形式

スキルのフロントマター

コマンドの追加

コマンド形式

コマンド引数

エージェントの追加

エージェント形式

フックの追加

フック設定

環境変数

MCPサーバーの追加

プラグインのテスト

ローカルテスト

検証チェックリスト

プラグインの配布

マーケットプレースの作成

マーケットプレースマニフェスト

プラグインソース

npm パッケージ

バージョン管理

Claude Code互換性

ベストプラクティス

例：完全なプラグイン

次のステップ