q792602257andClaude Opus 4.6
dd03abbbb0
Opens the skill-management-console openspec change (cloud/local skill split with local override) with proposal, design (D1-D11), four delta specs, and tasks. Implements the agent-side persistent local skill store (storage/local_skills.py): authored local skills + cloud-skill overrides in a physically separate SQLite file, with fork-on-revocation. 10 tests pass. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
41 lines
6.9 KiB
Markdown
41 lines
6.9 KiB
Markdown
## 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).
|