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

1. Package scaffolding & data model

• 1.1 Create skills/ package (__init__.py) alongside existing core/, tools/, vision/, runtime/, api/, storage/
• 1.2 Add skills/models.py: SkillMetadata (id, name, description, version, tags, source/subscription id, updated_at), KnowledgeSkill (content), FlowTemplateSkill (steps, parameters), and a kind discriminator uniting them
• 1.3 Add dependencies if needed (HTTP client for sync, no new heavy deps expected) to pyproject.toml

2. Skill Catalog storage & query (capability: skill-catalog)

• 2.1 Implement skills/catalog.py local store (decide SQLite table(s) reusing the existing DB vs. separate file, per design's open question) with create/update/remove operations used only by the sync path
• 2.2 Implement list_skills(caller_context) returning only skills visible under the caller's active subscriptions, stable-sorted
• 2.3 Implement search_skills(query, caller_context) matching name/tags/description
• 2.4 Implement get_skill(skill_id, caller_context) returning full content, or a clear "not found" for unknown/invisible ids
• 2.5 Reject/ignore any direct create-or-edit call to the catalog that didn't come from the sync path (enforce "Subscription Platform is sole source of truth")
• 2.6 Implement flow-template tool-reference validation: check each step's tool name against the currently registered device-capability tools; mark skill invalid/unavailable if any reference is dangling
• 2.7 Write unit tests: list/search/get visibility filtering, not-found cases, and flow-template validation (valid and dangling-reference cases)

3. Subscription sync client (capability: skill-subscription-sync)

• 3.1 Define the internal sync interface (e.g. SubscriptionClient.fetch_entitled_skills(subscription_id, since_version) supporting full or incremental fetch) in skills/sync_client.py
• 3.2 Implement a concrete HTTP-based SubscriptionClient against the assumed Subscription Platform API (configurable base URL/auth), isolated behind the interface from 3.1
• 3.3 Implement the poll loop: fetch on a configurable interval, diff against local catalog, and apply create/update/remove to skills/catalog.py
• 3.4 Implement optional push-triggered sync: a receiver (e.g. a small webhook endpoint) that, on notification, triggers an immediate out-of-cycle pull rather than being required for correctness
• 3.5 Implement subscription-based visibility enforcement at query time (re-check active subscription set, not just last-sync membership) so revoked entitlements stop being visible without waiting for the next full sync
• 3.6 Implement sync failure handling: on network/auth/malformed-response errors, leave the local catalog unchanged and record a last-error timestamp/reason for observability
• 3.7 Write unit tests: create/update/remove sync scenarios, push-triggered immediate sync, query-time revocation re-check, and sync-failure-preserves-cache behavior (using a fake SubscriptionClient)

4. Skill MCP tools (capability: skill-mcp-tools)

• 4.1 Implement skills/mcp_tools.py registering list_skills, search_skills, get_skill as MCP tools on the existing MCP server surface from apex-agent-mvp (or a standalone MCP server instance if that change is not yet applied)
• 4.2 Implement the flow-template parameter-resolution MCP tool: validate provided values against a skill's parameters schema and return the fully substituted step sequence, or a clear validation error listing missing/invalid parameters
• 4.3 Add semantic error translation for skill MCP tools (not-found, not-visible/entitled, invalid/unavailable flow template) consistent in style with the device-capability tool error handling
• 4.4 Confirm no MCP tool exists that both resolves and executes a flow-template skill's steps server-side (execution stays with the LLM issuing existing device-capability tool calls one at a time)
• 4.5 Write tests: list_skills/search_skills/get_skill via MCP against a seeded catalog (mocked sync), parameter-resolution success/failure cases, and an explicit check that no batch-execute tool is registered

5. End-to-end validation

• 5.1 Seed a local catalog via a fake SubscriptionClient with one knowledge skill and one flow-template skill, and verify both are listable/searchable/fetchable via MCP tools
• 5.2 Simulate an entitlement revocation (remove a skill from the fake client's entitled set) and confirm it disappears from list_skills/get_skill after both a sync cycle and, separately, via the query-time re-check before the next sync completes
• 5.3 Resolve a flow-template skill's parameters via MCP, then manually drive the resulting step sequence through the existing apex-agent-mvp device-capability tools against a mocked device, confirming each step still goes through the normal Observe-Think-Act loop