@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ja-JP/sharing.md

@@ -0,0 +1,219 @@
+---
+title: "共有とプライバシー"
+description: "フレームワークに組み込まれた Google ドキュメント スタイルの共有。ユーザーが作成したすべてのリソース (ドキュメント、ダッシュボード、デザイン、デッキ、クリップ、レコーディング、フォーム) は、1 つの一貫した共有 UI を持つ同じデフォルトのプライベート モデルを取得します。"
+---
+
+# 共有とプライバシー
+
+ユーザーがエージェント ネイティブ アプリで作成するすべてのリソース (ドキュメント、ダッシュボード、デザイン、デッキ、ビデオ編集、画面録画、会議記録、フォーム、予約リンク) は、**デフォルトでは作成者のみに公開されます**。他の人がそれを見ることができるのは、作成者が明示的に共有するか、公開範囲を `org` または `public` に変更した場合のみです。
+
+見た目も動作も Google ドキュメントと同じです。同じ共有ボタン、同じダイアログ、同じ 3 層可視性モデル、ユーザーごと/組織ごとの同じ許可が、すべてのテンプレートにわたって使用され、アプリごとの再発明は必要ありません。
+
+## なぜ 1 つのモデルなのか {#why}
+
+ほとんどのアプリ フレームワークでは、機能ごとにプロジェクトを共有します。その結果、すべてのドキュメントのようなサーフェスには、独自の共有ダイアログ、独自の権限スキーマ、独自のアクセス チェック バグが存在することになります。エージェントネイティブでは、共有は **フレームワークのプリミティブ**です。スキーマ列、アクセス チェック ヘルパー、共有ポップオーバー、エージェント呼び出し可能な共有 actions はすべてコアに同梱されています。新しいテンプレートでは、2 つの列と 1 行の登録を追加することで、完全な共有ストーリーを取得します。
+
+これは、エージェントがアプリごとに新しい共有モデルを学習する必要がないことも意味します。任意のテンプレートでエージェントに「これを編集者としてアリスと共有する」と伝えると、同じ `share-resource` アクションが実行されます。
+
+## 3 つの可視性レベル {#visibility}
+
+大まかな可視性はリソース自体に依存します。きめ細かい付与はコンパニオン株式テーブルに存在します。
+
+| 可視性    | 誰がそれを見ることができます                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------ |
+| `private` | 明示的に付与された所有者 + ユーザー。 **すべての新しいリソースのデフォルト。**                               |
+| `org`     | 所有者 + 明示的な許可 + 同じ組織内のすべてのユーザー (読み取り専用)。                                        |
+| `public`  | 所有者 + 明示的な許可 + リンクを持つすべてのユーザー (読み取り専用)。他の人のリスト/検索には表示されません。 |
+
+`public` は意図的に静かなレベルです。公開リソースは直接リンクからアクセスできますが、他のユーザーのサイドバー、リスト、検索には**表示されません**。これにより、「URL を共有するためのパブリック」と「クロスユーザー検出のためのパブリック」が分離されます。クロスユーザー検出を本当に必要とするギャラリーとテンプレート カタログは、明示的にオプトインします。
+
+```an-diagram title="Visibility, widening outward" summary="Coarse visibility on the resource sets the floor; explicit share grants in the companion table add named people on top."
+{
+  "html": "<div class=\"share-tiers\"><div class=\"diagram-card\"><span class=\"diagram-pill\">private</span><small class=\"diagram-muted\">owner + explicit grants only &middot; <strong>default</strong></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">org</span><small class=\"diagram-muted\">+ anyone in the same org (read-only)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">public</span><small class=\"diagram-muted\">+ anyone with the link (read-only) &middot; hidden from others' lists/search</small></div></div>",
+  "css": ".share-tiers{display:flex;flex-direction:column;align-items:stretch;gap:8px}.share-tiers .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.share-tiers .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+## 共有付与における役割 {#roles}
+
+特定のユーザーまたは組織と共有する場合は、役割を選択します。
+
+- **ビューア** — 読み取り専用。
+- **エディタ** — 読み取り + 書き込み。
+- **管理者** — 読み取り + 書き込み + 共有の管理 (他のユーザーの追加/削除が可能)。
+
+`admin` は NOT で所有権を変更します。共有付与とは異なり、リソースごとに所有者は依然として 1 人だけです。
+
+## 内容 {#covered}
+
+ユーザーが作成した作業を保存するすべてのテンプレートは、このモデルを使用します。具体的には:
+
+- **コンテンツ** — ドキュメント
+- **スライド** — デッキ
+- **デザイン** — デザインとアセット
+- **ビデオ** — 作品
+- **クリップ** — 画面録画 (Loom スタイル)
+- **フォーム** — フォーム定義
+- **カレンダー** — イベントと予約リンク
+- **Analytics** — ダッシュボード (展開中 — 分析テンプレートの `AGENTS.md` を参照)
+- **拡張機能** — サンドボックス化されたミニアプリ ([Extensions](/docs/extensions#sharing) を参照)
+
+これらはすべて、同じ `ownableColumns()` スキーマ ヘルパー、同じ `share-resource` アクション、および同じ `<ShareButton>` UI を使用します。あるテンプレートから別のテンプレートに移動すると、共有ダイアログは同じように見えます。
+
+## 対象外のもの {#not-covered}
+
+いくつかのエリアは意図的に共有システムの外にあります:
+
+- **個人データ アプリ** (メール、マクロ) — 設計によりユーザー スコープになっています。 「受信トレイを共有する」という概念はありません。
+- **外部信頼できる情報源アプリ** — アクセス制御は、エージェント ネイティブ アプリではなく、上流システムに存在します。
+- **匿名パブリック URL** — ログアウトしたユーザーに URL を公開するフォーム公開スラッグと予約リンク スラグは別の軸です。彼らは共有システムの上ではなく、共有システムと並行して生きています。
+
+## シェア UI {#share-ui}
+
+すべての共有可能なリソースには、ヘッダーに共有ボタンが表示されます。これをクリックすると、ボタンに固定されたポップオーバー (モーダルではなく) が開きます。
+
+- 可視性セレクター (`Private` / `Organization` / `Public link`)。
+- 「ユーザーまたはチームを追加」オートコンプリート — 組織内のユーザーを検索するか、メールを貼り付けます。
+- 個々の電子メール許可のための Google ドキュメント スタイルの `Notify people` チェックボックス。
+- ロールピッカーと削除コントロールを含む現在の許可のリスト。
+- 現在の表示設定を尊重するリンクのコピー ボタン。
+
+共有ボタンは単一のインポートです:
+
+```tsx
+import { ShareButton } from "@agent-native/core/client";
+
+<ShareButton
+  resourceType="deck"
+  resourceId={deck.id}
+  resourceTitle={deck.title}
+/>;
+```
+
+リストの場合、各行の横に `<VisibilityBadge visibility={row.visibility} />` をドロップすると、ユーザーが何がプライベートか共有かを一目で確認できるようになります。
+
+## 同じモデル、エージェント、UI {#agent-and-ui}
+
+フレームワークはこれらの actions をすべてのテンプレートに自動マウントします。エージェントはこれらをツールとして呼び出し、UI は `useActionQuery` / `useActionMutation` を通じてこれらを呼び出します。
+
+| アクション                | 機能                                                                                                           |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `share-resource`          | ユーザーまたは組織に特定のロールでのアクセスを許可します。オプションの `notify` は電子メール通知を制御します。 |
+| `unshare-resource`        | ユーザーまたは組織のアクセス権を取り消します。                                                                 |
+| `list-resource-shares`    | 現在の可視性とすべての明示的な許可を表示します。                                                               |
+| `set-resource-visibility` | `private`、`org`、または `public` に変更します。                                                               |
+
+エージェントに「このデザインを編集者としてマーケティング チームと共有する」ように指示すると、エージェントは UI が使用するのと同じエンドポイントに対して `share-resource` を呼び出します。結果は、次回のレンダリング時に共有ダイアログに表示されます。
+
+## 新しいテンプレートに組み込む {#building}
+
+テンプレートを作成している場合 ([Creating Templates](/docs/creating-templates) を参照)、配線の共有は短くなります。スキーマへの 2 つの追加:
+
+```ts
+import {
+  table,
+  text,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const decks = table("decks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  data: text("data").notNull(),
+  ...ownableColumns(), // adds owner_email, org_id, visibility
+});
+
+export const deckShares = createSharesTable("deck_shares");
+```
+
+```an-schema title="Resource + companion shares table" summary="Coarse visibility lives on the resource; each fine-grained grant is a row in the shares table."
+{
+  "entities": [
+    {
+      "id": "deck",
+      "name": "decks",
+      "note": "...ownableColumns()",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "title", "type": "text", "nullable": false },
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "The single source of truth for ownership." },
+        { "name": "org_id", "type": "text", "nullable": true },
+        { "name": "visibility", "type": "enum", "nullable": false, "note": "private | org | public" }
+      ]
+    },
+    {
+      "id": "deckShare",
+      "name": "deck_shares",
+      "note": "createSharesTable() — one row per grant",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "resource_id", "type": "text", "fk": "decks.id", "nullable": false },
+        { "name": "principal_type", "type": "enum", "note": "user | org" },
+        { "name": "principal_id", "type": "text", "note": "email (user) or org id (org)" },
+        { "name": "role", "type": "enum", "note": "viewer | editor | admin" },
+        { "name": "created_by", "type": "text" },
+        { "name": "created_at", "type": "text" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "deckShare", "to": "deck", "kind": "n-n", "label": "grants access to" }
+  ]
+}
+```
+
+`server/db/index.ts` での 1 つの登録呼び出し:
+
+```ts
+import { registerShareableResource } from "@agent-native/core/sharing";
+
+registerShareableResource({
+  type: "deck",
+  resourceTable: schema.decks,
+  sharesTable: schema.deckShares,
+  displayName: "Deck",
+  titleColumn: "title",
+  getResourcePath: (deck) => `/deck/${deck.id}`,
+  getDb,
+});
+```
+
+その後、リスト/読み取りクエリは `accessFilter()` を通過し、actions を書き込み、`assertAccess()` を使用してロールを強制します。
+
+### オプションの強化フラグ {#hardening-flags}
+
+`registerShareableResource` は、コードを実行するリソースまたは高い信頼を運ぶリソースに対して 2 つのセキュリティ フラグを受け入れます。
+
+```ts
+registerShareableResource({
+  type: "extension",
+  resourceTable: schema.extensions,
+  sharesTable: schema.extensionShares,
+  // ...
+  allowPublic: false, // Reject set-resource-visibility → "public"
+  requireOrgMemberForUserShares: true, // Reject user grants to non-org emails
+});
+```
+
+`allowPublic: false` は、呼び出し元 (エージェントまたは UI) がリソースの可視性を `public` に設定できないようにします。 `requireOrgMemberForUserShares: true` は、リソース所有者の組織外の電子メール アドレスに対する個々のユーザーの許可を拒否します。拡張機能は両方を設定します。拡張機能の HTML は、actions と DB を _viewer_ として呼び出す iframe 内で実行されるため、パブリック アクセスはビューアの資格情報を使用した任意のコードになります。
+
+```an-callout
+{
+  "tone": "risk",
+  "body": "For resources that execute code or carry elevated trust (like extensions), set `allowPublic: false` and `requireOrgMemberForUserShares: true`. Otherwise a public share becomes arbitrary code running with the *viewer's* credentials."
+}
+```
+
+`getResourcePath` は、エージェントまたは別の非 UI 呼び出し元によって共有が作成されたときに、通知メールに直接フォールバック リンクを送信します。完全なパターン (作成アクションの所有権スタンプや既存のテーブルの移行レシピを含む) は、`sharing` エージェント スキル内にあります。エージェントは、共有対応機能を構築するときにオンデマンドでそれを読み取ります。
+
+## セキュリティ保証 {#security}
+
+共有はフレームワークのより広範なデータスコープ モデルに基づいています。所有可能なテーブルへのリスト/読み取り/書き込みアクセスは `accessFilter()` / `resolveAccess()` / `assertAccess()` を経由し、`org_id` タグ付きリソースは組織間で表示されません。完全なパイプライン、CI ガード、および脅威サーフェスについては、[Security → Data Scoping](/docs/security#data-scoping) を参照してください。
+
+## こちらもご覧ください {#see-also}
+
+- [Security & Data Scoping](/docs/security) — 共有が利用するアクセス フィルターと所有権モデル。
+- [Authentication](/docs/authentication) — セッション、組織、および ID がリクエスト コンテキストにどのように流れ込むか。
+- [Extensions](/docs/extensions#sharing) — サンドボックス化されたミニアプリ サーフェスでの共有。
+- [Creating Templates](/docs/creating-templates) — `ownableColumns` を新しいテンプレートのスキーマに接続します。

package/corpus/core/docs/content/locales/ja-JP/skills-guide.md

@@ -0,0 +1,281 @@
+---
+title: "Skills ガイド"
+description: "エージェント ネイティブでの skills の動作: フレームワーク skills、ドメイン skills、カスタム skills の作成。"
+---
+
+# Skills ガイド
+
+Skills は、エージェントに特定のパターンとワークフローに関する深い知識を提供する Markdown ファイルです。
+
+## skills とは {#what-are-skills}
+
+Skills は `.agents/skills/<name>/SKILL.md` にあり、エージェント向けの詳細なガイダンスが含まれています。各スキルは、データの保存方法、状態の同期方法、エージェント チャットへの作業の委任方法という 1 つの懸念事項に重点を置いています。
+
+すべてのスキルのフロントマター `name` および `description` は常にシステム プロンプトの skills ブロックに挿入されるため、エージェントは skills が何であるかを認識します。エージェントがスキルがタスクに関連すると判断すると、完全なスキル本体がオンデマンドでロードされます (`docs-search` 経由でも表示されます)。これが、説明を短くし、トリガー固有にすることが重要である理由です。説明は、残りをロードするかどうかを決定する前にエージェントが読み取る唯一の内容です。
+
+```an-diagram title="Progressive disclosure" summary="Only the name + description of every skill is always in context. The full body loads on demand when the task matches."
+{
+  "html": "<div class=\"sk-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Always in the system prompt</span><div class=\"sk-list\"><span class=\"diagram-pill\">storing-data &mdash; <small class=\"diagram-muted\">add data models&hellip;</small></span><span class=\"diagram-pill\">real-time-sync &mdash; <small class=\"diagram-muted\">wire polling&hellip;</small></span><span class=\"diagram-pill\">create-skill &mdash; <small class=\"diagram-muted\">add a skill&hellip;</small></span></div><small class=\"diagram-muted\">just name + description (cheap)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><small class=\"diagram-muted\">task matches a description</small><span class=\"diagram-pill accent\">load on demand</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Full <code>SKILL.md</code> body<br><small class=\"diagram-muted\">rules, code, do/don't</small></div></div>",
+  "css": ".sk-flow{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.sk-flow .diagram-card{display:flex;flex-direction:column;gap:8px;padding:14px 16px;min-width:240px}.sk-flow .sk-list{display:flex;flex-direction:column;gap:6px}.sk-flow .center{display:flex;flex-direction:column;align-items:center;gap:6px}.sk-flow .diagram-arrow{font-size:22px}"
+}
+```
+
+## フレームワーク skills {#framework-skills}
+
+これらは、**デフォルト テンプレート**にバンドルされている skills です。特定のアプリで使用できる正確なセットは、スキャフォールディング元のテンプレートによって異なります。実際に同梱されているものについては、そのテンプレートの `.agents/skills/` ディレクトリを確認してください。
+
+| スキル                 | いつ使用するか                                                               |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| `storing-data`         | データ モデルの追加、構成または状態の読み取り/書き込み                       |
+| `real-time-sync`       | ワイヤリングポーリング同期、UI のデバッグが更新されない                      |
+| `delegate-to-agent`    | UI または actions からエージェントへの AI 作業の委任                         |
+| `actions`              | エージェント actions を作成または実行しています                              |
+| `self-modifying-code`  | アプリのソース、コンポーネント、スタイルの編集                               |
+| `create-skill`         | エージェントに新しい skills を追加します                                     |
+| `capture-learnings`    | 修正とパターンの記録                                                         |
+| `frontend-design`      | Web UI、コンポーネント、またはページの構築またはスタイル                     |
+| `adding-a-feature`     | 4 つの領域のチェックリスト: UI、actions、skills、アプリの状態                |
+| `internationalization` | ローカライズされた UI コピー、言語カタログ、および RTL セーフ スタイルの更新 |
+| `shadcn-ui`            | shadcn/ui プリミティブとコンポーネントの使用                                 |
+| `security`             | 認証、アクセス制御、およびシークレットの処理                                 |
+| `real-time-collab`     | マルチユーザーによる共同編集                                                 |
+| `agent-engines`        | 基盤となるエージェント エンジンの交換または構成                              |
+| `notifications`        | アプリ内通知とプッシュ通知のパターン                                         |
+| `progress`             | バックグラウンド タスクの進行状況の追跡と表示                                |
+| `inline-embeds`        | エージェント チャット内にアプリまたは iframe を埋め込む                      |
+
+`context-awareness` および `a2a-protocol` は、リポジトリ ルートの `.agents/skills/` ディレクトリで利用できるフレームワーク レベルの skills です。継承内容については、各テンプレートの独自の `.agents/skills/` を参照してください。
+
+## ドメイン skills {#domain-skills}
+
+テンプレートには、ドメインに固有の skills が含まれています。これらは同じ `.agents/skills/` ディレクトリに存在しますが、テンプレート固有のパターンをカバーします。完全なリストについては、各テンプレートの `.agents/skills/` ディレクトリを参照してください。代表的なサンプル:
+
+- **メール テンプレート** — `email-drafts`、`draft-queue`
+- **フォーム テンプレート** — `form-building`、`form-publishing`、`form-responses`
+- **分析テンプレート** — `adhoc-analysis`、`bigquery`、`cross-source-analysis`、`dashboard-management`、`data-querying`、`provider-api`、`gong`、`hubspot`、`prometheus`
+- **スライド テンプレート** — `create-deck`、`deck-management`、`design-systems`、`slide-editing`、`slide-images`
+
+ドメイン skills は、フレームワーク skills と同じ形式に従います。これらは、エージェントが従う必要があるテンプレートに固有のパターンをエンコードします。
+
+## アプリベースの skills {#app-backed-skills}
+
+アプリベースの skills は、エージェント ネイティブ アプリをスキル マーケットプレイス アーティファクトとしてパッケージ化します。バンドルには、エージェントの指示、エクスポートされた skills、MCP コネクタ メタデータ、ホスト/ローカルの起動指示、MCP アプリなどの UI サーフェスを含めることができます。
+
+> **詳細は以下の通り:** アプリベースの skills の仕組み (マニフェスト形式、CLI コマンド、マーケットプレイス アダプター、自動更新ハッシュ) は、[App-backed skills — full details](#app-backed-skills-full) で説明されています。
+
+## カスタム skills の作成 {#creating-skills}
+
+次の場合にスキルを作成します。
+
+- エージェントが繰り返し従うべきパターンがあります
+- ワークフローには段階的なガイダンスが必要
+- テンプレートからファイルをスキャフォールディングしたい
+
+次の場合はスキルを作成しないでください。
+
+- ガイダンスは別のスキルにすでに存在します - 代わりにそれを拡張します
+- ガイダンスは 1 回限りです。代わりに `AGENTS.md` またはワークスペース メモリに置きます
+
+## スキルフォーマット {#skill-format}
+
+各スキルは、YAML フロントマターを持つ Markdown ファイルです:
+
+```an-annotated-code title="Anatomy of a SKILL.md"
+{
+  "filename": ".agents/skills/project-imports/SKILL.md",
+  "language": "markdown",
+  "code": "---\nname: project-imports\ndescription: >-\n  How to import projects from the legacy CSV export. Use when the user uploads\n  a project CSV or asks to migrate projects from the old system.\n---\n\n# Project Imports\n\n## Rule\n\nAlways validate the CSV header row before writing any rows. Reject unknown\ncolumns rather than silently dropping them.\n\n## How\n\n1. Call `get-import-schema` to fetch the expected columns.\n2. Parse the first CSV row and diff against the schema.\n3. If any required columns are missing, return an error — do not proceed.\n4. Stream remaining rows through `create-project-item` in batches of 50.\n\n## Don't\n\n- Don't hold all rows in memory — stream them.\n- Don't create duplicate projects; check for an existing name first.\n\n## Related Skills\n\n- **storing-data** — SQL schema and write patterns for new rows\n- **sharing** — exposing a project to other users after import",
+  "annotations": [
+    { "lines": "2", "label": "Discovery key", "note": "The `name` matches the folder; it is how the skill is invoked as `/project-imports`." },
+    { "lines": "3-5", "label": "The trigger", "note": "This `description` is the **only** text always in context. Make it state precisely *when* the skill applies." },
+    { "lines": "9-14", "label": "Rules first", "note": "Lead with the hard rule and the why; the agent reads the body only once the task matches." },
+    { "lines": "27-30", "label": "Cross-link", "note": "Point at related skills so the agent can chain them instead of re-deriving guidance." }
+  ]
+}
+```
+
+フロントマター `name` および `description` は、スキル検出のためにエージェントのツール システムによって使用されます。説明には、スキルがいつ発動するかを記載する必要があります。状況について具体的に記載してください。
+
+ファイルを `.agents/skills/my-skill/SKILL.md` に保存します。ディレクトリ名は、frontmatter の `name` と一致する必要があります。
+
+> **こちらも参照:** スキルの説明を言葉で表現する方法、段階的な開示を適用する方法、`AGENTS.md` をスリムに保つ方法については、[Writing Agent Instructions](/docs/writing-agent-instructions) を参照してください。どちらのページでも、実行例として `project-imports` スキルを使用しています。
+
+## スキルの範囲: ランタイム vs 開発 {#skill-scope}
+
+オプションの `scope` フロントマター フィールドは、スキルがどのエージェントを対象とするかを制御します。
+
+| `scope`   | ランタイム エージェントによってロードされますか? | 用途                                                                                 |
+| --------- | ------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `both`    | はい (デフォルト)                                | Skills はアプリ内エージェントに役立ちます。 `scope` を省略した場合のデフォルトです。 |
+| `runtime` | はい                                             | Skills はアプリ内ランタイム エージェント専用です。                                   |
+| `dev`     | いいえ                                           | Skills は人間のコーディング エージェントのみを意味します (例: Claude コード)。       |
+
+```markdown
+---
+name: release-checklist
+description: >-
+  Steps for cutting a release. Use when preparing or publishing a new version.
+scope: dev
+---
+```
+
+`scope` が存在しない (または認識できない値に設定されている) 場合、デフォルトで `both` が設定されるため、既存のすべてのスキルは実行時にロードされ続けます。このフィールドは完全に下位互換性があります。 `scope: dev` スキルは、どこのランタイム エージェントからも見えません。システム プロンプトに挿入された skills ブロックおよび `docs-search` の結果から除外されます。
+
+### 開発専用スキルをコーディング エージェントに公開する {#dev-only-skills}
+
+エージェント ネイティブ ランタイムは、`.agents/skills/` から skills を読み取ります。 Claude コードは、`.claude/skills/` から skills を独立して読み取ります。スキルをコーディング エージェントが利用できるようにするが、ランタイム エージェントには非表示にするには:
+
+- ランタイム エージェントがロードしないように、`.agents/skills/<name>/SKILL.md` で `scope: dev` とマークします。
+- Claude コードがスキルを選択できるように、スキルを `.claude/skills/<name>/SKILL.md` の下に配置またはミラーリングします。
+
+これは、`.claude/skills` を読み取るだけの Claude コードに依存する古いハックを置き換えます。`scope: dev` は、開発とランタイムの分割を第一級の明示的な選択にします。
+
+```an-diagram title="Which agent loads which skill" summary="scopedecides whether the in-app runtime agent sees a skill.dev skills are visible only to your coding agent."
+{
+"html": "<div class=\"sc-grid\"><div class=\"diagram-card\"><span class=\"diagram-pill\">.agents/skills/</span><div class=\"sc-row\"><span class=\"diagram-pill ok\">scope: both</span><small class=\"diagram-muted\">default</small></div><div class=\"sc-row\"><span class=\"diagram-pill ok\">scope: runtime</span></div><div class=\"sc-row\"><span class=\"diagram-pill warn\">scope: dev</span></div></div><div class=\"sc-targets\"><div class=\"diagram-box\">Runtime agent<br><small class=\"diagram-muted\">reads <code>both</code> + <code>runtime</code></small></div><div class=\"diagram-box\">Coding agent<br><small class=\"diagram-muted\">Claude Code reads <code>.claude/skills/</code> + <code>dev</code></small></div></div></div>",
+"css": ".sc-grid{display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start}.sc-grid .diagram-card{display:flex;flex-direction:column;gap:8px;padding:14px 16px}.sc-grid .sc-row{display:flex;align-items:center;gap:8px}.sc-grid .sc-targets{display:flex;flex-direction:column;gap:10px}"
+}
+
+```
+
+> **こちらも参照:** スキルの説明を言葉で表現する方法、段階的な開示を適用する方法、`AGENTS.md` を無駄のないものに保つ方法については、[Writing Agent Instructions](/docs/writing-agent-instructions) を参照してください。
+
+## Skills 対 AGENTS.md {#skills-vs-agents-md}
+
+> **AGENTS.md** — 概要。すべてのスクリプトをリストし、データ モデルを説明し、アプリのアーキテクチャを説明します。エージェントはアプリを理解するために最初にこれを読みます。
+>
+> **Skills** — 詳細。各スキルは、詳細なルール、コード例、実行/禁止リストを備えた 1 つのパターンに焦点を当てています。エージェントは、特定のパターンに従う必要があるときにこれらを読み取ります。
+
+`AGENTS.md` は、アプリが「何をする」かをエージェントに伝えます。 Skills は、エージェントに特定のことを正しく実行する方法を指示します。両方が必要です。方向指定には `AGENTS.md`、実行には skills です。
+
+## Skills とメモリ {#skills-vs-memory}
+
+> **Skills** — 作成された再利用可能なハウツー ガイド。すべてのユーザーに適用され、タスクが一致したときにオンデマンドで呼び出されます。
+>
+> **メモリ (`LEARNINGS.md` / `memory/MEMORY.md`)** — プロジェクトの共有学習と個人の構造化メモリが毎ターン読み込まれます。
+
+その知識がアプリで作業しているすべての人に当てはまる場合 (「サブクエリよりも常に CTE を優先する」)、それはスキルまたは共有 `LEARNINGS.md` です。 _この特定のユーザー_ (「スティーブは簡潔な回答が好きです」) に関するものであれば、`memory/MEMORY.md` に属します。完全な治療法については、[Workspace Memory](/docs/workspace#memory) を参照してください。
+
+---
+
+# 上級
+
+## アプリによる skills — 詳細 {#app-backed-skills-full}
+
+App-backed skills は、エージェント ネイティブ アプリをスキル マーケットプレイス アーティファクトとしてパッケージ化します。
+バンドルには、エージェントの指示、エクスポートされた skills、MCP コネクタを含めることができます
+メタデータ、ホスト/ローカルの起動手順、MCP アプリなどの UI サーフェス。
+
+アプリでサポートされる各スキルは、アプリ ルートの `agent-native.app-skill.json` で始まります:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "assets",
+  "hosted": {
+    "url": "https://assets.agent-native.com",
+    "mcpUrl": "https://assets.agent-native.com/_agent-native/mcp"
+  },
+  "mcp": { "serverName": "agent-native-assets" },
+  "skills": [
+    {
+      "path": ".agents/skills/asset-generation",
+      "visibility": "both",
+      "exportAs": "assets"
+    }
+  ]
+}
+```
+
+スキルの可視性は、出荷されるものを制御します:
+
+| 可視性     | 意味                                                                                     |
+| ---------- | ---------------------------------------------------------------------------------------- |
+| `internal` | アプリ独自のエージェントによって使用され、マーケットプレイスにはエクスポートされません。 |
+| `exported` | マーケットプレイスにエクスポートされますが、アプリ内部では必要ありません。               |
+| `both`     | 内部的に使用され、エクスポートされます。                                                 |
+
+Hosted はデフォルトのインストール パスです。ローカル起動はカスタマイズのために明示的に行われます。
+オフラインでの作業、またはプライバシーに配慮した使用。
+
+```bash
+# Happy path: exported instructions plus hosted MCP connector.
+npx @agent-native/core@latest skills add visual-plan
+npx @agent-native/core@latest skills add assets
+
+# Repo-first Content docs/blog/MDX editing.
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+
+# Vercel/open Skills CLI: exported instructions only, no MCP config.
+npx skills@latest add BuilderIO/agent-native --skill assets
+
+# Register a hosted MCP connector for local agent clients.
+npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+
+# Materialize and run editable local source.
+npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+
+# Build marketplace adapters: Codex plugin, Claude marketplace, Vercel skills,
+# plain/Claude skills, and MCP configs.
+npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+
+# Install a local exported bundle with the Vercel/open Skills CLI.
+npx skills@latest add ./dist/assets-skill --skill assets -a codex -y
+
+# Add the generated Claude Code marketplace, then install its Assets plugin.
+claude plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace
+claude plugin install agent-native-assets@agent-native-apps
+```
+
+スキル ファイルに秘密を含めないでください。マニフェストには URL 専用コネクタ
+メタデータ; OAuth/デバイスのセットアップは、MCP ホストまたはアプリの通常の方法を通じて行われます
+設定フロー。
+
+Vercel Labs `skills` アダプターはポータブル `skills/<name>/SKILL.md` バンドルです
+`npx skills@latest add ...` 用ですが、生の `skills` CLI は手順のみをインストールします。
+リポジトリ定義のポストインストール スクリプトは実行されず、MCP コネクタは登録されません。
+Agent Native CLI をローカル エージェントのデフォルトのドキュメント パスとして保持します。
+は、MCP コネクタも登録します。 `BuilderIO/agent-native` は本物の GitHub
+Vercel/open Skills CLI のリポジトリ ソース。 `skills.sh` は発見であり、
+リーダーボード ディレクトリ。npm スタイルのパッケージ名前空間ではありません。
+
+Claude コード マーケットプレイス アダプターの書き込み
+`adapters/claude-marketplace/.claude-plugin/marketplace.json` とネストされた
+`skills/<name>/SKILL.md` および `.mcp.json` を含むプラグイン ディレクトリ。 Claude
+コードを作成し、マーケットプレイスを追加し、`agent-native-assets@agent-native-apps` をインストールします。
+プラグインをリロードし、`/mcp` からの URL 専用 MCP コネクタを認証します。
+
+生成されたプラグイン マニフェストは自動更新されるように設定されています: Claude コード
+マーケットプレイス エントリ セット `autoUpdate: true` (コミット SHA バージョン管理付き) と
+Codex プラグイン `version` には、バンドルされた skills および MCP のコンテンツ ハッシュが埋め込まれます
+エンドポイントなので、インストールされたプラグインは再パックせずにスキルの変更を取得します。
+プラン アプリは、この方法ですぐに追加できるマーケットプレイスとしてリポジトリ ルートに公開されます —
+エンドツーエンドのインストールについては、[Plan plugin & marketplace](/docs/plan-plugin) を参照
+および自動更新フロー。
+
+コピーされた skills を、ユニバーサル CLI の代わりにインストールするユーザー向け
+プラグイン マーケットプレイスでは、CLI 鮮度コマンドを使用します。
+
+```bash
+npx @agent-native/core@latest skills status visual-plan
+npx @agent-native/core@latest skills update visual-plan
+```
+
+`skills update` は既知の Codex/Claude プロジェクトとユーザー スキル フォルダーをスキャンし、比較します
+コピーされたフォルダーは最新のバンドル スキルにハッシュされ、古いフォルダーが書き換えられます
+場所。新しくコピーされた Agent Native skills には `agent-native-skill.json` が含まれます
+将来のステータス出力でソースとハッシュを識別できるようにするためのマーカー。
+
+生成された Agent Native アプリとワークスペースには、フレームワークが提供するものも含まれます
+skills under `.agents/skills` (or `packages/shared/.agents/skills` in a
+ワークスペース)。以下を使用して、スキャフォールドされた skills を現在/最新の CLI からリフレッシュします。
+
+```bash
+npm run skills:update
+# or, without relying on the local package script:
+npx @agent-native/core@latest skills update scaffold --project
+```
+
+`AGENTS.md` と `.agents/skills` は正規のままです。 update コマンドは修復も行います
+Claude コードが認識するための Claude 互換性リンク (`CLAUDE.md` および `.claude/skills`)
+2 番目のコピーを維持せずに同じ手順を実行します。