agentic-mobile-control/openspec/changes/skill-management-console/design.md

Context

skill-catalog-subscription (archived) shipped the consumption side of Skills: a read-only synced catalog (storage/skill_catalog.py), MCP discovery tools (api/skill_catalog_mcp.py), and a transport-replaceable sync client (api/skill_sync.py) that assumed an external "Subscription Platform" as the skill source. Three gaps remain:

1. No source. The external Subscription Platform was never built; SkillSyncRunner is not wired into any running app, so tasks/skills.sqlite3 is empty and list_skills/search_skills/get_skill return nothing at runtime.
2. No management surface. There is no human-facing way to author or manage skills, and no local-authoring path.
3. No local agency. An agent cannot create skills for itself or adapt a cloud skill to its own context.

This change closes all three by introducing a cloud-side management surface (this project's Cloud API becomes the skill source, replacing the assumed external platform) and a local-authoring + override path on the agent. Skills split into two pools — cloud-origin (human-managed via Cloud Console) and local (agent-managed via MCP tools) — that never write into each other's store, with a local override layer that lets an agent shadow a cloud skill.

This builds on apex-agent-mvp (MCP server / agent runtime), database-llm-provider-management (the Cloud DB + admin-surface pattern mirrored here), and the archived skill-catalog-subscription / skill-authoring capabilities.

Goals / Non-Goals

Goals:

• Cloud Console + Cloud API for humans to author/manage cloud-origin skills and assign them to hosts.
• Agent MCP authoring tools for the LLM to create/edit/delete its own local skills, and to override a cloud skill locally.
• A unified read surface (list_skills/search_skills/get_skill) that merges cloud-synced and local skills with an origin discriminator.
• Local override of cloud skills (shadow semantics), with a defined lifecycle against sync updates and entitlement revocation.
• Make the Skill capability usable end-to-end without an external platform: wire SkillSyncRunner into the running host agent, repointing sync at this project's Cloud API.
• Per-host visibility of an agent's local skills in the Console (read-only inventory).

Non-Goals:

• The external Subscription Platform (its billing/marketplace/authoring workflow). This project's Cloud API is the source instead.
• LLM-driven automatic skill generation.
• A human UI for authoring an agent's local skills (local authoring is LLM-via-MCP only).
• Push/webhook-triggered sync (deferred; pull is baseline — see D3).
• Batch/server-side flow execution (unchanged from skill-mcp-tools D5).

Decisions

D1: Cloud skill store reuses the Cloud platform DB (SQLAlchemy + Alembic)

Cloud-origin skills are administrator-managed configuration/content data, directly analogous to LLM Provider profiles. They live in the existing Cloud platform database via new SQLAlchemy models + an Alembic migration, reusing the established repository / admin-scope / CSRF / audit machinery (mirroring cloud/llm_providers.py + migration 0007). No separate store.

D2: Per-host entitlement

A cloud skill is visible to an agent only if it is explicitly entitled to that agent's host. New cloud tables: cloud_skills (the skill rows) and cloud_skill_entitlements (a skill_id × host_id mapping). The Console manages both skill CRUD and entitlement assignment. An agent syncs only its own host's entitled set. There is no global visibility and no tenant/group abstraction in this change.

D3: Incremental pull-only sync

The agent periodically pulls an incremental delta of its host's entitled skills from the Cloud API. The Cloud maintains a monotonic per-host entitlement_version that bumps on any change to that host's entitled set (skill added/removed/edited, entitlement granted/revoked). The agent sends since_version; the Cloud returns upserted skills, removed_ids, and the new latest_version. Full-replace is used on first sync (since_version absent) or when the Cloud cannot serve an incremental delta (version too old). The existing SubscriptionClient Protocol / SyncDelta shape already supports this; only the concrete HTTP client and endpoint change. Push/webhook is deferred — correctness never depends on it.

D4: Local skills persist to a dedicated SQLite file

The agent's local skills (authored + overrides) persist in a new file tasks/local_skills.sqlite3, physically separate from the synced tasks/skills.sqlite3 and from tasks/tasks.sqlite3. This preserves the archived "no cross-writes / physical separation" boundary from skill-authoring / skill-catalog-subscription D6-D7. The existing in-memory skills_learning.SkillStore (used by local-synthesis/embedding subsystems) is not the home for managed local skills; a new persistent local-skill store is introduced (see Layering). The existing Skill/FlowTemplateSkill/KnowledgeSkill domain models are reused verbatim; the SkillMetadata.source field discriminates local skills (source = "local") from synced ones.

D5: Origin discriminator is a simple read-surface field

The merged read surface reports each skill with origin: "cloud" | "local", derived from which store it came from (not stored redundantly). No entitlement/billing/cloud-management internals are exposed to the LLM. Overrides add a locally_overridden: true flag (see D11). This is the only provenance information the LLM receives.

D6: No authoring guard

The authoring MCP tools (create_skill, update_skill, delete_skill) are always registered on the agent's MCP server; there is no enable/disable config gate. The blast radius is already limited to the agent's own local store (cloud skills cannot be mutated directly — see D10), so an operator switch is not warranted for this change.

D7: Agent reports its local skill inventory up to the Cloud (read-only)

The agent periodically reports a read-only summary of its local skills (authored + active overrides) to the Cloud API, so the Console can display per-host local skills. This is a new agent→Cloud reverse channel (a host-scoped POST carrying local skill metadata, no secrets/content beyond what is already non-sensitive). The Console renders it per host. Reporting is best-effort: a failed report does not affect local operation.

D8: Override always shadows

A local override for a cloud skill id takes precedence at read time for as long as it exists. When the underlying cloud skill updates via sync, the override continues to shadow the new cloud version — the agent does not see the cloud update until the override is removed. This is simple and predictable; staleness is the operator/agent's responsibility. (Version-staleness flagging and auto-invalidation were considered and rejected for MVP complexity.)

D9: Override forks into a standalone local skill on entitlement revocation

If a cloud skill is removed from the agent's entitled set (sync delivers it in removed_ids) and a local override exists for it, the override is promoted to a standalone local skill: it gets a local id, origin becomes "local", and it survives independently of the (now-absent) cloud skill. The agent keeps its customized version rather than losing it. If no override exists, revocation simply removes the cloud skill from the local view as before.

D10: Authoring tools dispatch by origin (no dedicated override tool)

• create_skill(...) → creates a new local skill (fresh local id).
• update_skill(skill_id, ...):
  • skill_id is a local skill → edits it in the local store.
  • skill_id is a cloud skill → creates/updates the local override for that cloud id (never writes to the cloud store or the synced store).
• delete_skill(skill_id):
  • skill_id is a local skill → deletes it.
  • skill_id is a cloud skill with an active override → removes the override (the cloud skill resurfaces at its next read).
  • skill_id is a cloud skill with no override → semantic error (nothing local to delete; the agent cannot revoke a cloud entitlement from here).

Dispatch is by origin lookup, not by an id-prefix convention. A dedicated override_skill tool was considered and rejected in favour of fewer tools with origin-based dispatch.

D11: Origin reporting for overrides

• Cloud skill, no override: origin = "cloud", no flag.
• Cloud skill with an active override: origin = "cloud", locally_overridden = true (provenance is still cloud; the flag says it is shadowed).
• After a revocation fork (D9): origin = "local" (it has detached from the cloud identity).
• Authored local skill: origin = "local".

Architecture / Layering

Per docs/CONSTITUTION.md (HTTP/MCP enter at api; no LLM/HTTP/MCP in core/driver/device/tools; dependency direction core → driver/device → tools → perception → storage → runtime → api):

Concern	Location (new/extended)	Layer	Key deps
Cloud skill domain + service	packages/cloud-platform/cloud/skills.py (new)	cloud service	dataclasses, validation, cloud.provider_secrets only if secrets ever needed (none here)
Cloud SQLAlchemy models	packages/cloud-platform/cloud/db_models.py (extend)	cloud storage	SQLAlchemy
Cloud repository methods	packages/cloud-platform/cloud/sql_repository.py (extend)	cloud storage	SQLAlchemy, cloud.skills
Cloud Alembic migration	cloud/migrations/versions/0010_skill_management.py (new)	cloud storage	Alembic
Cloud admin REST (skill CRUD + entitlement)	cloud/internal_api/api.py + new admin router (extend)	cloud api	FastAPI, cloud.skills, auth/CSRF/scope
Cloud host-scoped sync endpoint + inventory-report endpoint	cloud/internal_api/api.py (extend)	cloud api	FastAPI, host-scoped bearer auth (same as planner-decision)
Persistent local-skill store (authored + overrides)	storage/local_skills.py (new)	storage	sqlite3, skills_learning.models — zero HTTP/MCP
Unified read/merge + origin + override resolution	api/skill_catalog_view.py (new)	api	storage.skill_catalog, storage.local_skills
Skill MCP tools (read merge + authoring dispatch)	api/skill_catalog_mcp.py (extend)	api	api.skill_catalog_view, FastMCP
Sync concrete client repoint + runner wiring	api/skill_sync.py (extend) + host-agent app bootstrap	api / runtime	httpx, storage.skill_catalog
Console view + API client + types	cloud-console/src/views/SkillsView.vue, cloud-console/src/api-equiv, cloud-console/src/types.ts (extend)	frontend	Vue, existing admin-auth/CSRF client

storage/skill_catalog.py (the synced store) is unchanged in its read-only-except-sync contract; it continues to receive only sync writes. Local authored skills and overrides live exclusively in storage/local_skills.py → tasks/local_skills.sqlite3. The merge happens in api/skill_catalog_view.py, the only module that reads both.

Override Model (detail)

• Overrides are stored in the local store keyed by the cloud skill id they shadow.
• Read merge order, per id:
  1. If a local override exists for the id → return the override payload, origin="cloud", locally_overridden=true.
  2. Else if the synced store has the id (and it is visible) → return it, origin="cloud".
  3. Else if the local store has the id as a standalone local skill → return it, origin="local".
  4. Else → not found (no existence leak between stores).
• update_skill(cloud_id) upserts the override; delete_skill(cloud_id) removes it (cloud skill resurfaces on next read).
• Fork-on-revocation (D9): when sync removes a cloud id that has an override, the override row is rewritten to a standalone local skill (new local id, source="local", content preserved), and the old cloud-id key is dropped. Subsequent reads see it as origin="local".

Migration Plan

Additive across existing packages; no new top-level package.

• Cloud: new Alembic migration 0010_skill_management.py adds cloud_skills, cloud_skill_entitlements, and a per-host cloud_skill_sync_state (host_id, last_version, updated_at) table. No existing table is altered. New admin scope skills:admin (mirrors llm-providers:admin).
• Agent: new tasks/local_skills.sqlite3 created lazily by storage/local_skills.py. storage/skill_catalog.py is untouched. api/skill_catalog_view.py + extended api/skill_catalog_mcp.py add the merge + authoring surface. api/skill_sync.py's concrete client is repointed at the Cloud API; SkillSyncRunner is constructed and started in the host-agent app bootstrap (behind the existing cloud-transport configuration).
• Rollback: drop the cloud migration's tables; delete tasks/local_skills.sqlite3; remove the new storage/local_skills.py, api/skill_catalog_view.py, the authoring tool registrations, and the Console view. The synced store and original read tools revert to their archived behaviour (empty until an external source exists).

Risks / Trade-offs

• [Risk] Sync staleness under overrides (D8): an override masks cloud updates indefinitely. → Mitigation: explicit, documented; the Console's per-host inventory (D7) surfaces active overrides so an operator can see what is shadowed.
• [Risk] Fork-on-revocation (D9) can let an agent keep a customized copy of a skill the operator tried to revoke. → Mitigation: the fork contains only what the agent already had (no new content); revocation still removes the cloud entitlement. Accepted trade-off: local agency over strict central control. The Console inventory makes forks visible.
• [Risk] Per-host entitlement + incremental versioning adds cloud-side bookkeeping (the entitlement_version must bump correctly on every relevant change). → Mitigation: centralize the bump in the service layer (cloud/skills.py) behind the repository port; cover with repository/service tests.
• [Trade-off] No authoring guard (D6) means an agent can fill its local store freely. Accepted: blast radius is local-only and the store is per-agent.
• [Trade-off] Reusing SkillMetadata.source for origin keeps the domain model unchanged but means origin is inferred at the merge layer rather than stored as a first-class field. Accepted: avoids model divergence between synced and local skills.
• [Risk] Inventory reporting (D7) is a new agent→Cloud channel that could leak local-skill metadata upstream. → Mitigation: report metadata only (id/name/kind/origin/overridden-cloud-id/version/timestamps), never secrets; the agent already trusts the Cloud API as its sync source.

Open Questions

• Exact Cloud sync endpoint path and whether inventory report rides on the same host-scoped auth as the planner-decision endpoint (likely yes).
• Whether flow-template tool-reference validation (already applied to synced skills) should also apply to locally-authored/override skills at author time vs read time (lean: validate at get_skill/resolve_flow_template time uniformly, warn — not block — at author time).
• Console UX for entitlement assignment (per-skill host picker vs per-host skill picker) — a UI detail, resolved during Console implementation.