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

Why

The skill-catalog-subscription change shipped the consumption side of Skills (local read-only catalog, MCP discovery tools, sync-client contract), but assumed an external "Subscription Platform" (统一订阅平台) as the skill source — a system that does not exist. With no source feeding the catalog and no sync runner wired into any running app, list_skills/search_skills/get_skill are registered but return empty at runtime, and an operator has no way to author or manage skills. We need both a cloud-side management surface (so humans can author the skills agents consume) and a local-authoring path (so an agent can create skills for itself) before the Skill capability is usable end-to-end — without waiting on an external platform.

What Changes

Skills are split into two pools with separate management entry points that never cross each other:

• Cloud-origin skills — authored and managed by humans through a new Cloud Console management surface (UI + Cloud API REST + a cloud-side skill store). This cloud store becomes the source agents sync from, replacing the previously-assumed external Subscription Platform.
• Local skills — authored and managed by the agent's LLM through new authoring MCP tools, living in a dedicated persistent local store (a new file tasks/local_skills.sqlite3, physically separate from the synced catalog store and from the in-memory local-synthesis store). The agent can read both pools but writes only to its own local pool: it cannot mutate a cloud skill directly. It may, however, create a local override that shadows a cloud skill (see below).

Specifically:

• Add a Cloud Console management surface for cloud-origin skills: list/view, create, edit, and delete cloud skills, plus visibility into which agents/tenants are entitled to which skills. Backed by a new cloud-side skill store and Cloud API REST endpoints.
• Add authoring MCP tools (create_skill / update_skill / delete_skill) on the agent's MCP server that dispatch by origin: editing/deleting local skills, and creating/updating/removing local overrides for cloud skills (never writing to the cloud or synced store). Authoring errors are surfaced as semantic MCP errors consistent with the existing read tools.
• Add local override of cloud skills: a local override shadows a cloud skill at read time, wins against sync updates until removed, and forks into a standalone local skill if the cloud entitlement is revoked.
• Make the existing MCP read tools (list_skills / search_skills / get_skill) present a unified catalog by merging cloud-synced skills (read-only, after overrides) and local skills, so a single discovery surface serves both pools. Each skill carries an origin discriminator (cloud | local) and overrides are flagged.
• Repoint the sync source: the agent's skill-subscription-sync now pulls incremental per-host deltas from this project's own Cloud API skill store, rather than an assumed external platform, and the sync runner is wired into the running host agent. The sync capability's transport-replaceable contract is preserved — only the concrete upstream changes.
• Have the agent report its local-skill inventory up to the Cloud (read-only) so the Console can show per-host local skills.
• Persist local skills across agent restarts in the dedicated local store.

Capabilities

New Capabilities

• skill-management-console: Cloud-side management of cloud-origin skills — the Cloud Console UI, the Cloud API REST endpoints for skill CRUD and per-host entitlement, the versioned host-scoped sync endpoint agents pull from, the agent local-skill inventory readback, and the cloud-side skill store. This is the human-facing authoring and management entry point and the authoritative source for cloud skills.
• local-skill-management: Agent-side management of the agent's own local skills — a persistent local skill store (separate from the synced catalog store), local authoring semantics (create/update/delete), the local override model (shadow a cloud skill; fork to a standalone local skill on entitlement revocation), and the origin-discriminated read-merge over synced + local skills. The synced catalog store's read-only-except-sync invariant and the physical separation between local and synced stores remain intact.

Modified Capabilities

• skill-mcp-tools: (a) the existing read tools present a unified catalog merged from cloud-synced and local skills with an origin discriminator (delegating to local-skill-management's merge); (b) new create_skill / update_skill / delete_skill authoring tools are added that dispatch by origin — editing/deleting local skills, and creating/updating/removing local overrides for cloud skills (never writing to the cloud or synced store).
• skill-subscription-sync: the concrete sync upstream is this project's Cloud API skill store (incremental per-host pull), not an external Subscription Platform; the runner is wired into the running host agent; and the agent reports its local-skill inventory up to the Cloud. The transport-replaceable interface contract is preserved.

(skill-catalog, which governs the synced store, is unchanged: local skills live in the separate store introduced by local-skill-management, and the merge happens above it. No delta is needed for skill-catalog.)

Impact

• New code (cloud-side): a cloud-side skill store + schema/migration, Cloud API REST endpoints + handlers for cloud-skill CRUD and entitlement readback, audit/CSRF/scope guards consistent with the existing llm-providers:admin-style admin surface, and a Cloud Console view + API client (cloud-console/src/views, API layer).
• New code (agent-side): authoring MCP tool registrations in api/skill_catalog_mcp.py; a merge layer so the read tools query both storage/skill_catalog.py (synced) and skills_learning/store.py (local); persistence for skills_learning/store.py (currently in-memory).
• Existing code: storage/skill_catalog.py query surface, api/skill_sync.py's concrete client (repointed to Cloud API), and the skills_learning store.
• Capabilities: new skill-management-console and local-skill-management; modified skill-mcp-tools and skill-subscription-sync. skill-catalog (synced store) is unchanged.
• Open design questions (design.md): exact shape of the cloud-side skill store and its entitlement model; whether local-skill persistence reuses a SQLite file alongside tasks/skills.sqlite3 or extends skills_learning/store.py; how origin is discriminated and surfaced to the LLM without leaking cloud-management internals; whether the cloud console also offers a read-only view of an individual agent's local skills (likely out of scope).
• Still out of scope: billing/marketplace, LLM-driven automatic skill generation, and a human UI for authoring an agent's local skills (local authoring is LLM-via-MCP only).