Add versioned Skills and hosted template references

CONTRIBUTING.md

@@ -45,6 +45,8 @@ and Clippy, and Linux OpenSSL development libraries. `make sqlc-generate` owns o
 migrations. The public protocol schema is `contracts/agents-api/openapi.yaml`;
 there is no product swaggo contract in this repository. Preserve its pinned types,
 coverage ledgers and official SDK/raw HTTP tests when changing API behavior.
+Run `make openapi` after handler annotation changes. It reuses the original
+Core-only swaggo v1.16.4 generator and writes this schema, without product routes.
 
 Core changes must retain the independent build and official-client workflow.
 Changes to native Harness sources require `make check-agents-harness-native`,
@@ -248,7 +250,7 @@ Completed environments never reinstall initial files on reconnect or native reco
 Provider RunCommand carries bounded stdin, not confidential argv. Only fixed trusted
 initializers may run with Runtime authority. User setup and package install hooks
 run in the common packaged sandbox, without daemon credentials or native history.
-Files and inline Skills precede system, npm/Python packages and ordered setup commands. Initialization has
+Files and resolved Skills precede system, npm/Python packages and ordered setup commands. Initialization has
 provisioning network access; requested network restrictions apply to native tools
 after setup. Confidential env and setup snapshots are encrypted independently of
 ordinary metadata. Adapters apply tool env only after isolation, never to the
@@ -271,19 +273,39 @@ Core preserves the system-package requirement in the common execution binding;
 a missing installation receipt fails preparation instead of falling back to base
 tools. This requirement does not add execution prerequisites to Files reads.
 
-Inline Skill ZIPs use the same confidential initialization snapshot and installer.
+Skills and their immutable versions are Core-owned tenant resources, independent of
+Sessions and native Skill installations. Serialize version allocation and pointer
+mutations under the owning Skill row; preserve unique version identities across
+concurrent uploads and deletion. Metadata reads never load or decrypt bundle bytes.
+Encrypt bundle contents with a tenant, Skill and version binding using the existing
+service cipher. Deleting a Skill reclaims its versions without affecting already
+frozen Session initialization. Public reference metadata, unresolved template intent
+and the resolved Runtime bundle are distinct; do not report a reference as inline
+merely because it reuses the same installer. No compatibility reader, source
+cache, extra lifecycle owner or per-harness resource implementation is required.
+Resolve references inside the Session creation transaction, after the creation
+upsert establishes ownership. Lock referenced resources in a stable order; freeze
+the selected version, descriptive metadata and bytes together. Creation retries
+recover the recorded intent before reading mutable templates or Skill sources.
+Templates preserve omitted/default, latest and explicit version selectors. Session
+responses contain concrete versions; only validated installation metadata crosses
+the Runtime boundary. A supplied Session Skill list replaces the template list;
+omission inherits. Explicit null reference selectors and null list overrides remain
+unqualified and reject rather than silently changing selection.
+
+Inline and referenced Skill ZIPs use the same confidential initialization snapshot and installer.
 Core validates portable manifests and bounded regular-file archives, returns only
 safe Skill metadata, and freezes content before native preparation. The Runtime
 owns `/environment/initialization/capabilities/skills/<name>`; setup and native tools may read but
 not modify this tree. The common execution descriptor carries Skill metadata,
 never native plugin configuration or template identities. Adapters register native
 Skill roots without changing the execution loop or enabling unrestricted tools.
 Native activation extensions remain adapter-owned and must fail explicitly when
-unqualified. Skills API references, generic Plugins and capability-directory
+unqualified. Generic Plugins and capability-directory
 imports remain separate work; an adapter-owned Claude plugin envelope does not
 implement public Plugins.
 
-Name, enabled/disabled/exact-domain restricted network, initial files, inline Skills and env/setup/system/npm/Python are
+Name, enabled/disabled/exact-domain restricted network, initial files, inline/referenced Skills and env/setup/system/npm/Python are
 implemented independently of remaining installation fields. Reject unsupported
 inputs rather than persisting them for silent
 omission; expand inline and template initialization together in separately qualified

Makefile

@@ -1,6 +1,7 @@
 SHELL := /bin/bash
 SQLC_VERSION ?= v1.29.0
 SQLC ?= go run github.com/sqlc-dev/sqlc/cmd/sqlc@$(SQLC_VERSION)
+SWAG_VERSION ?= v1.16.4
 
 .PHONY: help check check-database check-go check-sqlc sqlc-generate node-deps check-claude-sdk check-mcode-harness build-daemon build-agents-api build-agents-api-release check-agents-api docker-build-agents-api check-agents-api-container build-agents-executor check-agents-executor build-agents-harness check-agents-harness check-agents-harness-native build-agents-runtime build-claude-runtime build-claude-sdk-runtime build-mcode-harness build-mcode-runtime
 
@@ -16,6 +17,16 @@ check-database:
 sqlc-generate:
 	cd services/agents-api && $(SQLC) generate
 
+.PHONY: openapi
+openapi:
+	@set -e; root="$${PARSAR_HOME:-$$HOME/.parsar}/build"; mkdir -p "$$root"; \
+	output=$$(mktemp -d "$$root/core-openapi.XXXXXX"); trap 'rm -rf "$$output"' EXIT; \
+	go run github.com/swaggo/swag/cmd/swag@$(SWAG_VERSION) init \
+	    -g cmd/server/main.go --dir ./services/agents-api,./contracts/agents-api/v1 \
+	    --exclude ./services/agents-api/internal/executor --output "$$output" \
+	    --outputTypes yaml --parseInternal; \
+	mv "$$output/swagger.yaml" contracts/agents-api/openapi.yaml
+
 check-sqlc:
 	python3 scripts/check-sqlc.py
 

contracts/agents-api/README.md

@@ -64,20 +64,23 @@ This inventory is based on the pinned Python source, not our generated OpenAPI.
 It contains 42 distinct HTTP operations in 15 resource classes, excluding async
 duplicates, overloads and client-side helpers. There are 36 handler entries; the six
 Subagent read operations remain missing. The separate
-general `/v1/files` source-file API is outside this 42-operation count.
+general `/v1/files` source-file API and `/v1/skills` resource/version operations
+are outside this 42-operation count.
 
 An implemented route is not complete semantic compatibility. **Accepted** below
 means a recorded workflow passed under a specific profile; **partial** means some
 variants work; **missing** means no implementation; **unverified** means behavior
 has not been shown to match upstream. Do not convert the route count into a
 compatibility percentage or treat a Docker result as E2B qualification.
 
-Paths below are SDK resource paths beneath `client.beta.agents`. Method names use
-the Python SDK. Vault HTTP paths start at `/vaults`, not `/agents/vaults`.
+Paths below are SDK resource paths beneath `client.beta.agents`, except Skills
+and Versions under `client.skills`. Method names use the Python SDK. Vault HTTP
+paths start at `/vaults`, not `/agents/vaults`.
 
 | Resource | Upstream operations | Current coverage |
 | --- | --- | --- |
 | Root reusable Agents | create, retrieve, update, list, delete | Partial create/retrieve/update/list/delete and Session references; configuration/error gaps remain |
+| Skills and Versions | create, retrieve, update default, list, delete, content | [Tenant-owned encrypted bundles and hosted references](environment-templates.md); qualified upload limits and unresolved hosted semantics are recorded explicitly |
 | sessions | create, retrieve, update, list, delete | Create (ordinary/live), retrieve, list with root-Agent filter, metadata-only update, public deletion with owned Docker/E2B cleanup; general physical cleanup and exact hosted semantics remain open |
 | sessions.events | create, stream | Text/cancel/function-result admission and live events; function-action state snapshots supported |
 | sessions.turns | retrieve, list | Implemented reads; lifecycle conformance still partial |
@@ -89,7 +92,7 @@ the Python SDK. Vault HTTP paths start at `/vaults`, not `/agents/vaults`.
 | sessions.subagents.turns.items | list | Missing |
 | environments | retrieve | Supported Codex self-hosted and three-harness Docker/E2B hosted profiles: durable status and safe initial-file metadata; other installation inventory and full lifecycle parity remain gaps |
 | environments.files | create, list | [Bounded live listing and inline/source-file creation](environment-files.md) on qualified Docker/E2B workspaces; Codex self-hosted listing is a separate supported path. Full listing, overwrite and error semantics remain partial |
-| environments.templates | create, retrieve, update, list, delete | [Reusable network, files, env/setup/packages, inline Skills and Session snapshots](environment-templates.md); other initialization and full semantics remain gaps |
+| environments.templates | create, retrieve, update, list, delete | [Reusable network, files, env/setup/packages, inline/referenced Skills and Session snapshots](environment-templates.md); other initialization and full semantics remain gaps |
 | vaults | create, retrieve, list, delete | Create/retrieve/list/delete with independent tenant persistence, stored status filtering, atomic Credential cascade and frozen Session attachments; archive semantics and full hosted lifecycle parity remain missing |
 | vaults.credentials | create, retrieve, update, list, delete | Static-bearer create/retrieve/list/token replacement/deletion with scoped encrypted storage; Session attachment and exact-URL HTTPS MCP binding; OAuth, archive semantics and full hosted lifecycle parity remain missing |
 
@@ -155,7 +158,7 @@ user-managed enrollment remain outside this qualification.
 | Area | Missing or unverified scope |
 | --- | --- |
 | Subagents / multi_agent | Six public child read operations, enabled execution, child lifecycle/interactions and full recovery; deferred outside the MVP |
-| Environment Templates | Skills references, Plugins, capability directories, unsupported restricted hostname forms, installation overrides/null network and exact hosted errors; CRUD/list, files, env/setup/system/npm/Python, inline Skills and Session references are supported |
+| Environment Templates | Plugins, capability directories, unsupported restricted hostname forms, installation overrides/null network and exact hosted errors; CRUD/list, files, env/setup/system/npm/Python, inline/referenced Skills and Session references are supported |
 | Input and configuration | Non-text initial input, broader content/configuration unions, structured output and reasoning/verbosity combinations |
 | Tools and interactions | Deferred functions, other tool types, effective tool-set enforcement and result/cancel publication ordering; MiniMax public functions/MCP remain unsupported |
 | Vault and Credentials | OAuth/refresh, archive semantics, revocation/concurrent mutation and exact hosted selection/error behavior; static bearer CRUD/token replacement is already present |