create-paperclip-bundled-skill

Paperclip バンドルスキルの作成

素材（ツイート、タスクの説明、ブログ記事、「X を実行するスキルを作って」など）をもとに、レビュー済みの PR として Paperclip スキルカタログ（packages/skills-catalog/）にスキルを追加します。カタログは、すべての Paperclip 企業が閲覧してインストールする棚です。そのため、正確なメタデータ、有用な手順、実例、問題のない検証実行が求められます。

基本ルールは 作成する前に探す ことです。すでに良いスキルが存在する場合（カタログ内、このリポジトリ内、または GitHub で公開済みの場合）は、ゼロから重複して作成するのではなく、参照または応用してください。

使用するタイミング

• 人がツイート、リンク、アイデアを送ってきて、それを Paperclip スキルにするよう依頼した場合。
• 既存のリポジトリスキルをカタログにバンドルするようタスクで依頼された場合。
• 外部で公開されているスキルをカタログに追加するようタスクで依頼された場合。

使用しないタイミング

• スキルが企業内限定の場合（配布カタログではなく、Skills UI/API を通じてその企業のライブラリに追加します）。
• Paperclip 自体の作業に必要な、リポジトリ内部向けのエージェントスキルだけが必要な場合。この場合はカタログ関連の仕組みを使わず、.agents/skills/ または skills/ に追加します。

ステップ 0 — 素材を収集する

何かを書く前に、スキルで教える内容を正確に把握します。

ツイート／X のリンク。 xc CLI（X API クライアント）を使用します。Paperclip のエンジニアリングエージェント環境には、インストール済みで認証も完了した状態で用意されています。自分でインストールしたり、認証情報を取得したりするツールではありません。利用する前に使用可能か確認します。

command -v xc && xc whoami    # on PATH and authenticated? if not, use the fallback below

xc get <post-url-or-id> --json        # the post itself (conversation_id, author)
xc search 'conversation_id:<id>' --archive --json   # rest of the thread (>7 days old needs --archive)
xc user <username>                    # author context
xc search '<topic keywords>' -n 30    # related discussion

xc が PATH にない、認証されていない、またはアカウントに読み取り権限がない場合（上記の確認で何らかの理由により失敗した場合）は、X/Twitter にアクセスできるチームメイト（例：Content Strategist エージェント）に子イシュー経由で取得を依頼します。URL を渡し、投稿とスレッドの全文、およびリンク先のコンテンツを尋ねてください。

その他の素材。 リンク先の記事や README を直接取得します。出典 URL を記録してください。スキル本文または PR の説明に出典として記載します。

要点をまとめます。繰り返し実行できる手順は何か。どのような入力を受け取るか。「完了」とはどのような状態か。素材が「エージェントはより良いコミットメッセージを書くべき」のような願望にすぎない場合は、手順を自分で作成します。その旨を PR に明記してください。

ステップ 1 — 検索：既存のスキルを探す

次の順序で検索し、明確な候補が見つかったら終了します。

1. すでにカタログにあるか？ 重複を避けてください（スラッグが重複するとビルドに失敗します）。

   grep -i '<topic>' packages/skills-catalog/generated/catalog.json
   ls packages/skills-catalog/catalog/{bundled,optional}/*/
   

2. すでにこのリポジトリにあるか？ .agents/skills/、skills/、およびイシューの履歴（gh search issues／Paperclip ボード）で、このトピックに関する以前の作業を確認します。
3. GitHub で公開されているか？ スキルは通常、SKILL.md を含むディレクトリです。

   gh search code --filename SKILL.md "<topic>" --limit 20
   gh search repos "<topic> skill" --limit 20
   

   既知のコレクション（例：anthropics/skills）も確認し、ウェブ検索で <topic> agent skill SKILL.md を検索します。

候補は次の点から判断します。SKILL.md に実際の手順が含まれているか（ひな形だけではないか）。メンテナンスされているか。何がバンドルされているか（スクリプトが含まれていると信頼性が高まります）。ライセンスは再配布に対応しているか。そのうえで、次の方針を選びます。

• 良い外部スキルがある → 外部参照として追加します（ステップ 2A）。上流リポジトリへの帰属表示を保ち、参照先を固定します。
• 一部だけ合致する → アイデアを応用したローカルスキルを作成します（ステップ 2B）。SKILL.md 本文にリンクを記載して出典を明示します。
• 使えるものがない → 新しいローカルスキルを作成します（ステップ 2B）。

ステップ 2 — 種類、カテゴリ、スラッグを選ぶ

• kind：デフォルトは optional にします。すべての Paperclip 企業にデフォルトで提供するスキルの場合に限り bundled を使用します。これには人間または取締役会からの明示的な指示が必要で、あなた自身の判断で決めてはいけません。
• category：該当する既存のディレクトリがあれば再利用します（browser、content、docs、finance、paperclip-operations、product、quality、research、software-development）。新しいカテゴリも使用できますが、小文字のケバブケースのスラッグにしてください。
• slug：小文字のケバブケース（^[a-z0-9]+(-[a-z0-9]+)*$）とし、カタログ全体（両方の種類）で一意にします。

スキルは packages/skills-catalog/catalog/<kind>/<category>/<slug>/ に配置し、正規キーは paperclipai/<kind>/<category>/<slug> です。

ステップ 2A — 外部参照パス（catalog-ref.json）

ディレクトリには catalog-ref.json のみを含めます（catalog-ref.json と SKILL.md の両方があるディレクトリはビルドに失敗します）。マニフェストビルダーはビルド時に GitHub から固定されたファイルを取得し、目録を作成します。

# Pin the exact commit for the chosen ref (tag or branch)
gh api repos/<owner>/<repo>/commits/<ref> --jq .sha

{
  "source": {
    "type": "github",
    "hostname": "github.com",
    "owner": "<owner>",
    "repo": "<repo>",
    "ref": "<tag-or-branch>",
    "commit": "<40-char sha from above>",
    "path": "<dir inside the repo containing SKILL.md, or ''>"
  },
  "files": ["SKILL.md", "references/**", "scripts/run.py"],
  "defaultInstall": false,
  "recommendedForRoles": ["researcher"],
  "requires": ["python3"],
  "tags": ["topic", "keywords"]
}

ビルダーが適用するルール：

• files のエントリは正確な相対パス、または dir/** の glob パターンにします。SKILL.md を含める必要があり、name と description を含むフロントマターが必要です。
• 上流のフロントマターで key／slug が宣言されている場合は、カタログ内の配置と一致させる必要があります。一致しない場合は、対応するスラッグを選ぶか、ローカルパスを使用します。
• commit は40桁の完全な16進数の SHA でなければなりません。列挙された各ファイルは 1 MiB 以下である必要があります。
• recommendedForRoles、requires、tags は JSON に記述します（これらを記載するローカルの SKILL.md はありません）。

実際の例については catalog/optional/research/last30days/catalog-ref.json を参照してください。また、このスキルの隣にある examples/external-reference.md も参照してください。

ステップ 2B — ローカルカタログスキルを作成する

レイアウト：

catalog/<kind>/<category>/<slug>/
├── SKILL.md          # required entrypoint
├── examples/         # 1–2 worked examples (Step 3)
├── references/       # optional deep-dive docs
├── scripts/          # optional — raises trust level, avoid unless needed
└── assets/           # optional templates/images

SKILL.md のフロントマター（すべてビルダーによって検証されます）：

---
name: <slug>
description: >
  40–300 chars. Routing logic, not marketing: what it does, when to use it,
  when not to.
key: paperclipai/<kind>/<category>/<slug>
recommendedForRoles:
  - engineer            # non-empty; used for staffing suggestions
tags:
  - topic               # non-empty; used for browse/search
---

任意のフロントマター：defaultInstall: true（すべての新しい企業に提供するスキルの場合のみ）、実行時依存関係には requires: [node, python3, ...] を指定します。

本文は docs/guides/agent-developer/writing-a-skill.md に従ってください。「When to use」／「When not to use」のセクションを設け、文章による説明より具体的なコマンドを優先し、補足情報は references/ に記載します。スキルがツイートや外部ソースに基づく場合は、出典を示すため本文にリンクを記載します。

信頼レベルは宣言ではなくファイルから導出されます。scripts/ ファイルがひとつでもあると、スキルは scripts_executables になります（インストールが監査ゲートの対象になり、src/shipped-catalog.test.ts の scriptBearing の期待値も拡張する必要があります）。assets/ または Markdown 以外のファイルがあると assets になります。Markdown のみのスキルは markdown_only のままです。Markdown のみの構成を推奨します。

ステップ 3 — 1～2 個の作業例を作成する

スキルディレクトリ内に examples/ を作成し、Markdown ファイルを 1～2 個用意します。それぞれに、入力 → 適用 → 出力を含む完全な手順例を記載します（現実的な入力、スキルの手順の適用、完成した成果物）。これらのファイルはスキルとともに配布されるため、インストーラーは実行前に内容を評価できます。また、.md ファイルなので信頼レベルは markdown_only のままです。

たとえば、examples/rewrite-release-note.md のようにシナリオに基づいた名前を付けます。

ステップ 4 — マニフェストを再生成し、テストを更新する

generated/catalog.json を手動で編集してはいけません。これは決定的に生成されるビルド出力です。

pnpm --filter @paperclipai/skills-catalog build:manifest   # regenerates generated/catalog.json
pnpm --filter @paperclipai/skills-catalog validate         # must report no errors

（外部参照の場合、これらの手順では GitHub へのネットワークアクセスが必要です。）

次に、packages/skills-catalog/src/shipped-catalog.test.ts を更新します。

• 新しいキーを EXPECTED_BUNDLED_KEYS または EXPECTED_OPTIONAL_KEYS に追加します（アルファベット順）。
• スキルにスクリプトが含まれる場合は、scriptBearing の期待値に追加します。

pnpm --filter @paperclipai/skills-catalog test

テストスイートは、リポジトリ全体におけるフロントマターの説明の上限（300 文字）に加え、すべてのカタログスキルに対する説明の最小文字数（40 文字）と、空でない roles および tags のルールも適用します。

ステップ 5 — PR を作成する

paperclipai/paperclip の master ブランチに対して、prepare-paperclip-pr スキル（.agents/skills/prepare-paperclip-pr/）に従ってください。差分には、次の項目だけを含めてください。

1. 新しいスキルディレクトリ（SKILL.md + examples/ + 補助ファイル、または catalog-ref.json）、
2. 再生成した generated/catalog.json、
3. shipped-catalog.test.ts の期待値の更新。

PR の本文では、参照元資料（ツイート URL、上流リポジトリ）にリンクし、これが新しいスキル／既存スキルの応用／外部参照のいずれなのかを明記し、信頼レベルを記載してください。最小限のオプションスキル PR の参考として、PR #10410（simplified-english）に言及してください。

注意点

• generated/catalog.json の古さは検証エラーになります。スキルディレクトリ内のファイルを変更したら、必ず build:manifest を再実行してください（インベントリにはファイルごとの sha256 ハッシュが含まれます）。
• バンドル済みとオプションの両方で slug が重複すると、重複キーだけでなくビルドも失敗します。
• スキルディレクトリ内のシンボリックリンクは、そのディレクトリ内を参照している必要があります。ディレクトリへのシンボリックリンクは拒否されるため、ファイルをコピーしてください。
• bundled の種別と defaultInstall は独立した要素です。オプションスキルに defaultInstall: true を安易に設定しないでください。
• 外部参照の場合、マニフェストのビルドのたびにビルダーが GitHub から取得します。上流の移動や削除によってビルドが失敗するため、commit が固定されています。ref には上流のタグを優先してください。