From 6cff2aa507dd3a0e4bb75d4ab67d6b3495cec55f Mon Sep 17 00:00:00 2001 From: Jinwoo-H Date: Tue, 11 Aug 2026 23:27:29 -0400 Subject: [PATCH] docs(skills): keep bundle shares unlisted --- ...t-skill-sharing-implementation-checklist.md | 15 ++++++++------- docs/agent-skill-sharing-installation-plan.md | 18 +++++++++--------- 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/agent-skill-sharing-implementation-checklist.md b/docs/agent-skill-sharing-implementation-checklist.md index 77a66980347..f7669bc03c1 100644 --- a/docs/agent-skill-sharing-implementation-checklist.md +++ b/docs/agent-skill-sharing-implementation-checklist.md @@ -139,6 +139,8 @@ does not mean the surrounding phase is complete. - [x] Decide Orca will not depend on the upstream CLI or an unsupported programmatic API. - [x] Decide V1 accepts Orca package sources only; Git, npm, and community registries remain with existing tools. +- [x] Decide every Skill Bundle share is unlisted and reachable only through its durable link; do + not add search, browsing, organization-library, marketplace, or contained-skill indexes. - [x] Record Agent Plugins 1.0.0 commit `bd383552095128f6effe895b9257cfd580a6d179` as the portable-format reference. - [x] Decide to implement from the specification without copying its CC BY prose or vendoring its @@ -212,7 +214,7 @@ does not mean the surrounding phase is complete. - [ ] Create fresh staging roots and reject unknown, malformed, or conflicting imported `dev.orca.skill-sharing` namespaces without overwriting them. - [x] Keep the detailed manifest inside the archive for export, remote/SSH transport, and offline - validation; keep GCS metadata compact and PostgreSQL searchable. + validation; keep GCS metadata compact and PostgreSQL limited to exact link/ownership lookup. - [x] Add selected skill IDs and per-skill conflict choices to preview/install requests. - [x] Return aggregate status plus ordered installed, unchanged, kept-local, and failed per-skill outcomes; support retrying failed items only. @@ -620,10 +622,10 @@ does not mean the surrounding phase is complete. - [x] Add foreign keys preventing blob-reference deletion while a published version uses it. - [x] Accept and stream-validate both the pre-release single-skill envelope and the new Agent Plugins skills-only bundle envelope during the desktop migration. -- [x] Store the detailed bundle manifest in the existing immutable version catalog and derive the - searchable bundle name and digest without changing object or ACL semantics. -- [ ] Adapt package/version records to bundle-level identity and add ordered per-version skill rows - with identity, digest, counts, warnings, and archive roots. +- [x] Store the detailed bundle manifest in the existing immutable version record without changing + object, share, or ACL semantics; expose it only after exact-link authorization or to owners. +- [x] Keep contained skills out of separate database rows and search indexes. Selective inspection + reads the validated manifest attached to the exact immutable version. - [ ] Keep detailed file identity in the in-archive manifest rather than duplicating it into GCS custom metadata. - [ ] Test forward migration, rollback strategy, backup restoration, and migration compatibility @@ -1177,11 +1179,10 @@ still require the listed split metrics, latency panels, and alerts. - [ ] Telemetry, logs, and diagnostic bundles contain no credentials or private contents. - [ ] Kill switches are tested without affecting discovery or existing installations. -## 15. Post-release team library and reconciliation +## 15. Post-release multi-machine management and reconciliation - [ ] Measure sharing, installation, update, conflict, fallback, failure, and multi-machine demand without collecting private contents. -- [ ] Design an organization skill library and immutable version history from usage evidence. - [ ] Add **Install on another machine** and bounded multi-machine progress. - [ ] Add optional desired-version policy for selected personal or organization machines. - [ ] Add opt-in drift and missing-install reconciliation that never overwrites modifications. diff --git a/docs/agent-skill-sharing-installation-plan.md b/docs/agent-skill-sharing-installation-plan.md index 919556fd013..4a444264dfb 100644 --- a/docs/agent-skill-sharing-installation-plan.md +++ b/docs/agent-skill-sharing-installation-plan.md @@ -36,6 +36,8 @@ Orca will: 7. Install each selected skill once into `.agents/skills` and add aliases only for detected agents that need provider-specific paths. 8. Record bundle/version provenance independently from the community CLI's lockfiles. +9. Keep every share unlisted: bundles are reachable only through their durable link and never + appear in search, browse, organization-library, or marketplace surfaces. The portable archive root follows Agent Plugins 1.0.0 for a skills-only package. Orca does not present Skill Bundles as a new executable plugin system: MCP servers, hooks, processes, connectors, @@ -333,8 +335,8 @@ Rules: - Orca-specific integrity and version data lives in `dev.orca.skill-sharing/manifest.json` rather than a top-level custom field or GCS metadata alone. It therefore survives export, SSH/remote transfer, and offline validation and can describe every skill and file. -- GCS custom metadata stays compact and operational. PostgreSQL remains the searchable package, - share, and version catalog. +- GCS custom metadata stays compact and operational. PostgreSQL stores only the package, share, + version, ACL, and lifecycle records needed to resolve a known link or manage an owned bundle. - Orca constructs a fresh staging root. If imported content already contains `dev.orca.skill-sharing`, Orca accepts only an appropriate recognized schema and rejects unknown, malformed, or conflicting contents; it never overwrites the namespace silently. @@ -521,10 +523,8 @@ Create migrations for: - `skill_packages`: stable bundle identity, owner organization, slug/name, creator, timestamps, and deletion state. - `skill_package_versions`: immutable version, package digest, archive SHA-256, GCS object key and - generation, byte and skill counts, compact searchable metadata, release notes, creator, and - publication state. -- `skill_package_version_skills`: ordered per-skill identity, name, description, digest, file and - byte counts, warnings, and archive root for preview and selective installation. + generation, byte and skill counts, release notes, creator, publication state, and the validated + bundle manifest needed to inspect a known share without downloading its private archive. - `skill_package_uploads`: tenant/user binding, quarantine key and generation, expected identities, expiration, finalization state, and failure category. - `skill_package_acl`: organization or user principal, permission, creator, and timestamps. @@ -539,6 +539,7 @@ Required constraints and indexes include: - Unique immutable version ID and package digest identity. - Tenant-scoped archive identity and final GCS object key/generation pair. - Share lookup by unpredictable ID and active/revoked state. +- No package, version, or contained-skill search/list index; share links are intentionally unlisted. - ACL lookup by package and principal. - Pending-upload lookup by owner and expiration. - Foreign keys that prevent removing a blob reference while a published version uses it. @@ -797,7 +798,7 @@ and test the same contract accurately. - Skill upload grant creation and finalization. - Share creation, resolution, revocation, and access management. - Download grant creation. -- Package catalog and version lookup. +- Owned-package management and exact package/version lookup by ID; no browse or search API. - Manager-only package details include current user/organization access and active, unexpired share records; non-managers never receive that management metadata. @@ -1318,11 +1319,10 @@ Exit criteria: Estimate: 4–7 engineer-days, depending on host-helper availability. -### Phase 5: team library and reconciliation +### Phase 5: multi-machine management and reconciliation Deliver: -- Organization skill library and version history. - “Install on another machine” and multi-machine progress. - Optional desired-version policy for selected personal or organization machines. - Drift and missing-install reconciliation.