@wowok/skills 3.0.3 → 3.1.0

package/wowok-arbitrator/SKILL.md

@@ -1,17 +1,10 @@
 ---
 name: wowok-arbitrator
-description: |
-  WoWok Arbitrator — build and operate on-chain arbitration services.
-  Create Arbitration objects, configure voting rules (open or guard-based weighted),
-  manage dispute cases through their full lifecycle, and earn fees from resolution.
-
-  Core value: achieve trust consensus between merchants and users through
-  transparent, fair, and efficient dispute resolution.
-when_to_use:
-  - User wants to create/configure an Arbitration service
-  - User needs to handle dispute cases and voting processes
-  - User wants to design voter eligibility and weight mechanisms
-  - User mentions "arbitration", "dispute", "voting", "arb", "judge"
+description: "WoWok Arbitrator — build and operate on-chain arbitration services. Create Arbitration objects, configure voting rules (open or guard-based weighted), manage dispute cases through their full lifecycle, and earn fees from resolution. Core value: achieve trust consensus between merchants and users through transparent, fair, and efficient dispute resolution. Use when: User wants to create/configure an Arbitration service; User needs to handle dispute cases and voting processes; User wants to design voter eligibility and weight mechanisms; User mentions \"arbitration\", \"dispute\", \"voting\", \"arb\", \"judge\"."
+metadata:
+  version: "2.0.0"
+  role: arbitrator
+  related: "wowok-order, wowok-messenger"
 ---
 
 # WoWok Arbitrator Guide

package/wowok-auditor/SKILL.md

@@ -1,22 +1,10 @@
 ---
 name: wowok-auditor
-description: |
-  WoWok pre-publish auditor — the static-analysis Skill that verifies
-  Guard completeness, Machine soundness, fund-flow safety, permission
-  consistency, and publish readiness BEFORE any irreversible publish
-  operation (Service publish, Machine publish, Allocator binding freeze).
-
-  This Skill is the knowledge base for the L4 Harness Verify Loop. It does
-  not mutate objects. It queries, exports, and rules — emitting a
-  pass/warn/fail audit report plus a publish decision.
-when_to_use:
-  - User is about to publish a Service, Machine, or lock an Allocator set
-  - User asks to "audit", "verify", "review", "check before publish"
-  - L4 Harness Verify Loop is invoked before an irreversible operation
-  - User mentions "fund flow", "refund path", "allocation sum", "guard completeness"
-  - User mentions "machine cycle", "unreachable state", "permission index conflict"
-  - User wants a pre-publish go/no-go decision
-  - A publish operation failed and root-cause analysis is needed
+description: "WoWok pre-publish auditor — the static-analysis Skill that verifies Guard completeness, Machine soundness, fund-flow safety, permission consistency, and publish readiness BEFORE any irreversible publish operation (Service publish, Machine publish, Allocator binding freeze). This Skill is the knowledge base for the L4 Harness Verify Loop. It does not mutate objects. It queries, exports, and rules — emitting a pass/warn/fail audit report plus a publish decision. Use when: User is about to publish a Service, Machine, or lock an Allocator set; User asks to \"audit\", \"verify\", \"review\", \"check before publish\"; L4 Harness Verify Loop is invoked before an irreversible operation; User mentions \"fund flow\", \"refund path\", \"allocation sum\", \"guard completeness\"; User mentions \"machine cycle\", \"unreachable state\", \"permission index conflict\"; User wants a pre-publish go/no-go decision; A publish operation failed and root-cause analysis is needed."
+metadata:
+  version: "2.0.0"
+  role: shared
+  related: "wowok-planner, wowok-provider, wowok-machine"
 ---
 
 # WoWok Pre-Publish Auditor

package/wowok-collaborator/SKILL.md

@@ -1,22 +1,10 @@
 ---
 name: wowok-collaborator
-description: |
-  WoWok Collaborator — the canonical skill for process collaborators who execute
-  workflow forwards on behalf of a merchant: internal staff (permission entities)
-  and external operators (named operators).
-
-  Covers permission-index and named-operator routing, guard-gated evidence
-  submission, and reputation protection. The collaborator carries PROCESS
-  responsibility (no direct settlement stake) — the goal is to keep the workflow
-  flowing and avoid stall blame.
-
-  For the merchant who owns the Service, see wowok-provider. For the supplier who
-  presents to Demands, see wowok-supplier.
-when_to_use:
-  - User is an operator/employee executing workflow steps (permission index)
-  - User is an external named operator advancing a Machine forward
-  - User wants to submit guard evidence (proof/repository) for a forward
-  - User mentions "collaborator", "operator", "permission index", "named operator", "execute forward"
+description: "WoWok Collaborator — the canonical skill for process collaborators who execute workflow forwards on behalf of a merchant: internal staff (permission entities) and external operators (named operators). Covers permission-index and named-operator routing, guard-gated evidence submission, and reputation protection. The collaborator carries PROCESS responsibility (no direct settlement stake) — the goal is to keep the workflow flowing and avoid stall blame. For the merchant who owns the Service, see wowok-provider. For the supplier who presents to Demands, see wowok-supplier. Use when: User is an operator/employee executing workflow steps (permission index); User is an external named operator advancing a Machine forward; User wants to submit guard evidence (proof/repository) for a forward; User mentions \"collaborator\", \"operator\", \"permission index\", \"named operator\", \"execute forward\"."
+metadata:
+  version: "2.0.0"
+  role: collaborator
+  related: "wowok-provider, wowok-machine, wowok-messenger"
 ---
 
 # WoWok Collaborator Guide

package/wowok-governance/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: wowok-governance
+description: "WoWok Governance — the canonical skill for on-chain permission, data, and financial governance: the account that OWNS the objects keeps them healthy after setup. Covers Permission lifecycle (indexes, role assignment, entity table, admin transfer), Treasury/Allocation fund stewardship (deposit/withdraw, history audit, unclaimed payments), and Personal data boundaries (public identity, profile records). Governance is a continuous loop — inventory, decide, execute, audit — not a one-time setup. For building services, see wowok-provider. For market operations, see wowok-market. Use when: User wants to manage who can operate their objects (permission indexes, entity table); User wants to deposit/withdraw treasury funds or audit fund history; User has unclaimed payments or wants to check claimable balances; User wants to update their public on-chain profile or personal data; User mentions \"permission\", \"treasury\", \"governance\", \"manage assets\", \"audit funds\"."
+metadata:
+  version: "1.0.0"
+  role: shared
+  related: "wowok-provider, wowok-market, wowok-messenger"
+---
+
+# WoWok Governance Guide
+
+> **Role**: Object owner/admin — the account that carries administrative responsibility for Permission, Treasury, and Personal objects
+> **Related Skills**: [wowok-provider](../wowok-provider/SKILL.md) (service build), [wowok-market](../wowok-market/SKILL.md) (market ops), [wowok-messenger](../wowok-messenger/SKILL.md) (contact)
+
+---
+
+## MCP Knowledge Layer
+
+The following content has been pushed down to the MCP knowledge layer and is applied automatically — this Skill does NOT duplicate it:
+
+| Content | Access via (MCP action) | Applied Via |
+|---------|--------------------------|-------------|
+| Permission safety rules (owner/admin/entity hierarchy) | `schema_query` action='get_safety_rules' | `onchain_operations` permission |
+| Treasury/Permission/Personal object schema | `schema_query` action='get_schema' | governance operations |
+| Unclaimed-payment detection | `keeper_operation` (payment_unclaimed scan) | monitor loop |
+| Fund-flow event meanings (TreasuryEvent / AllocationEvent / RewardClaimEvent / RewardFundEvent) | event semantic registry | audit & monitor |
+
+This Skill keeps the governance **conversation flow** — what to inventory, what to decide, what to execute, and how to audit.
+
+---
+
+## Governance Is a Loop, Not a Setup
+
+Inventory → Decide → Execute → Audit. Governance objects are LIVE: a permission change takes effect on the next call, a withdraw is irreversible, a personal profile record is permanently public. Every change deserves an audit pass after execution.
+
+---
+
+## Domain 1: Permission Governance
+
+A Permission object defines WHO can perform WHICH operations on your business objects (Service / Machine / Treasury …).
+
+- **Indexes** (`permission.index_create`): create named role indexes (e.g. operator=1, finance=2) before assigning.
+- **Role assignment** (`permission.role_assign`): bind indexes onto target objects — a mis-assigned role grants unintended operational authority immediately.
+- **Entity table**: add/remove addresses per index. Review-first: list current entities before mutating (`query_objects` on the Permission object).
+- **Audit**: `query_toolkit` query_type='onchain_table_item_permission_perm' checks what a specific address may do; query_type='address_profile' shows an address's permission memberships across all objects.
+
+Rules of thumb:
+- One Permission per business object family; reuse named indexes, don't proliferate unnamed ones.
+- Removing an entity is immediate — the next operation by that address fails with "Permission denied" (abort code 5).
+- Admin transfer is a high-trust operation: the new admin controls the whole table.
+
+---
+
+## Domain 2: Financial Governance
+
+Fund stewardship across Treasury / Allocation / Reward / Payment.
+
+- **Treasury**: deposit joins coins in (a Payment receipt is minted); withdraw splits balance out — irreversible, and when an `external_guard` is set the guard must validate first. `query_toolkit` query_type='onchain_table_item_treasury_history' audits every flow (op 0 Withdraw / 1 Deposit / 2 Receive) with amount + guard + timestamp.
+- **Allocation**: runs distribute pool funds per sharing mode (Amount / Rate ‰ / Surplus). Review allocator guards periodically — a stale guard blocks legitimate distributions.
+- **Unclaimed payments**: recipients hold frozen CoinWrappers until they unwrap. The keeper `payment_unclaimed` scan owns this reminder surface — run `keeper_operation` to list claimable payments and nudge recipients via Messenger. NewPaymentEvent is deliberately NOT push-bridged, to avoid duplicate reminders (P2-4 channel split).
+- **Reward pools**: RewardFundEvent in / RewardClaimEvent out; a dry pool blocks claims — watch balances before announcing campaigns.
+
+---
+
+## Domain 3: Data Governance
+
+- **Personal profile** (`personal` operations): your public on-chain identity. Everything here is PERMANENTLY PUBLIC — never anchor private data. Review-first: show the current record before every mutation.
+- **Entity info**: description/info updates re-emit NewEntityEvent — counterparties' cached profiles refresh; keep descriptions accurate.
+- **Repository data**: contribution/usage policies are designed at Repository level (see wowok-provider); governance audits consumption through the event stream.
+
+---
+
+## Monitor Loop
+
+Governance goals close the loop through three channels:
+
+- **Push**: fund-flow events (TreasuryEvent / AllocationEvent / RewardClaimEvent / RewardFundEvent) become goal-bound suggestions via SuggestionBridge.
+- **Pull**: keeper scans (payment_unclaimed, balance thresholds) repeat reminders until resolved.
+- **Audit**: after every governance write, re-query the object and confirm the post-state matches the intent.
+
+---
+
+## Core Interaction Principles
+
+1. **Review-first**: always show current state + the exact delta before executing.
+2. **User-driven**: surface options, never auto-execute — withdraw and admin transfer are irreversible.
+3. **Disclose irreversibility**: say it explicitly for withdraw, admin transfer, and any personal-data write.
+4. **Audit after**: every governance write ends with a re-query confirmation.
+
+## Quick Reference
+
+- Permission: indexes → role assignment → entity table; audit via permission_perm + address_profile.
+- Treasury: deposit/withdraw + history audit; external_guard gates withdrawals.
+- Unclaimed payments: keeper scan owns reminders; recipients unwrap CoinWrappers.
+- Personal data: permanently public — review before every write.

package/wowok-machine/SKILL.md

@@ -1,23 +1,10 @@
 ---
 name: wowok-machine
-description: |
-  WoWok Machine Workflow Design — the canonical skill for designing, building,
-  and operating automated workflow templates (Machines) on WoWok. Machines are
-  directed graphs that define how orders progress through stages, who can
-  advance them, and what conditions must be met at each step.
-
-  Covers Machine architecture (Nodes, Pairs, Forwards, Guards, Thresholds),
-  lifecycle management (create, configure, publish, pause), node operations
-  (add, exchange, rename, granular forward/prior-node manipulation),
-  Progress integration, cross-Machine supply chain composition via Guard verification, privacy-preserving
-  consensus patterns, and export/import workflows via machineNode2file.
-when_to_use:
-  - User wants to create or modify a Machine workflow
-  - User asks about workflow steps, state transitions, or progress
-  - User needs to design order processing pipelines
-  - User mentions "machine", "workflow", "progress", "state machine", "pipeline"
-  - User wants to export Machine nodes to a file or import from a file
-  - User needs to understand threshold mechanics, forward permissions, or guard bindings
+description: "WoWok Machine Workflow Design — design, build and operate workflow templates (Machines): directed graphs that define how orders progress through stages, who can advance them, and what conditions must be met at each step. Covers Nodes/Pairs/Forwards/Guards/Thresholds, lifecycle (create, configure, publish, pause), node and forward operations, Progress integration, cross-Machine supply chains via Guard verification, and machineNode2file import/export. Use when: User wants to create or modify a Machine workflow; User asks about workflow steps, state transitions, or progress; User needs to design order processing pipelines; User mentions \"machine\", \"workflow\", \"progress\", \"state machine\", \"pipeline\"; User wants to export/import Machine nodes via a file; User needs threshold mechanics, forward permissions, or guard bindings."
+metadata:
+  version: "2.0.0"
+  role: provider
+  related: "wowok-provider"
 ---
 
 # WoWok Machine Workflow Design

package/wowok-market/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: wowok-market
+description: "WoWok Market — market discovery and operations (the matchmaking layer): how a demand finds candidate services, how a merchant picks a trustworthy arbitrator, how the account's on-chain attention is surfaced, and how the market is measured and governed. Covers match_discover/discover_services/discover_demands, arbitration_score (trust selection), account_events (attention), market_metrics, anti_cheat, market_operations (journey funnel / referral / CRM) and category match rules. Use when: User wants to discover services for an intent (\"find a plumber in Shanghai\"); Merchant wants to find open Demands to present to; Merchant wants to pick or compare arbitrators; User wants their on-chain attention items surfaced; User wants market metrics, anti-cheat signals, journey funnel, referral or CRM; User mentions \"market\", \"match\", \"discover\", \"matchmaking\", \"funnel\", \"referral\"."
+metadata:
+  version: "1.0.0"
+  role: shared
+  related: "wowok-provider, wowok-order, wowok-arbitrator"
+---
+
+# WoWok Market Guide
+
+> **Role**: Market discovery & operations (matchmaking + Observe layer)
+> **Related Skills**: [wowok-provider](../wowok-provider/SKILL.md) (merchant), [wowok-order](../wowok-order/SKILL.md) (customer), [wowok-arbitrator](../wowok-arbitrator/SKILL.md) (arbitrator), [wowok-supplier](../wowok-supplier/SKILL.md) (demand presenter)
+
+---
+
+## MCP Knowledge Layer
+
+The matching/routing/aggregation logic is pushed down to MCP and applied automatically — this Skill does NOT duplicate it. All market actions live under `evaluation_operation`:
+
+| Capability | MCP action | Purpose |
+|------------|------------|---------|
+| Service discovery (intent → candidates) | `match_discover` / `discover_services` | enumerate + location gate + 6-dim score |
+| Demand discovery (merchant → open demand) | `discover_demands` | enumerate shared Demands |
+| Arbitrator trust selection | `arbitration_score` | dual-perspective trust/fairness |
+| Account attention | `account_events` | unread messenger / collectible / arbitrable |
+| Market metrics | `market_metrics` | supply / demand / trust counts |
+| Anti-cheat | `anti_cheat` | fake order / fake review / shell merchant |
+| Operational aggregation | `market_operations` | journey funnel / referral / CRM |
+
+This Skill keeps the **market conversation flow** — discover → compare → trust → act → measure. The MCP layer handles enumeration, scoring, and chain-derived aggregation.
+
+---
+
+## Core Interaction Principles
+
+1. **Review-first**: State (a) what the AI understood, (b) the decision order, and (c) the interaction contract — before the first choice.
+2. **User-driven**: Every step is an explicit user decision; the AI provides a `recommend` but never auto-advances.
+3. **Neutrality**: the AI surfaces trade-offs and scores, never chooses the branch for the user.
+
+---
+
+## Phase 1: Discover (intent → candidates)
+
+**Demand side** — `evaluation_operation` action=`match_discover`:
+- Provide `description` + `location` (+ optional `budget`, `required_capabilities`, `category`).
+- Returns location-gated, 6-dimension-scored services + recommendation reasons.
+- `category` (e.g. `life_service` / `retail`) applies hard-constraint filtering + weight re-anchoring (K3 15 §3).
+
+**Merchant side** — `evaluation_operation` action=`discover_demands`:
+- Enumerate open Demands (optional `location` filter).
+- A Demand carries rewards (incentive pointers); read the Reward objects by id for amounts.
+
+---
+
+## Phase 2: Compare & Trust
+
+- **Compare**: the `match_discover` result already surfaces per-service scores + reasons. Surface the top-N side-by-side; highlight differences, never force a single pick.
+- **Arbitrator trust**: `evaluation_operation` action=`arbitration_score` with the Arbitration `object` (history auto-fetched via `query_arbs`). Returns `trust` + `fairness` + `combined`. Use it when a merchant chooses which Arbitration to bind, or a customer judges a Service's arbitration guarantee.
+
+---
+
+## Phase 3: Act
+
+- **Attention**: `evaluation_operation` action=`account_events` with the account — surfaces actionable items (unread messages, collectible payments, demand presented). Let the user act on each, never auto-act.
+- **Discovery → order**: hand off to [wowok-order](../wowok-order/SKILL.md) for due diligence + order placement once the user picks a service.
+
+---
+
+## Phase 4: Measure & Govern
+
+- **Metrics**: `evaluation_operation` action=`market_metrics` → active services / open demands / disputes / supply-demand ratio.
+- **Anti-cheat**: `evaluation_operation` action=`anti_cheat` with a Service's orders/reviews/object-stack → returns negative-factor signals (fake order / fake review / shell merchant).
+- **Operations**: `evaluation_operation` action=`market_operations` with `op` = `journey_funnel` / `referral_attribution` / `customer_relationship`.
+
+---
+
+## Design Principles
+
+- **Events signal opportunities only**: chain events are emitted only for participatable/profitable opportunities (K3 13 §6.7) — not for create/pause/noise.
+- **Read the object for authority**: event previews (description ≤260 chars, reward addresses) are routing hints; amounts and authoritative state are read from the object by id.
+- **No fabricated matching**: always run the MCP enumeration/scoring; never invent candidates or scores.

package/wowok-messenger/SKILL.md

@@ -1,23 +1,10 @@
 ---
 name: wowok-messenger
-description: |
-  WoWok Messenger — end-to-end encrypted communication for pre-order negotiation,
-  evidence collection, and dispute resolution.
-
-  Core features: send/receive encrypted messages, generate WTS evidence files,
-  verify message authenticity, manage conversations with anti-spam controls, and
-  integrate with arbitration workflows.
-
-  Used by customers, service providers, and arbitrators for secure off-chain
-  communication that creates tamper-proof audit trails.
-when_to_use:
-  - User needs to communicate with another party (buyer, seller, arbitrator)
-  - User wants to send encrypted messages for negotiation
-  - User needs to generate WTS evidence files from conversations
-  - User wants to verify message authenticity
-  - User needs to manage conversation lists (friends, blacklist, guard)
-  - User mentions "messenger", "message", "chat", "communication", "WTS", "evidence"
-always: false
+description: "WoWok Messenger — end-to-end encrypted communication for pre-order negotiation, evidence collection, and dispute resolution. Core features: send/receive encrypted messages, generate WTS evidence files, verify message authenticity, manage conversations with anti-spam controls, and integrate with arbitration workflows. Used by customers, service providers, and arbitrators for secure off-chain communication that creates tamper-proof audit trails. Use when: User needs to communicate with another party (buyer, seller, arbitrator); User wants to send encrypted messages for negotiation; User needs to generate WTS evidence files from conversations; User wants to verify message authenticity; User needs to manage conversation lists (friends, blacklist, guard); User mentions \"messenger\", \"message\", \"chat\", \"communication\", \"WTS\", \"evidence\"."
+metadata:
+  version: "2.0.0"
+  role: shared
+  related: "wowok-order, wowok-provider, wowok-arbitrator"
 ---
 
 # WoWok Messenger Guide

package/wowok-onboard/SKILL.md

@@ -1,27 +1,10 @@
 ---
 name: wowok-onboard
-description: |
-  WoWok First-Touch Onboarding — guides a NEW user (vague first prompt) to their
-  first published Service through a business-first dialogue: a Review opening
-  followed by AT MOST 8 mandatory business questions (never technical field
-  prompts), then a dependency-aware auto-build with reuse/customize/discover for
-  the technical components. Every business decision (industry, network, location,
-  payment token, pricing, workflow, fund distribution, arbitration) is framed in
-  terms of who-wins-what and why — not which field to fill.
-
-  Use when a new user says "I want to open a shop", "I want to sell something",
-  "how do I start", or has no published Service yet. Produces a complete merchant
-  capability stack: Permission + Service (published) + Machine (published) +
-  Progress (bound) + Guards + Allocation + Contact + Arbitration, verified by a
-  user-driven test order.
-
-  Not for existing merchants tuning operations — hand off to wowok-provider.
-when_to_use:
-  - User is new to WoWok and wants to set up a service
-  - User says "open a shop", "create a service", "start selling", "onboard"
-  - User has no published Service yet on the current account
-  - User completed account creation and asks "what's next"
-  - User resumes an interrupted onboarding (read checkpoint state)
+description: "WoWok First-Touch Onboarding — guides a NEW user from a vague first prompt to their first published Service: a Review opening, then AT MOST 8 mandatory business questions (never technical field prompts), then a dependency-aware auto-build (reuse / customize / discover). Every decision (industry, network, location, token, pricing, workflow, fund distribution, arbitration) is framed as who-wins-what and why. Produces Permission + Service + Machine + Progress + Guards + Allocation + Contact + Arbitration, verified by a test order. Not for existing merchants tuning operations — use wowok-provider. Use when: User is new to WoWok and wants to set up a service; User says \"open a shop\", \"create a service\", \"start selling\", \"onboard\"; User has no published Service yet; User asks \"what's next\" after account creation; User resumes an interrupted onboarding."
+metadata:
+  version: "2.0.0"
+  role: shared
+  related: "wowok-provider, wowok-machine"
 ---
 
 # WoWok First-Touch Onboarding

package/wowok-order/SKILL.md

@@ -1,23 +1,10 @@
 ---
 name: wowok-order
-description: |
-  WoWok Buyer Guide — TWO lifecycles in one skill:
-
-  1. PROSPECT (prospect due diligence, pre-purchase): E1-E11 due diligence + consensus
-     building + trust-score synthesis, ending in a buy/no-buy decision.
-  2. CUSTOMER (in-order fulfillment, post-order): order creation, progress advancement,
-     fund management, and arbitration.
-
-  For suppliers presenting to Demands, see wowok-supplier. For process
-  operators executing workflow forwards, see wowok-collaborator.
-when_to_use:
-  - User is a potential buyer evaluating a service BEFORE purchasing (prospect)
-  - User is a customer/buyer placing or managing orders (customer)
-  - User wants to evaluate services, WIP, guards, allocations, arbitration
-  - User needs to communicate with sellers via Messenger
-  - User asks about order progress, payments, or refunds
-  - User wants to file disputes or arbitration claims
-  - User mentions "buy", "order", "purchase", "refund", "dispute", "arbitration", "due diligence"
+description: "WoWok Buyer Guide — TWO lifecycles in one skill: 1. PROSPECT (prospect due diligence, pre-purchase): E1-E11 due diligence + consensus building + trust-score synthesis, ending in a buy/no-buy decision. 2. CUSTOMER (in-order fulfillment, post-order): order creation, progress advancement, fund management, and arbitration. For suppliers presenting to Demands, see wowok-supplier. For process operators executing workflow forwards, see wowok-collaborator. Use when: User is a potential buyer evaluating a service BEFORE purchasing (prospect); User is a customer/buyer placing or managing orders (customer); User wants to evaluate services, WIP, guards, allocations, arbitration; User needs to communicate with sellers via Messenger; User asks about order progress, payments, or refunds; User wants to file disputes or arbitration claims; User mentions \"buy\", \"order\", \"purchase\", \"refund\", \"dispute\", \"arbitration\", \"due diligence\"."
+metadata:
+  version: "2.0.0"
+  role: customer
+  related: "wowok-provider, wowok-arbitrator, wowok-messenger"
 ---
 
 # WoWok Buyer Guide

package/wowok-output/SKILL.md

@@ -1,15 +1,10 @@
 ---
 name: wowok-output
-description: |
-  WoWok output processing and display — post-processes all WoWok tool responses
-  for human-readable presentation. Handles address resolution, name mapping,
-  amount formatting, and data visualization.
-when_to_use:
-  - AI has received response from any WoWok MCP tool
-  - Response contains addresses requiring name resolution
-  - Response contains amounts requiring human-readable formatting
-  - User queries on-chain data (events, objects, tables)
-always: true
+description: "WoWok output processing and display — post-processes all WoWok tool responses for human-readable presentation. Handles address resolution, name mapping, amount formatting, and data visualization. Use when: AI has received response from any WoWok MCP tool; Response contains addresses requiring name resolution; Response contains amounts requiring human-readable formatting; User queries on-chain data (events, objects, tables)."
+metadata:
+  version: "2.0.0"
+  role: shared
+  loading: always
 ---
 
 # Address Display Rules

package/wowok-planner/SKILL.md

@@ -1,24 +1,10 @@
 ---
 name: wowok-planner
-description: |
-  WoWok Planning Skill — the main planning component of the L4 Harness Plan Loop.
-  Converts user natural-language intent into an executable Object Dependency Graph
-  (ODG) and a phased execution plan. Deterministic-first: rule tables and scenario
-  templates drive planning; the LLM only clarifies intent and translates responses.
-
-  Use when a user says "I want to build...", "plan a service", "help me set up X",
-  or when the L4 Harness opens a new planning cycle. Produces an ODG JSON document
-  consumed by the Harness execution loop, with checkpoints between phases.
-
-  Not for direct execution — hand off to wowok-onboard or wowok-provider for
-  step-by-step MCP orchestration once the ODG is confirmed.
-when_to_use:
-  - User describes a new service intent and needs a build plan
-  - L4 Harness opens a Plan Loop cycle (fresh task)
-  - User asks "what do I need to create to support X"
-  - User wants to reuse existing objects for a new service
-  - User asks for a dependency graph or execution phases
-  - User resumes an interrupted planning session (read ODG checkpoint)
+description: "WoWok Planning Skill — the planning component of the L4 Harness Plan Loop. Converts natural-language intent into an executable Object Dependency Graph (ODG) plus a phased plan. Deterministic-first: rule tables and scenario templates drive planning; the LLM only clarifies intent. Produces an ODG consumed by the Harness execution loop, with checkpoints between phases. Not for direct execution — hand off to wowok-onboard or wowok-provider once the ODG is confirmed. Use when: User describes a new service intent and needs a build plan; the Harness opens a Plan Loop cycle; User asks \"what do I need to create to support X\"; User wants to reuse existing objects for a new service; User asks for a dependency graph or execution phases; User resumes an interrupted planning session."
+metadata:
+  version: "2.0.0"
+  role: shared
+  related: "wowok-onboard, wowok-auditor, wowok-provider"
 ---
 
 # WoWok Planning Skill

package/wowok-provider/SKILL.md

@@ -1,22 +1,10 @@
 ---
 name: wowok-provider
-description: |
-  WoWok Service Provider — the canonical skill for service providers (merchants, sellers)
-  to build, operate, and manage commercial services on WoWok.
-
-  Covers service design (WIP products, Machine workflows, Allocator strategies),
-  trust mechanisms (compensation funds, arbitration), customer attraction
-  (discounts, rewards, supply chain promises), and order fulfillment.
-
-  For customers placing orders, see wowok-order. For arbitrators, see wowok-arbitrator.
-when_to_use:
-  - User is a service provider/merchant/seller on WoWok
-  - User wants to create a commercial service/marketplace
-  - User wants to design workflow (Machine) for order processing
-  - User wants to set up fund distribution strategies (Allocators)
-  - User wants to configure trust mechanisms (compensation, arbitration)
-  - User wants to handle order fulfillment and customer service
-  - User mentions "create service", "merchant", "seller", "provider", "workflow design", "compensation", "arbitration"
+description: "WoWok Service Provider — the canonical skill for service providers (merchants, sellers) to build, operate, and manage commercial services on WoWok. Covers service design (WIP products, Machine workflows, Allocator strategies), trust mechanisms (compensation funds, arbitration), customer attraction (discounts, rewards, supply chain promises), and order fulfillment. For customers placing orders, see wowok-order. For arbitrators, see wowok-arbitrator. Use when: User is a service provider/merchant/seller on WoWok; User wants to create a commercial service/marketplace; User wants to design workflow (Machine) for order processing; User wants to set up fund distribution strategies (Allocators); User wants to configure trust mechanisms (compensation, arbitration); User wants to handle order fulfillment and customer service; User mentions \"create service\", \"merchant\", \"seller\", \"provider\", \"workflow design\", \"compensation\", \"arbitration\"."
+metadata:
+  version: "2.0.0"
+  role: provider
+  related: "wowok-machine, wowok-messenger"
 ---
 
 # WoWok Service Provider Guide

package/wowok-supplier/SKILL.md

@@ -1,21 +1,10 @@
 ---
 name: wowok-supplier
-description: |
-  WoWok Supplier — the canonical skill for suppliers (sub-order providers) who
-  present their service to a Demand and fulfill the resulting sub-order.
-
-  Covers demand discovery, service presentation (open or passport-gated),
-  sub-order fulfillment via Progress, and settlement collection. The supplier
-  is a PEER role with a two-sided position: deliver (to get paid) + collect
-  (from the upstream merchant).
-
-  For the merchant who owns the main Service, see wowok-provider. For the
-  process operators executing the workflow, see wowok-collaborator.
-when_to_use:
-  - User wants to present their service to a Demand (open RFP or gated call)
-  - User is a sub-order provider / supplier fulfilling part of a transaction
-  - User wants to collect settlement from an upstream merchant
-  - User mentions "supplier", "sub-order", "demand", "present service", "RFP", "fulfill sub-order"
+description: "WoWok Supplier — the canonical skill for suppliers (sub-order providers) who present their service to a Demand and fulfill the resulting sub-order. Covers demand discovery, service presentation (open or passport-gated), sub-order fulfillment via Progress, and settlement collection. The supplier is a PEER role with a two-sided position: deliver (to get paid) + collect (from the upstream merchant). For the merchant who owns the main Service, see wowok-provider. For the process operators executing the workflow, see wowok-collaborator. Use when: User wants to present their service to a Demand (open RFP or gated call); User is a sub-order provider / supplier fulfilling part of a transaction; User wants to collect settlement from an upstream merchant; User mentions \"supplier\", \"sub-order\", \"demand\", \"present service\", \"RFP\", \"fulfill sub-order\"."
+metadata:
+  version: "2.0.0"
+  role: supplier
+  related: "wowok-provider, wowok-machine, wowok-messenger"
 ---
 
 # WoWok Supplier Guide