npm パッケージに Agent Skills を同梱する TanStack intent

コーディングエージェントがコードを生成する際に、学習データの量と質の多さが生成するコードの品質に大きく影響を与えると言われています。例えば TypeScript や Python は GitHub 上のオープンソースコードの多くを占めているため、LLM の訓練データに含まれる割合が高くなり、結果として言語のイディオムやプラクティスを深く理解しているため、生成されるコードの品質も高くなる傾向があります。

npm や PyPI などのパッケージマネージャーに公開されているコードについても同じことが言えます。例えば React のような人気のあるライブラリは、LLM の訓練データに大量に含まれているため、特別な指示を与えなくとも React のプラクティスに従ったコードを生成する可能性が高くなります。その一方、LLM のカットオフ以降に公開された新興のライブラリではコーディングエージェントが誤った使い方をしてしまうリスクが高くなります。

この問題の対策として有効なのは、コンテキストにコードの使用方法を明示的に提供することです。AGENTS.md（CLAUDE.md）や Agent Skills のようなコーディングエージェントにコンテキストを渡す標準的な方法を使用してライブラリのドキュメントを提供するという方法がよく知られています。またライブラリの提供者側もライブラリのドキュメントをエージェントに渡す方法を模索しており、例えば Next.js では Next.js のスキルを GitHub 上で公開していたり、node_modules にドキュメントを同梱し、コードを書く前にエージェントがドキュメントを参照できるようにする方法を提供しています。React Remotion や Motia といった新しめのライブラリでは、プロジェクトを作成するとあらかじめ Agent Skills が同梱されているというケースも出てきています。

ライブラリの提供者が Agent Skills を公開・同梱する手法は最近注目されていますが、スキルの更新や管理の方法に課題があります。GitHub 上で公開されたスキルは手動でコピペしたり Vercel の Skills CLI を使用して手元のプロジェクトに反映させますが、スキルの更新を追跡する方法が確立されていません。またスキルを手動で更新する必要があるとなれば次第に更新が滞ってしまう可能性もあります。互換性のないライブラリのバージョン更新があった後にスキルのドキュメントが陳腐化していれば、気が付かないうちにエージェントが少しずつ誤ったコードを生成してしまうリスクもあります。エージェントが生成したコードの評価が難しいこともあり、エージェントが書くコードの品質が低下したとしてもスキルの更新忘れであるということに気が付かない可能性もあります。

@tanstack/intent はライブラリのメンテナが Agent Skills を生成・検証して npm パッケージに同梱することを支援するツールです。スキルの更新が滞るという問題に対して npm パッケージに同梱するという方法を採用することにより、npm update でライブラリのバージョンが更新されればスキルも同時に更新されるという形でスキルの更新を促すことができます。

この記事では @tanstack/intent を使用してライブラリの使用者側と、メンテナ側の両方の観点から Agent Skills を利用する方法を紹介します。

Warning

Agent Skills はプロンプトにユーザーの機密事項を窃取するプロンプトを含める「プロンプトインジェクション」のリスクや、任意のスクリプトを実行できる仕組みが悪用されるリスクなど、セキュリティ上のリスクを伴う可能性があります。Agent Skills を第三者からインストールする際には、スキルの内容を十分に確認することを推奨します。

ライブラリの使用者側のワークフロー

@tanstack/intent を使用して Agent Skills が提供されているライブラリでは、node_modules にスキルが同梱されています。ライブラリの使用者はインストール済みの依存関係からスキルを検出し、エージェントの設定とスキルのマッピングを行います。その後ライブラリのバージョン更新に合わせてスキルが同期されるようになります。

Agent Skills が同梱されている npm パッケージは Agent Skills Registry で確認できます。

ここでは @tanstack/db というデータベースクライアントライブラリを例に、Agent Skills を利用する方法を紹介します。React のプロジェクトに @tanstack/db をインストールしておきましょう。

npm install @tanstack/db

node_modules/@tanstack/db/ を確認してみると、確かに skills/ ディレクトリが存在し、Agent Skills が同梱されていることがわかりますね。

node_modules/@tanstack/db
├── dist
│   ├── ...
├── package.json
├── README.md
├── skills
│   ├── db-core
│   │   ├── collection-setup
│   │   │   ├── references
│   │   │   │   ├── electric-adapter.md
│   │   │   │   ├── local-adapters.md
│   │   │   │   ├── powersync-adapter.md
│   │   │   │   ├── query-adapter.md
│   │   │   │   ├── rxdb-adapter.md
│   │   │   │   ├── schema-patterns.md
│   │   │   │   └── trailbase-adapter.md
│   │   │   └── SKILL.md
│   │   ├── custom-adapter
│   │   │   └── SKILL.md
│   │   ├── live-queries
│   │   │   ├── references
│   │   │   │   └── operators.md
│   │   │   └── SKILL.md
│   │   ├── mutations-optimistic
│   │   │   ├── references
│   │   │   │   └── transaction-api.md
│   │   │   └── SKILL.md
│   │   └── SKILL.md
│   └── meta-framework
│       └── SKILL.md
└── src
    ├── ...

実際に人間の目で node_modules ディレクトリを確認してスキルを見つけるのは大変なので、@tanstack/intent には同梱されているスキルを検出するための CLI ツールが提供されています。以下のコマンドを実行してみましょう。

npx @tanstack/intent@latest list

Tip

執筆時点（2026 年 3 月）では @tanstack/[email protected] に出力が表示されないバグがあるため、ここでは @0.0.14 を使用して検証しています。

このコマンドを実行すると、インストールされている依存関係の中から Agent Skills を検出し、スキルの名前や説明、スキルが提供されているライブラリのバージョンなどの情報が表示されます。

1 intent-enabled packages, 6 skills (npm)
 
PACKAGE       VERSION  SKILLS  REQUIRES
─────────────────────────────────────────
@tanstack/db  0.5.33   6       –
 
Skills:
 
  @tanstack/db
    db-core                 [core]        TanStack DB core concepts: ...

node_modules に同梱されているスキルを検出したら、エージェントの設定とスキルのマッピングを行います。以下のコマンドを実行すると、AI エージェントにスキルをセットアップするためのプロンプトが標準出力に表示されます。このプロンプトをパイプで Claude Code などのコーディングエージェントに渡して使用します（後述）。

npx @tanstack/intent@latest install

出力されるプロンプトは以下のタスクをエージェントに指示する内容になっています。

既存マッピングの確認: プロジェクトのエージェント設定ファイル（CLAUDE.md、AGENTS.md、.cursorrules、.github/copilot-instructions.md）にスキルマッピングのブロックが存在するか確認する。存在する場合は現在のマッピングをユーザーに表示し、更新内容を尋ねる
利用可能なスキルの発見: intent list コマンドを実行して、利用可能なスキルの名前、説明、パスを出力する
リポジトリのスキャン: プロジェクトの構造やパターンを把握するために、package.json を読み、ディレクトリレイアウトを調査し、繰り返されるパターンをメモする。これに基づいて、3〜5 のスキルとタスクのマッピングを提案し、ユーザーに他に一般的に AI コーディングエージェントを使用するタスクがあるか尋ねる
マッピングブロックの書き込み: 完全なマッピングセットが揃ったら、エージェント設定ファイル（CLAUDE.md を優先して、存在しない場合は新規作成）にスキルマッピングのブロックを正確に書き込む。

出力されるプロンプト

You are an AI assistant helping a developer set up skill-to-task mappings for their project.
 
Follow these steps in order:
 
1. CHECK FOR EXISTING MAPPINGS
   Search the project's agent config files (CLAUDE.md, AGENTS.md, .cursorrules,
   .github/copilot-instructions.md) for a block delimited by:
     <!-- intent-skills:start -->
     <!-- intent-skills:end -->
   - If found: show the user the current mappings and ask "What would you like to update?"
     Then skip to step 4 with their requested changes.
   - If not found: continue to step 2.
 
2. DISCOVER AVAILABLE SKILLS
   Run: intent list
   This outputs each skill's name, description, and full path — grouped by package.
 
3. SCAN THE REPOSITORY
   Build a picture of the project's structure and patterns:
   - Read package.json for library dependencies
   - Survey the directory layout (src/, app/, routes/, components/, api/, etc.)
   - Note recurring patterns (routing, data fetching, auth, UI components, etc.)
 
   Based on this, propose 3–5 skill-to-task mappings. For each one explain:
   - The task or code area (in plain language the user would recognise)
   - Which skill applies and why
 
   Then ask: "What other tasks do you commonly use AI coding agents for?
   I'll create mappings for those too."
 
4. WRITE THE MAPPINGS BLOCK
   Once you have the full set of mappings, write or update the agent config file
   (prefer CLAUDE.md; create it if none exists) with this exact block:
 
<!-- intent-skills:start -->
# Skill mappings — when working in these areas, load the linked skill file into context.
skills:
  - task: "describe the task or code area here"
    load: "node_modules/package-name/skills/skill-name/SKILL.md"
<!-- intent-skills:end -->
 
   Rules:
   - Use the user's own words for task descriptions
   - Include the exact path from `intent list` output so agents can load it directly
   - Keep entries concise — this block is read on every agent task
   - Preserve all content outside the block tags unchanged

実際にインストールコマンドを実行する場合には、パイプラインで Claude Code や Codex にプロンプトを渡すとよいでしょう。

npx @tanstack/intent@latest install | claude

Claude code にプロンプトを渡すと、プロジェクトの内容に従ってスキルとタスクのマッピングを提案してくれます。「localStorage を使用してデータを永続化する TODO アプリをこれから作成する」という追加情報を与えたうえで、実際に CLAUDE.md にスキルのマッピングを追加してもらいましょう。

実際に CLAUDE.md にスキルのマッピングが追加されていることがわかりますね。

<!-- intent-skills:start -->
 
# Skill mappings — when working in these areas, load the linked skill file into context.
 
skills:
 
- task: "localStorage を使った TODO コレクションのセットアップ（localStorageCollectionOptions、スキーマ定義、getKey）"
  load: "node_modules/@tanstack/db/skills/db-core/collection-setup/SKILL.md"
 
- task: "TODO の一覧表示・フィルタリング・検索など、ライブクエリの実装"
  load: "node_modules/@tanstack/db/skills/db-core/live-queries/SKILL.md"
 
- task: "TODO の追加・編集・削除（楽観的ミューテーション、insert/update/delete）"
  load: "node_modules/@tanstack/db/skills/db-core/mutations-optimistic/SKILL.md"
 
- task: "TanStack DB の全般的な概念・使い方がわからないとき"
load: "node_modules/@tanstack/db/skills/db-core/SKILL.md"
<!-- intent-skills:end -->

これでエージェントがコードを生成する際に、@tanstack/db のスキルを参照するか試してみましょう。以下のようなプロンプトを与えて TODO アプリのコードを生成してみましょう。

ユーザーが TODO を追加・編集・削除できる React アプリを作成してください。
 
- TODO データは @tanstack/db を使用して localStorage に永続化してください
- TODO データのフィルタリング機能も実装してください

確かに node_modules/@tanstack/db/skills からスキルを参照していることがわかりますね。

CLAUDE.md のスキルのマッピングでは node_modules のスキルを参照するように指示されているため、npm パッケージのバージョンを更新すればユーザーが特に作業しなくともスキルも更新されるようになります。スキルが古いソースコードを参照していないかどうか以下のコマンドで確認できます。

npx @tanstack/intent@latest stale

ライブラリのメンテナ側のワークフロー

続いてライブラリのメンテナが npm パッケージに @tanstack/intent を使用して Agent Skills を同梱する方法を見てみましょう。isOdd と isEven という関数を提供する小さなライブラリを作成してワークフローを見てみましょう。

/**
 * Returns true if n is an odd integer, false otherwise.
 * Returns false for NaN, Infinity, -Infinity, and non-integer values.
 */
export function isOdd(n: number): boolean {
  if (!Number.isFinite(n)) return false;
  if (!Number.isInteger(n)) return false;
  return Math.abs(n % 2) === 1;
}
 
/**
 * Returns true if n is an even integer, false otherwise.
 * Returns false for NaN, Infinity, -Infinity, and non-integer values.
 */
export function isEven(n: number): boolean {
  if (!Number.isFinite(n)) return false;
  if (!Number.isInteger(n)) return false;
  return n % 2 === 0;
}

Agent Skills の生成

scaffold コマンドを実行すると、エージェントがスキルを生成するためのプロンプトが出力されます。

npx @tanstack/intent@latest scaffold

出力されるプロンプトは以下のタスクをエージェントに指示する内容になっています。

事前準備: package.json からライブラリ名・リポジトリ URL・ドキュメント URL を読み取る
ライブラリの内容の理解: プロンプト全体のソースコードを読んだり、メンテナにインタビュー（ライブラリの目的, 一般的な使用方法, よくある誤った使用方法, 暗黙知）を行い、ライブラリの全体のドメインマップを作成する。成果物は domain_map.yaml と skill_spec.md で必ずメンテナのレビューを求めること
スキルツリーの生成: スキルツリーは、ライブラリに対して生成する SKILL.md ファイルの完全な一覧と構造を定義したマニフェストで、コーディングエージェントがどのスキルがどのタスクに対応しているかを理解するために使用される。成果物は skill_tree.yaml で必ずメンテナのレビューを求めること
スキルの生成: スキルを生成する。成果物は個々の SKILL.md ファイル。
- 単一リポジトリの場合: skills/<domain>/<skill>/SKILL.md
- モノレポの場合: packages/<pkg>/skills/<domain>/<skill>/SKILL.md
生成されたスキルの検証: npx @tanstack/intent validate を実行して、生成されたスキルが正しい形式であることを確認する
スキルの同梱: 生成されたスキルを npm パッケージに同梱するために、package.json に files フィールドを追加して skills/ ディレクトリを含めるようにする

出力されるプロンプト

You are helping a library maintainer scaffold Intent skills.
 
Run the three meta skills below **one at a time, in order**. For each step:
1. Load the SKILL.md file specified
2. Follow its instructions completely
3. Present outputs to the maintainer for review
4. Do NOT proceed to the next step until the maintainer confirms
 
## Before you start
 
Gather this context yourself (do not ask the maintainer — agents should never
ask for information they can discover):
1. Read package.json for library name, repository URL, and homepage/docs URL
2. Detect if this is a monorepo (look for workspaces field, packages/ directory, lerna.json)
3. Use skills/ as the default skills root
4. For monorepos:
   - Domain map artifacts go at the REPO ROOT: _artifacts/
   - Skills go INSIDE EACH PACKAGE: packages/<pkg>/skills/
   - Identify which packages are client-facing (usually client SDKs and primary framework adapters)
 
---
 
## Step 1 — Domain Discovery
 
Load and follow: /Users/xxx/.npm/_npx/49ccc4810cfff6df/node_modules/@tanstack/intent/meta/domain-discovery/SKILL.md
 
This produces: domain_map.yaml and skill_spec.md in the artifacts directory.
Domain discovery covers the WHOLE library (one domain map even for monorepos).
 
**STOP. Review outputs with the maintainer before continuing.**
 
---
 
## Step 2 — Tree Generator
 
Load and follow: /Users/xxx/.npm/_npx/49ccc4810cfff6df/node_modules/@tanstack/intent/meta/tree-generator/SKILL.md
 
This produces: skill_tree.yaml in the artifacts directory.
For monorepos, each skill entry should include a `package` field.
 
**STOP. Review outputs with the maintainer before continuing.**
 
---
 
## Step 3 — Generate Skills
 
Load and follow: /Users/xxx/.npm/_npx/49ccc4810cfff6df/node_modules/@tanstack/intent/meta/generate-skill/SKILL.md
 
This produces: individual SKILL.md files.
- Single-repo: skills/<domain>/<skill>/SKILL.md
- Monorepo: packages/<pkg>/skills/<domain>/<skill>/SKILL.md
 
---
 
## After all skills are generated
 
1. Run `npx @tanstack/intent validate` in each package directory
2. Commit skills/ and artifacts
3. For each publishable package, run: `npx @tanstack/intent add-library-bin`
4. For each publishable package, run: `npx @tanstack/intent edit-package-json`
5. Ensure each package has `@tanstack/intent` as a devDependency
6. Create a `skill:<skill-name>` label on the GitHub repo for each skill (use `gh label create`)
7. Add a README note: "If you use an AI agent, run `npx @tanstack/intent@latest install`"

パイプラインで Claude Code や Codex にプロンプトを渡してスキルを生成してもらいましょう。

npx @tanstack/intent@latest scaffold | claude

はじめにライブラリの内容を理解するためのスキャンが行われました。小規模なライブラリであることをよく理解していますね。またステップが終わるたびに成果物を確認するように促してくれています。

次のステップではスキルを作成するためにインタビューが行われ、ライブラリがどのような目的で使用されることが多いか、どのようなタスクが発生しやすいかなどを質問されます。

最終的には isOdd/isEven の基本的な使用方法を説明する parity-check スキルと、Zod と組み合わせて使用する parity-with-zod スキルの 2 つのスキルが提案されました。

続けてスキルツリーである skill_tree.yaml と、個々のスキルである parity-check/SKILL.md と parity-with-zod/SKILL.md が生成されていきます。最終的な成果物は以下のようになりました。

skills
├── _artifacts
│   ├── domain_map.yaml
│   ├── skill_spec.md
│   └── skill_tree.yaml
├── parity-check
│   └── SKILL.md
└── parity-with-zod
    └── SKILL.md

スキルの作成が完了したら、npx @tanstack/intent validate を実行してスキルが正しい形式であることを確認します。ここではパッケージのパスと name フィールドが一致してないというエラーが報告され、修正されている様子が確認できます。

スキルの検証が完了したら、npx @tanstack/intent add-library-bin と npx @tanstack/intent edit-package-json を実行して、スキルを npm パッケージに同梱するための準備をします。

add-library-bin は、ライブラリのリポジトリに bin/intent.mjs というシムファイルを生成するコマンドです。これによりライブラリをインストールしたユーザーが npx intent を実行すると、@tanstack/intent CLI が起動するようになります。edit-package-json は、package.json に files フィールドを追加して skills/ ディレクトリを含めるようにするコマンドです。

package.json

{
  "files": [
    "dist",
    "skills",
    "bin",
    "!skills/_artifacts"
  ],
  "bin": {
    "intent": "./bin/intent.mjs"
  },
  "devDependencies": {
    "@tanstack/intent": "^0.0.14",
    // ...
  }
}

続いて gh CLI を使用して GitHub 上に skill:parity-check と skill:parity-with-zod というラベルを作成し、スキルの内容を確認できるようにします。最後に README に「AI エージェントを使用する場合は npx @tanstack/intent@latest install を実行してください」という注意書きを追加して、ワークフローの完了です。

Agent Skills Registry へ登録されるようにするためには、package.json の keywords フィールドに tanstack-intent を追加して npm パッケージを公開する必要があります。

package.json

{
  "keywords": [
    "tanstack-intent",
    // ...
  ]
}

Agent Skills の更新

スキルは一度作成したら終わりではなく、ライブラリの更新に合わせてスキルも更新していく必要があります。以下のコマンドを実行すると、CI パイプラインでスキルの検証と更新の確認をする GitHub Action のテンプレートが生成されます。

npx @tanstack/intent@latest setup-github-actions

生成されるワークフローは以下の 3 つです。

validate-skills: 生成されたスキルが正しい形式であることを確認するジョブ。/skills ディレクトリに変更があったプルリクエストに対して実行される
notify-intent: ドキュメントやソースコードが変更された場合、tanstack/intent レポジトリに Webhook を送信する。これにより intent 側でライブラリのスキルが最新のソースコードと整合しているかチェックが行われ、スキルの更新が必要と判断された場合に次の check-skills ワークフローがトリガーされる
check-skills: 新しいバージョンのライブラリが公開されたときに、古いスキルを自動で検出する。このワークフローによりプルリクエストが自動で作成され、PR の説明にはスキルの更新に必要な変更内容を含むプロンプトが記載される。メンテナはこのプロンプトをコーディングエージェントに渡すことで、スキルの更新作業を効率的に行うことができる

まとめ

LLM のカットオフ以降に公開されたライブラリでは、エージェントが誤ったコードを生成するリスクがある。Agent Skills をライブラリに同梱することで品質を改善できるが、スキルの更新・管理が課題となる
@tanstack/intent は Agent Skills を npm パッケージに同梱することで、npm update によるライブラリ更新と同時にスキルも更新される仕組みを実現するツールである
ライブラリの使用者側は、@tanstack/intent install コマンドを使用して、エージェントの設定とスキルをマッピングするためのプロンプトを表示できる。スキルが同梱されている npm パッケージは Agent Skills Registry で確認できる
ライブラリのメンテナ側は、@tanstack/intent scaffold コマンドを使用して、エージェントにスキルを生成するためのプロンプトを表示できる。