Central management without central ambiguity
++ People author a portable skill once, assign it to useful targets, and choose how + much of the applicable catalog enters each session. The system records exactly what + ran. +
+
+ Proposed design / August 2026
+ Skills,
+
+ Skills,
managed.
+ + A platform-native system for authoring, assigning, selecting, pinning, and safely + installing reusable agent capabilities before OpenCode starts. +
+ +
+
+ 4core concepts
+ 3assignment scopes
+ 20skills / session max
+ 5 MiBsession content max
+ No chapter matches that search.
+
+
+ 01
+
+
+ Start here
+
+
+ The frame
++ V1 is intentionally scoped to the product that exists today: one trusted installation, + canonical users, environments, repositories, sessions, and provider-neutral sandboxes. + It does not pretend that a team authorization boundary already exists. +
+ +
+
+ Product thesis
+
+
+ Tenancy stance
+
+
+ Goal
+
+
+ Goal
+
+
+ Goal
+
+
+
+
+ Installation-wide, not fake teams
++ "Team-managed" means shared by admitted users in V1. Real team ACLs must later cover + sessions, repos, environments, secrets, integrations, and skills together. +
+Author in platform
+Create and modify standard skill trees, with creator and revision attribution.
+Target precisely
+Assign globally, to exact repositories, or to exact saved environments.
+Reproduce sessions
+Resolve once, pin immutable content, and show provenance in session details.
+| Format | +Portable Agent Skills directory with required SKILL.md. |
+
|---|---|
| Versioning | +Immutable internal revisions now; history, diffs, tags, and rollback later. | +
| Storage | +D1 for bounded UTF-8 trees in V1; R2 for larger or binary packages later. | +
| Delivery | ++ Session-authenticated fetch from the sandbox, never environment-variable payloads. + | +
| Failure | ++ Fail startup if selected skills cannot be authenticated, verified, or installed. + | +
+ 02
+
+
+ Domain language
+
+
+ Four clean concepts
++ Content, applicability, user preference, and execution provenance are separate records. + This prevents profiles from becoming copies and prevents later edits from mutating a + session already in flight. +
+ +
+
+
+
+
+ 01 / CONTENTSkill
+
+ A stable catalog identity pointing at current immutable content.
+
+ 02 / APPLICABILITYAssignment
+
+ A global, repository, or environment rule that can match a target.
+
+ 03 / PREFERENCEProfile
+
+ A user's reusable explicit selection from the shared catalog.
+
+ 04 / EXECUTIONManifest
+
+ The exact revisions, sources, profile, and digest pinned to one session.
+
+
+ Immutable underneath
+
+
+ Mutable above
+
+
+ Every successful save becomes a revision
++ V1 exposes only current content, but the data plane references revision IDs and + SHA-256 digests. History becomes a product feature later without changing runtime + semantics. +
+Assignments and profiles remain lightweight
++ They reference stable skill identities. A session turns those moving references into + one permanent manifest before its Durable Object is initialized. +
+
+ 03
+
+
+ User journey
+
+
+ Author to session
++ The experience is split between shared catalog management and personal session choice. + The canonical name is immutable; content changes affect only sessions created after + save. +
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Scan the catalog
++ See canonical name, description, state, assignments, creator, last editor, + update time, and validation. +
+Control lifecycle
++ Disable to stop new resolution or soft-delete while retaining revisions required + by pinned sessions. +
+
+
+
+
+
+
+
+
+
+
+ Content
+Structured frontmatter, Markdown body, and supporting UTF-8 file tree.
+Assignments
+Global toggle plus repository and environment multi-selects.
+Details
+Creator, digest, timestamps, validation, disable, and delete.
+
+
+ + Profiles are personal explicit sets, not copied content. A selected skill still + loads only when an assignment makes it applicable to the current target. +
+
+
+
+
+ | All applicable | +Default for people, bots, integrations, and old clients. | +
|---|---|
| No managed skills | +Explicit opt-out from centrally managed skills. | +
| Named profile | +Intersect applicable skills with the user's saved set. | +
+ 04
+
+
+ Try the rules
+
+
+ Resolution, made visible
++ Assignments form the applicable set. The user's selection filters it. The result is + bounded, sorted, generation-checked, and persisted with the session snapshot. +
+ +
+
+
+
+
+ Interactive resolver
+
+
+
+
+
+
+
+
+
+ + Example catalog only. The real resolver also records every matching assignment + source. +
+
+ Pinned result
+
+ 0 skills selected
+ +
+
+ Consistency
+
+
+ Limits
+
+
+ Child sessions
+
+
+ Generation check
++ Read generation, resolve, read again, and retry if any catalog/profile mutation + occurred. +
+No truncation
+More than 20 skills or 5 MiB fails preview and creation with a specific error.
+Copy the parent
++ Agent-spawned children inherit the exact pinned manifest and selection provenance. +
+
+ 05
+
+
+ Control plane
+
+
+ Platform design
++ D1 holds bounded text revisions and all relationship metadata. Human APIs author and + preview; session APIs expose provenance; two sandbox-only APIs deliver and acknowledge + the pinned manifest. +
+ +
+
+
+
+
+
+
+
+
+
+ +skills_catalog_state +skills --------------> skill_revisions --------------> skill_revision_files + | ^ + +--- skill_assignments | + | +skill_profiles --- skill_profile_items + +sessions --- session_skill_manifests --- session_skill_revisions+
+
+ +GET /skills +POST /skills +GET /skills/:id +PATCH /skills/:id +PUT /skills/:id/content If-Match: <revision-id> +DELETE /skills/:id +POST /skills/preview + +GET /skill-profiles +POST /skill-profiles +PATCH /skill-profiles/:id +DELETE /skill-profiles/:id +POST /skills/resolve-preview +GET /sessions/:id/skills+
+
+ + GET /sessions/:id/sandbox-skills + +Authentication: + session-specific sandbox bearer token + validated by the Session Durable Object + +Rejected: + human principals + internal HMAC service principals + tokens bound to another session+
+
+ + Cross-language digests use domain-separated, length-prefixed byte grammars. Files + are sorted by UTF-8 path bytes; skills by canonical name then ID; assignment sources + by a fixed identity tuple. TypeScript and Python share fixtures. +
+
+ 06
+
+
+ Data plane
+
+
+ Before OpenCode starts
++ Runtime fetch is the only reliable ordering point across providers and restores. Managed + content is staged in OpenCode's global skills directory, outside repository checkouts. +
+ +
+
+
+
+
+ BOOTPrepare repos
+
+ Clone, sync, run hooks, and assemble multi-repo OpenCode configuration.
+
+ FETCHGet manifest
+
+ Authenticate as this sandbox and retrieve only pinned revisions.
+
+ VERIFYValidate twice
+
+ Recheck names, paths, limits, UTF-8, source collisions, and every digest.
+
+ INSTALLJournaled swap
+
+ Repair prior journals, install the complete tree, then launch.
+
+
+ Filesystem ownership
+
+
+
+ ~/.config/opencode/skills
+ + The platform owns this global directory inside its sandboxes. Repository and bundled + skills retain their existing project locations. The collision scan excludes the + managed destination itself so a restored snapshot does not collide with its own + tree. +
+
+ 07
+
+
+ Threat model
+
+
+ Instructions are executable
++ Markdown can direct an agent to run scripts, inspect injected credentials, or exfiltrate + data through tools it already has. Skills are supply-chain content, not harmless notes. +
+ +
+
+ What V1 enforces
+
+ Verified authorship, safe YAML, bounded UTF-8 files, normalized relative paths, no
+ links or special files, per-file and package digests, session-bound download auth,
+ independent runtime validation, and fail-closed materialization.
+
+
+
+ What skills never grant
+
+
+ allowed-tools is rejected. Skill use never grants MCP access, secrets,
+ shell permissions, network access, or external SaaS authorization. Those remain
+ separate enforcement planes.
+
+
+ Accepted V1 trust risk
+
+ All admitted users may edit installation-wide content under the current single-tenant
+ trust model. Deployments that do not trust all admitted users keep the feature
+ disabled until editor roles or an allowlist exist.
+
+
+
+
+
+ Failure posture
+
+ Invalid edits preserve the current revision. Missing content, auth failure, hash
+ mismatch, or exhausted startup retries fail the sandbox before OpenCode starts. Name
+ collisions keep the discovered skill, drop the managed entry, and emit a warning.
+ Activation callback failure alone retries best-effort after local success.
+
+
+
+ Per skill
+
+
+ Per session
+
+
+ Lifecycle
+
+
+ 1 MiB / 100 files
++ Each file is at most 256 KiB and paths are at most 240 bytes deep across 10 + segments. +
+5 MiB / 20 skills
+Resolution returns an error instead of dropping entries to fit.
+No mid-session refresh
+Updates prepare future sessions; already-pinned sessions remain reproducible.
+
+ 08
+
+
+ Delivery plan
+
+
+ Earn the runtime
++ Build and observe the catalog and resolver before allowing content into production + sandboxes. Runtime injection is the third phase, not the first demo. +
+ +
+
+ PHASE 0
+
+
+ PHASE 1
+
+
+ PHASE 2
+
+
+ PHASE 3
+
+
+ PHASE 4
+
+
+ Format and hardening
++ Shared limits, parser, digest fixtures, collision detection, provider deployment + hashes. +
+Catalog and authoring
++ D1, stores, CRUD APIs, settings editor, authorship, internal revisions. Injection + stays off. +
+Assignments and preview
++ Scopes, personal profiles, warmed-session key, manifest persistence, staging + comparison. +
+Sandbox delivery
+Authenticated fetch, materializer, internal rollout, opt-in, default.
+Governance
++ History, review, Git import, R2, ACLs, signed packages, evals, canaries, revocation. +
+
+ 09
+
+
+ External evidence
+
+
+ Patterns, not imitation
++ The portable file format is standard. Assignment, profiles, transport, version pinning, + and precedence are Open-Inspect product decisions informed by adjacent systems. +
+ +
+ Agent SkillsPortable format and progressive disclosure
+ OpenCodeDiscovery locations and native skill tool
+ Claude CodeScopes, precedence, and namespacing
+ CodexRepository, user, admin, system scopes
+ GitHub CopilotProject and personal skill distribution
+ OPA bundlesVerified activation and status reporting
+ LangSmithImmutable commits and movable tags
+ PromptLayerApprovals, evaluations, release labels
+ SLSADigest and invocation provenance
+
+
+
+ Continue into the implementation-grade plan
++ The Markdown document includes complete logical DDL, exact digest byte grammar, API + payloads, failure matrix, testing matrix, alternatives, file map, and future version + control design. +
+ Read managed-skills.md +