# PopClipの拡張機能を自作する方法（スニペットの作成から公開まで）

URL: https://webrandum.net/popclip-custom-extensions/
公開日: 2026-09-24
更新日: 2026-09-24
カテゴリー: 作業効率化
タグ: PopClip
出典: Webrandum（著者: サイトウ マサカズ）

PopClipの[公式ディレクトリ](https://www.popclip.app/extensions/)にはさまざまな拡張機能が登録されています。

[PopClip Extensions Directory](https://www.popclip.app/extensions/)

翻訳やノートアプリへの取り込みといったよくありそうな機能は、だいたいここで見つかります。

しかし、自分が使っているマイナーなサービスに投げたい、社内ツールのURLを選択したIDで開きたい、といった用途では、既存の拡張機能だけで対応できないことがあります。

そんなときは、拡張機能を自作する選択肢があります。
開発者登録もビルドも要らず、テキストエディタがあれば完結します。

今回はPopClipの拡張機能を自作する方法についてまとめます。

## 拡張機能の2つの形式

PopClipの拡張機能には、大きく分けて「Snippets（スニペット）」と「Packages（パッケージ）」の2つの形式があります。

[Snippets — PopClip Developer](https://www.popclip.app/dev/snippets)

違いをまとめると下記の通りです。

| 項目 | Snippets | Packages |
| --- | --- | --- |
| 形式 | テキスト | .popclipextで終わる名前のフォルダ |
| 設定の書き方 | YAMLやJavaScriptなど | Config.yamlなどの設定ファイル |
| 追加ファイル | 持てない | アイコン画像・スクリプト・READMEを同梱できる |
| インストール | テキストを選択して実行 | ダブルクリック |
| 署名 | できない | できる |

Snippetsの方が気軽に追加できますが、追加ファイルの同梱や署名はできません。
配布したり自分以外も使う場合はPackagesがいいですが、自分専用や個人でのお試しレベルであればSnippetsで十分です。

まずはSnippetsで作って、配布したくなったらPackagesにする流れが良さそうです。

## Snippetsで自作する

SnippetsはYAML形式のテキストを書くだけで作れます（JavaScriptで書く方法もありますが、その方法は後述します）。

最小のサンプルは下記の通りです。

```
#popclip
name: Urban Dictionary
icon: UD
url: https://www.urbandictionary.com/define.php?term=***
```

1行目の`#popclip`が目印で、この形式のテキストを丸ごと選択すると、PopClipが自動的に検知して「Install Extension」のアクションを表示してくれます。
`***`には、選択したテキストの前後の空白を取り除き、URLエンコードした値が入ります。

検索先のURLを差し替えれば、好きなサイトの検索用アクションが作れます。

そしてテキストを選択するだけで、PopClip上にインストールボタンが表示されます。

![](https://webrandum.net/mskz/wp-content/uploads/2026/09/image_1-4-1024x460.png)

わざわざファイルを作らなくてもテキストを選択するだけで拡張機能をインストールできるという方法は、PopClipらしい仕組みで面白いです。

なお、テキスト選択からインストールできるのは5,000文字までです。
それ以上に長い場合やファイルとして保存したい場合は、`.popcliptxt`拡張子で保存することで、ファイルをダブルクリックでインストールできるようになります。

`.yaml`・`.js`・`.ts`で保存した場合は、Finderの［このアプリケーションで開く］→［PopClip］を選ぶか、PopClipのメニューバーアイコンへドラッグします。

なお、YAMLのインデントにはタブではなく半角スペースを使う必要があるので注意が必要です。

### アイコンを指定する

`icon`で指定できる代表的な形式は、下記の通りです（[アイコンの公式仕様](https://www.popclip.app/dev/icons)）。

| 書き方 | 例 | 内容 |
| --- | --- | --- |
| テキスト | icon: square filled AB | 最大3文字を使ったアイコンを生成する |
| SF Symbols | icon: symbol:globe | macOS標準のSF Symbolsから指定する |
| Iconify | icon: iconify:simple-icons:notion | Iconifyのアイコンライブラリから指定する |

テキストアイコンは`square`（四角）や`circle`（丸）といった図形の指定に、`filled`（塗りつぶし）を組み合わせて書きます。
`icon: UD`のように文字だけを書くこともできます。

バーに同じような四角が並ぶと押し間違えるので、サービスのロゴがIconifyにあるならそれを指定しておくのが分かりやすいです。

### アクションの種類

指定できるアクションには、下記の6種類があります。

| 種類 | 設定キー | 内容 |
| --- | --- | --- |
| URL | url | URLを開く |
| キー入力 | keyCombo | ショートカットキーを送る |
| サービス | serviceName | macOSのサービスを呼び出す |
| ショートカット | shortcutName | ショートカット.appのショートカットを実行する |
| AppleScript | appleScript | AppleScriptを実行する |
| シェルスクリプト | shellScript | シェルスクリプトを実行する |

文字列の加工や条件分岐が必要になったら、JavaScriptやシェルスクリプトを使います。

### キー入力を送る

アプリのショートカットキーを押すだけのアクションは`keyCombo`で書けます。

```
#popclip
name: Bold
icon: B
keyCombo: command b
keyComboTarget: app
stayVisible: true
```

`command b`のように、修飾キーと通常のキーを半角スペースで区切って書きます。
修飾キーは`command`・`option`・`control`・`shift`が使え、`cmd`や`opt`のような省略形も通ります。

また、`stayVisible: true`を付けると、クリックしてもPopClipバーが消えません。
太字と斜体を続けて当てたいときなど、連続で押したいアクションに向いています。

### シェルスクリプトを実行する

シェルスクリプトを実行する場合、選択したテキストは環境変数`POPCLIP_TEXT`から受け取ります。

```
#popclip
name: Character Count
icon: symbol:textformat.123
after: show-result
interpreter: /bin/zsh
shellScript: printf '%s' "$POPCLIP_TEXT" | wc -m | tr -d ' '
```

`POPCLIP_TEXT`以外にも、ブラウザで開いているURLが入る`POPCLIP_BROWSER_URL`などが用意されています。

### JavaScriptで書く

JavaScriptの場合は`#popclip`をコメントとして書き、その下に処理を続けます。
拡張子は`.js`です。

```
// #popclip
// language: javascript
// name: Uppercase
// icon: square filled AB
popclip.pasteText(popclip.input.text.toUpperCase());
```

選択したテキストは`popclip.input.text`で取得でき、`popclip.pasteText()`で置換できます。

上記のサンプルは選択テキストを大文字に変換していますが、このレベルの処理なら簡単に作成できます。
ちなみに、あとで説明する公式ディレクトリへの公開ではJavaScriptが推奨されています。

### 複数のアクションを設定する

1つの拡張機能に複数のアクションを持たせる場合は`actions`に並べます。

```
#popclip
name: 検索
actions:
  - title: Google
    icon: iconify:simple-icons:google
    url: https://www.google.com/search?q=***
  - title: MDN
    icon: iconify:simple-icons:mdnwebdocs
    url: https://developer.mozilla.org/ja/search?q=***
```

`title`はアイコンが無いときにボタンへ表示され、アイコンがある場合はツールチップに表示されます。

よく使う検索先を、1つの拡張機能としてまとめて管理なんてことができます。

### 表示条件を絞る

拡張機能を増やしていくと、バーが横に長くなって目的のアクションを探すのに時間がかかるようになってしまいます。

そこで便利な設定が「`requirements`」です。
選択した内容が条件に合うときだけアクションを表示する指定で、主な値は下記の通りです。

| 値 | 条件 |
| --- | --- |
| text | 文字が選択されている |
| url | 選択範囲にURLが1つだけ含まれている |
| isurl | 選択範囲がURLそのもの |
| email | メールアドレスが1つだけ含まれている |
| path | 存在するローカルのファイルパスである |
| paste | ペーストできる状態である |
| formatting | 書式変更に対応する状況である |

値の先頭に`!`を付けると条件を反転することもできます。

さらに、細かく絞りたい場合は`regex`で正規表現の指定も可能です。
「`requirements`」で絞ったあとに正規表現がかけられて、マッチした部分だけがアクションに渡ります。

例えば、選択した文字列がチケット番号のときだけ管理ツールを開く、といった書き方ができます。

```
#popclip
name: Issue
icon: symbol:number
regex: "^[A-Z]+-[0-9]+$"
url: https://example.com/browse/***
```

上記のサンプルでは選択テキストが`ABC-123`のような形式に一致したときだけ表示されます。

他にも、特定のアプリでだけ表示したい場合は`requiredApps`にバンドルIDを指定します。

### 実行後の動作を決める

`after`を指定すると、アクションの実行結果をどう扱うかを決められます。

| 値 | 動作 |
| --- | --- |
| paste-result | 結果を選択範囲にペーストする |
| copy-result | 結果をクリップボードにコピーする |
| show-result | 結果をその場に表示する |
| preview-result | 結果をプレビュー表示する |
| show-status | 成功・失敗のマークだけ表示する |
| copy | 選択範囲をコピーする |

対になる`before`もあって、アクションの実行前に`copy`や`cut`を挟めます。

シェルスクリプトの標準出力を選択範囲に戻す場合は、`after: paste-result`を指定します。
URLを開くだけのアクションなど、テキストの結果を返さない処理には使えません。

## Packagesにする

アイコン画像や別ファイルを同梱したい場合、または公式ディレクトリへ公開したい場合は、[Packages（パッケージ形式）](https://www.popclip.app/dev/packages)にします。

Packagesと言っても、`.popclipext`で終わる名前のフォルダを作ってその中に設定ファイルを置くだけです。

```
MyExtension.popclipext/
├── Config.yaml
├── icon.png
└── readme.md
```

今回の例では設定ファイルに`Config.yaml`を使っていますが、他にJSONやplist、JavaScriptなどでも記述できます。

中身に書く内容はSnippetsと同じですが、公開する場合は`name`・`identifier`・`description`・`popclip version`の4つが必須になります。

```
name: My Extension
identifier: com.example.myextension
popclip version: 6221
description: 選択したテキストを社内ツールで開きます。
icon: icon.png
url: https://example.com/search?q=***
```

`identifier`は拡張機能を識別する値なので、一意の名前を決めて、更新時も同じ値を使います。
`popclip version`は必要なPopClipの最低バージョンのビルド番号で、上記サンプルでは2026.8.1（6221）以降を対象にしています。

`icon.png`も実際の画像を用意します。
画像を使わない場合は`icon: square filled AB`のようなテキストアイコンに変更し、画像ファイルを省けます。

パッケージ化したら、フォルダをダブルクリックするとインストールされます。
なお、配布用にはフォルダをzipで圧縮して、拡張子を`.popclipextz`に変えたものを渡します。

## 自作した拡張機能を公開する方法

自分で使うだけなら前述のファイルだけで事足りますが、[公式のディレクトリ](https://www.popclip.app/extensions/)に載せることもできます。

[PopClip Extensions Directory](https://www.popclip.app/extensions/)

ディレクトリに掲載された拡張機能はサーバー側で署名されるので、インストール時に警告が出なくなりますし、更新も自動で配信されます。

### 提出の準備

[公式の提出手順](https://www.popclip.app/extensions/submit)に沿って、公開したGitHubリポジトリを登録します。
2026年8月に新しい方式へ切り替わったようで、以前より手順が整理されました。

[Submit an Extension — PopClip Extensions](https://www.popclip.app/extensions/submit)

流れは下記の通りです。

1. 拡張機能を`.popclipext`パッケージとしてGitHubの公開リポジトリに置く
2. リポジトリのルートに`popclip-directory.yaml`を作る
3. PopClip Directoryのアプリを対象のリポジトリにインストールする
4. バージョンのタグを付けてプッシュする

`popclip-directory.yaml`には、どのフォルダを拡張機能として扱うかを書きます。

```
include: "source/*.popclipext"
versionPrefix: v
```

この設定例では、パッケージをリポジトリ内の`source/`フォルダに置きます。
ソースと設定ファイルをコミットしてGitHubへプッシュしたら、提出するコミットにバージョンのタグを付けて送ります。

```
git tag v1.0.0
git push origin v1.0.0
```

タグをプッシュすると自動チェックが始まり、結果をGitHubで確認できます。

サイズ制限は1つの拡張機能につきファイル数は100個まで、1ファイル1MiBまで、全体で2MiBまでです。

そして`readme.md`を置くと、拡張機能のページに表示されます。
デモ動画（`demo.mp4`）を置くこともできて、こちらは目立つ位置に表示されます。

自動チェックを通ると手動レビューへ進みます。
それも承認されると、専用のページと署名済みの`.popclipextz`のダウンロードが用意されて公開されます。

### シェルスクリプトは理由が必要

ひとつ注意したいのが、ディレクトリではJavaScriptで書くことが強く推奨されている点です。

シェルスクリプトを使う拡張機能を提出する場合は、`shellScriptRationale`に「なぜJavaScriptでは実現できないのか」を書く必要があります。
理由は20文字以上が必要で、項目が無い場合は自動チェックを通りません。

公開を考えている場合は、JavaScriptで実現できる処理かを先に確認しておくと作り直しを減らせます。

## まとめ

PopClipの拡張機能の自作は、想像していたよりずっと手前から始められました。
特に公開予定もなく、とりあえず自分で使う用のものであれば、YAMLを4行書いてそれを選択するだけで追加できます。

何よりテキストを選択するだけでインストール表示が出てくるのは、PopClipらしくて非常に面白いです。

まずは自分で試してみて、便利そうであれば公式ディレクトリへの申請も考えてみてはいかがでしょうか。