agentic-mobile-control/openspec/changes/skill-catalog-subscription/proposal.md

Why

Apex Agent's MCP tool server (see change apex-agent-mvp) gives the LLM raw device capabilities (tap/swipe/screenshot/...), but it has no notion of reusable, task-specific know-how — e.g. "how to search on Xiaohongshu," or "the tap/swipe/input sequence to place an order on Taobao." Today that knowledge would have to live entirely inside the LLM's own reasoning or be re-derived from scratch on every task. We need a Skill concept the AI can discover and pull on demand via MCP, and — since skill content will be authored, versioned, and entitled to specific tenants/devices by a separate, already-planned Subscription Platform (统一订阅平台，另一套信息管理系统) — Apex Agent needs a defined contract for consuming that platform's catalog rather than owning skill authoring itself.

What Changes

• Introduce a Skill Catalog capability: a local data model and store for Skills, where a Skill is either a knowledge skill (structured instructional/markdown content the AI reads to decide how to act, analogous to Claude Skills) or a flow-template skill (a parameterized, predefined sequence of capability calls — e.g. tap/swipe/input steps with placeholders — that the AI mostly fills in parameters for and triggers, rather than re-planning from scratch). Both kinds share common metadata (id, name, description, version, tags) so they can be listed/searched uniformly.
• Introduce Skill MCP tools (list_skills, search_skills, get_skill, run_skill_flow-input-resolution helper) exposed through the same MCP surface established in apex-agent-mvp's mcp-tool-server, so an LLM can discover which skills are available and fetch their content/flow template without knowing anything about the Subscription Platform underneath.
• Introduce a Skill Subscription Sync capability: a client-side contract for talking to the external Subscription Platform, covering (a) pulling/receiving the catalog of skills a given deployment is entitled to, (b) keeping the local Skill Catalog in sync (create/update/remove on change), and (c) enforcing subscription-based visibility so only skills the current tenant/device/agent is subscribed to are listed or fetchable via the MCP tools.
• Explicitly out of scope for this change: designing or building the Subscription Platform itself (authoring UI, billing, skill publishing workflow) — it is treated as an existing/external system; this change only defines the integration contract (API shape, sync semantics, auth) Apex Agent needs from it. Also out of scope: automatic skill-authoring/generation by the LLM, and a skill marketplace UI.

Capabilities

New Capabilities

• skill-catalog: Local Skill data model (knowledge-doc and flow-template variants), storage, and search/query functions used by both the MCP tools and the sync client.
• skill-mcp-tools: MCP-facing tool surface for listing, searching, and fetching Skill content/flow templates, plus resolving flow-template parameters, without exposing any Subscription Platform or storage detail to the LLM.
• skill-subscription-sync: Contract and client implementation for syncing the Skill Catalog from the external Subscription Platform (pull and/or push), and for enforcing subscription-based visibility/permission scoping per tenant/device/agent.

Modified Capabilities

(none — mcp-tool-server from the pending apex-agent-mvp change is composed with, not modified: this change adds new tools to the same MCP server process rather than changing that capability's existing requirements. If apex-agent-mvp has not yet been applied when this change is implemented, the Skill MCP tools should still be registrable on their own MCP server instance and merged in later.)

Impact

• New code: extends existing packages rather than adding a new one. Adds KnowledgeSkill to skills_learning/models.py (reusing the already-shipped SkillKind/SkillMetadata/FlowStep/Skill/FlowTemplateSkill); new storage/skill_catalog.py (synced-skill local store + query); new api/skill_sync.py (Subscription Platform HTTP client, poll loop, optional webhook receiver); new api/skill_catalog_mcp.py (registers list_skills/search_skills/get_skill/resolve_flow_template as MCP tools, wrapping the existing workflow/skill_exec.resolve_skill_steps); one-line wire-up in api/mcp.py:create_mcp_server.
• Dependencies: reuses the already-shipped domain models from skills_learning/ (archived skill-learning-runtime change) and the parameter-resolution logic from workflow/skill_exec.py. Depends on the apex-agent-mvp MCP server surface for tool registration. No new external dependency beyond httpx (already in pyproject.toml) for the sync API.
• External systems: introduces a new external dependency — the Subscription Platform's API (assumed to expose an endpoint to fetch entitled skills and, optionally, a webhook/push channel for change notifications). Exact base URL/auth mechanism is a deployment-time configuration, not a code dependency.
• Storage: adds a new local Skill Catalog store as a physically separate SQLite file tasks/skills.sqlite3 (owned by storage/skill_catalog.py), distinct from tasks/tasks.sqlite3 (task metadata) and the in-memory skills_learning.SkillStore. This preserves the archived skill-authoring spec's contract that locally-synthesized and externally-synced skills never share storage. A small sync-state table (last-synced version/timestamp/error per subscription) lives in the same file.
• Follow-on work explicitly deferred: Subscription Platform's own design/build, skill-authoring workflows, billing/entitlement logic beyond "is this skill visible to me," and any LLM-driven automatic skill generation.