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: skills/ package — skills/models.py (Skill, KnowledgeSkill, FlowTemplateSkill, SkillMetadata), skills/catalog.py (local store + search/query), skills/sync_client.py (Subscription Platform client: pull/push, auth, visibility filtering), skills/mcp_tools.py (registers list_skills/search_skills/get_skill/flow-param-resolution as MCP tools).
• Dependencies: depends on the apex-agent-mvp change for the MCP server process and tools//runtime/ capability layer that flow-template skills ultimately drive (a flow-template skill's steps still execute through existing tools/ functions); does not depend on any new external dependency beyond an HTTP client 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 local Skill Catalog store (SQLite table(s) alongside the existing task-metadata DB from apex-agent-mvp, or an embedded file-based store — to be decided in design) plus a small sync-state table (last-synced version/timestamp per subscription).
• 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.