## 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).