@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ko-KR/sharing.md

@@ -0,0 +1,219 @@
+---
+title: "공유 및 개인정보 보호"
+description: "프레임워크에 내장된 Google-Docs 스타일 공유. 문서, 대시보드, 디자인, 데크, 클립, 녹음, 양식 등 사용자가 생성한 모든 리소스는 하나의 일관된 공유 UI를 통해 기본적으로 동일한 비공개 모델을 얻습니다."
+---
+
+# 공유 및 개인정보 보호
+
+문서, 대시보드, 디자인, 데크, 비디오 편집, 화면 녹화, 회의 기록, 양식, 예약 링크 등 사용자가 에이전트 기반 앱에서 생성하는 모든 리소스는 **기본적으로 작성자에게 공개됩니다**. 다른 사람들은 작성자가 명시적으로 공유하거나 공개 상태를 `org` 또는 `public`로 변경한 경우에만 볼 수 있습니다.
+
+Google 문서도구처럼 보이고 작동합니다. 동일한 공유 버튼, 동일한 대화 상자, 동일한 3계층 가시성 모델, 동일한 사용자별/조직별 부여 — 앱별 재창조 없이 모든 템플릿에 적용됩니다.
+
+## 왜 하나의 모델 {#why}
+
+대부분의 앱 프레임워크는 기능별 프로젝트를 공유합니다. 결과: 모든 문서와 유사한 표면은 자체 공유 대화 상자, 자체 권한 스키마, 자체 액세스 확인 버그로 끝납니다. 에이전트 기반에서 공유는 **프레임워크 기본**입니다. 스키마 열, 액세스 확인 도우미, 공유 팝오버 및 에이전트 호출 가능 공유 actions는 모두 코어와 함께 제공됩니다. 새 템플릿은 두 개의 열과 한 줄의 등록을 추가하여 완전한 공유 스토리를 제공합니다.
+
+이는 상담원이 앱별로 새로운 공유 모델을 배울 필요가 없다는 의미이기도 합니다. 상담원에게 어떤 템플릿에서든 "편집자인 Alice와 공유하세요"라고 말하면 동일한 `share-resource` 작업이 실행됩니다.
+
+## 세 가지 가시성 수준 {#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의 소유권을 변경합니다. 공유 부여와는 별도로 리소스당 소유자는 여전히 정확히 한 명입니다.
+
+## 다루는 내용 {#covered}
+
+사용자가 작성한 작업을 저장하는 모든 템플릿은 이 모델을 사용합니다. 구체적으로:
+
+- **콘텐츠** — 문서
+- **슬라이드** — 자료
+- **디자인** — 디자인 및 자산
+- **동영상** — 작곡
+- **클립** — 화면 녹화(Loom 스타일)
+- **양식** — 양식 정의
+- **캘린더** — 이벤트 및 예약 링크
+- **분석** — 대시보드(출시 — 분석 템플릿의 `AGENTS.md` 참조)
+- **확장** — 샌드박스 미니 앱([Extensions](/docs/extensions#sharing) 참조)
+
+이들 모두는 동일한 `ownableColumns()` 스키마 도우미, 동일한 `share-resource` 작업 및 동일한 `<ShareButton>` UI를 사용합니다. 한 템플릿에서 다른 템플릿으로 이동하면 공유 대화 상자가 동일하게 보입니다.
+
+## 포함되지 않는 내용 {#not-covered}
+
+일부 영역은 의도적으로 공유 시스템 외부에 있습니다.
+
+- **개인 데이터 앱**(메일, 매크로) - 사용자 범위로 설계되었습니다. '받은편지함 공유' 개념은 없습니다.
+- **외부 정보 소스 앱** — 액세스 제어는 에이전트 기본 앱이 아닌 업스트림 시스템에 있습니다.
+- **익명 공개 URLs** — 로그아웃한 사용자에게 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) 참조) 배선 공유가 짧습니다. 스키마에 두 가지 추가 사항:
+
+```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`에서 한 번의 등록 호출:
+
+```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`는 코드를 실행하거나 높은 신뢰를 전달하는 리소스에 대해 두 가지 보안 플래그를 허용합니다.
+
+```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/ko-KR/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`에 거주하며 상담원을 위한 자세한 지침을 담고 있습니다. 각 기술은 데이터 저장 방법, 상태 동기화 방법, 상담원 채팅에 작업 위임 방법 등 한 가지 문제에 중점을 둡니다.
+
+모든 스킬의 앞부분 `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`      | 웹 UI, 구성 요소 또는 페이지 구축 또는 스타일 지정          |
+| `adding-a-feature`     | 4개 영역 체크리스트: UI, actions, skills, app-state         |
+| `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}
+
+다음과 같은 경우에 스킬을 생성하세요:
+
+- 상담원이 반복적으로 따라야 하는 패턴이 있습니다
+- 워크플로우에는 단계별 지침이 필요합니다
+- 템플릿에서 파일을 스캐폴딩하려는 경우
+
+다음과 같은 경우에는 스킬을 생성하지 마세요:
+
+- 다른 기술에 이미 지침이 있습니다. 대신 확장하세요.
+- 지침은 일회성입니다. 대신 `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`에 파일을 저장합니다. 디렉토리 이름은 머리말의 `name`와 일치해야 합니다.
+
+> **또한 참조:** 기술 설명을 단어로 표현하고, 점진적 공개를 적용하고, `AGENTS.md`를 간결하게 유지하는 방법은 [Writing Agent Instructions](/docs/writing-agent-instructions)를 참조하세요. 두 페이지 모두 `project-imports` 스킬을 실행 예시로 사용합니다.
+
+## 기술 범위: 런타임 대 개발 {#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/skills/<name>/SKILL.md` 아래에 스킬을 배치하거나 미러링하면 Claude 코드가 이를 선택할 수 있습니다.
+
+이것은 `.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** — 심층 분석. 각 기술은 세부 규칙, 코드 예제, 해야 할 일/하지 말아야 할 목록이 포함된 하나의 패턴에 중점을 둡니다. 에이전트는 특정 패턴을 따라야 할 때 이를 읽습니다.
+
+`AGENTS.md`는 앱이 *무슨 일을*하는지 상담원에게 알려줍니다. Skills는 에이전트에게 특정 작업을 올바르게 수행하는 방법을 _방법_ 알려줍니다. 둘 다 필요합니다. 방향을 지정하려면 `AGENTS.md`, 실행을 위해서는 skills가 필요합니다.
+
+## Skills 대 메모리 {#skills-vs-memory}
+
+> **Skills** — 재사용 가능한 제작 방법 가이드입니다. 모든 사용자에게 적용되며 작업이 일치할 때 요청 시 호출됩니다.
+>
+> **메모리(`LEARNINGS.md` / `memory/MEMORY.md`)** — 공유 프로젝트 학습 및 개인 구조화된 메모리가 매 턴 로드됩니다.
+
+지식이 앱에서 작업하는 *모든 사람*에게 적용된다면("항상 하위 쿼리보다 CTE를 선호합니다"), 그것은 기술 또는 공유 `LEARNINGS.md`입니다. _이 특정 사용자_("Steve는 간결한 답변을 좋아합니다")에 관한 것이라면 `memory/MEMORY.md`에 속합니다. 전체 치료에 대해서는 [Workspace Memory](/docs/workspace#memory)를 참조하세요.
+
+---
+
+# 고급
+
+## 앱 지원 skills — 전체 세부정보 {#app-backed-skills-full}
+
+앱 지원 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`     | 내부적으로 사용되며 내보내집니다.                                 |
+
+호스팅이 기본 설치 경로입니다. 로컬 출시는 사용자 정의를 위해 명시적입니다.
+오프라인 작업 또는 개인 정보 보호에 민감한 사용
+
+```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는 지침만 설치합니다.
+repo 정의 사후 설치 스크립트를 실행하거나 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 앱은 저장소 루트에 바로 추가할 수 있는 마켓플레이스로 이러한 방식으로 게시됩니다 —
+전체 설치에 대해서는 [Plan plugin & marketplace](/docs/plan-plugin)를 참조하세요
+및 자동 업데이트 흐름
+
+대신 범용 CLI를 통해 복사된 skills를 설치하는 사용자의 경우
+플러그인 마켓플레이스에서는 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 앱 및 작업 공간에는 프레임워크 제공도 포함됩니다.
+`.agents/skills` 아래의 skills(또는 a의 `packages/shared/.agents/skills`
+작업 공간). 다음을 사용하여 현재/최신 CLI에서 스캐폴드된 skills를 새로 고칩니다.
+
+```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`는 표준을 유지합니다. 업데이트 명령도 복구됩니다
+Claude 호환성 링크(`CLAUDE.md` 및 `.claude/skills`)이므로 Claude 코드는
+두 번째 사본을 유지하지 않고 동일한 지침을 따릅니다.