Agent skill

world-model-workflow

Build a rigorous world model with state, dynamics, uncertainty, and provenance. Use when creating digital twins, constructing system representations, building simulation foundations, or establishing baseline world state.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/digital-twin-bootstrap

SKILL.md

Intent

Run the composed workflow world-model-workflow using atomic capability skills to construct a comprehensive, grounded representation of a system or domain.

A world model captures:

  • State: Current entity states and attributes
  • Dynamics: How the system evolves over time
  • Uncertainty: Confidence bounds and unknowns
  • Provenance: Source and lineage of all facts

Success criteria:

  • Complete entity inventory with identity resolution
  • State representation follows canonical schema
  • Causal relationships and dynamics modeled
  • Uncertainty quantified for all assertions
  • Full provenance chain for every fact
  • Simulation capability established

Compatible schemas:

  • reference/world_state_schema.yaml
  • reference/event_schema.yaml

Inputs

Parameter Required Type Description
goal Yes string The modeling objective (e.g., "model supply chain for disruption analysis")
scope Yes string|array Domain, system, or entities to model
constraints No object Limits (e.g., time horizon, resolution, confidence threshold)
sources No array Data sources for world state extraction
prior_model No object Existing model to extend or refine

Procedure

  1. Create checkpoint marker if mutation might occur:

    • Create .claude/checkpoint.ok after confirming rollback strategy

  2. Invoke /retrieve and store output as retrieve_out

    • Gather raw data from configured sources

  3. Invoke /inspect and store output as inspect_out

    • Examine retrieved data for structure and quality

  4. Invoke /identity-resolution and store output as identity-resolution_out

    • Resolve entity references and establish canonical IDs

  5. Invoke /world-state and store output as world-state_out

    • Construct canonical state representation

  6. Invoke /state-transition and store output as state-transition_out

    • Define rules for state evolution

  7. Invoke /causal-model and store output as causal-model_out

    • Map cause-effect relationships

  8. Invoke /uncertainty-model and store output as uncertainty-model_out

    • Quantify confidence and unknowns

  9. Invoke /provenance and store output as provenance_out

    • Document source and lineage of all facts

  10. Invoke /grounding and store output as grounding_out

    • Attach evidence anchors to assertions

  11. Invoke /simulation and store output as simulation_out

    • Validate model through simulation runs

  12. Invoke /summarize and store output as summarize_out

    • Generate human-readable model summary

Output Contract

Return a structured object:

yaml
workflow_id: string  # Unique model construction ID
goal: string  # Modeling objective
status: completed | partial | failed
world_model:
  version: string
  created_at: string  # ISO timestamp
  schema_version: string
  entities:
    count: integer
    by_type: object  # type -> count
    sample: array[object]  # representative entities
  relationships:
    count: integer
    types: array[string]
    sample: array[object]
  evidence_anchors: array[string]
state:
  snapshot: object  # Canonical world state
  hash: string  # Integrity hash
  timestamp: string
  evidence_anchors: array[string]
dynamics:
  transition_rules: integer
  causal_links: integer
  temporal_scope: string  # e.g., "real-time", "daily", "event-driven"
  evidence_anchors: array[string]
uncertainty:
  overall_confidence: number  # 0.0-1.0
  high_uncertainty_areas: array[string]
  unknown_factors: array[string]
  evidence_anchors: array[string]
provenance:
  sources: array[string]
  lineage_depth: integer
  coverage: number  # 0.0-1.0 (% of facts with provenance)
  evidence_anchors: array[string]
simulation:
  validated: boolean
  scenarios_tested: integer
  anomalies_found: array[string]
  evidence_anchors: array[string]
summary:
  description: string
  key_insights: array[string]
  recommended_actions: array[string]
  evidence_anchors: array[string]
confidence: number  # 0.0-1.0
evidence_anchors: array[string]
assumptions: array[string]

Field Definitions

Field Type Description
workflow_id string Unique identifier for this model construction
world_model object Metadata about entities and relationships
state object Canonical world state snapshot with integrity hash
dynamics object Transition rules and causal structure
uncertainty object Confidence levels and unknown factors
provenance object Source tracking and lineage
simulation object Model validation results
summary object Human-readable insights
confidence number 0.0-1.0 based on evidence completeness
evidence_anchors array All evidence references collected
assumptions array Explicit assumptions made during modeling

Examples

Example 1: Build Supply Chain World Model

Input:

yaml
goal: "Model electronics supply chain for disruption risk analysis"
scope:
  - "suppliers"
  - "manufacturers"
  - "logistics"
  - "inventory"
constraints:
  time_horizon: "6 months"
  geographic_scope: "Asia-Pacific"
  confidence_threshold: 0.7
sources:
  - type: database
    connection: "postgres://supply-chain-db"
  - type: api
    endpoint: "https://logistics.api/shipments"

Output:

yaml
workflow_id: "world_20240115_100000_supplychain"
goal: "Model electronics supply chain for disruption risk analysis"
status: completed
world_model:
  version: "v1.0.0"
  created_at: "2024-01-15T10:00:00Z"
  schema_version: "world_state_schema_v2"
  entities:
    count: 1247
    by_type:
      supplier: 156
      manufacturer: 23
      warehouse: 45
      distribution_center: 12
      product: 892
      shipment: 119
    sample:
      - id: "supplier-taiwan-001"
        type: "supplier"
        name: "Taiwan Semiconductor Co"
        location: "Hsinchu, Taiwan"
        capacity: 50000
        lead_time_days: 45
      - id: "mfg-shenzhen-005"
        type: "manufacturer"
        name: "Shenzhen Electronics Assembly"
        location: "Shenzhen, China"
        capacity: 100000
  relationships:
    count: 3456
    types:
      - "supplies_to"
      - "located_in"
      - "transports_via"
      - "stores_at"
      - "depends_on"
    sample:
      - subject: "supplier-taiwan-001"
        predicate: "supplies_to"
        object: "mfg-shenzhen-005"
        attributes:
          volume: 25000
          frequency: "weekly"
  evidence_anchors:
    - "tool:database:supply-chain-db/entities"
    - "tool:api:logistics.api/shipments"
state:
  snapshot:
    timestamp: "2024-01-15T10:00:00Z"
    entities: "[1247 entities - see world_state.yaml]"
    relationships: "[3456 relationships - see world_state.yaml]"
  hash: "sha256:def456abc789..."
  timestamp: "2024-01-15T10:00:00Z"
  evidence_anchors:
    - "file:state/supply_chain_world.yaml"
dynamics:
  transition_rules: 34
  causal_links: 89
  temporal_scope: "daily"
  evidence_anchors:
    - "tool:state-transition:rule_extraction"
    - "tool:causal-model:dependency_graph"
uncertainty:
  overall_confidence: 0.82
  high_uncertainty_areas:
    - "Supplier capacity utilization (estimated from public data)"
    - "Shipping delays (historical average, not real-time)"
  unknown_factors:
    - "Competitor orders affecting supplier allocation"
    - "Regulatory changes in transit countries"
  evidence_anchors:
    - "tool:uncertainty-model:confidence_analysis"
provenance:
  sources:
    - "postgres://supply-chain-db (primary)"
    - "https://logistics.api (secondary)"
    - "public filings (supplementary)"
  lineage_depth: 3
  coverage: 0.94
  evidence_anchors:
    - "tool:provenance:lineage_trace"
simulation:
  validated: true
  scenarios_tested: 5
  anomalies_found:
    - "Taiwan supplier shutdown causes 67% production halt within 2 weeks"
    - "Shipping route disruption adds 12-day average delay"
  evidence_anchors:
    - "tool:simulation:scenario_results"
summary:
  description: "Electronics supply chain model covering 156 suppliers, 23 manufacturers, and supporting logistics infrastructure in Asia-Pacific region"
  key_insights:
    - "Single-source dependency on Taiwan for 45% of semiconductor supply"
    - "Shenzhen manufacturing hub handles 60% of assembly volume"
    - "Average supply chain depth of 3 tiers with limited visibility beyond tier 1"
  recommended_actions:
    - "Diversify semiconductor sourcing to reduce Taiwan concentration risk"
    - "Establish buffer inventory for critical components"
    - "Develop secondary logistics routes for key shipping lanes"
  evidence_anchors:
    - "tool:summarize:executive_summary"
confidence: 0.82
evidence_anchors:
  - "tool:database:supply-chain-db"
  - "tool:api:logistics.api"
  - "tool:simulation:scenario_results"
  - "file:state/supply_chain_world.yaml"
assumptions:
  - "Database reflects current operational state"
  - "API provides accurate shipment tracking"
  - "Public capacity data is within 20% of actual"
  - "Lead times based on historical 90-day average"

Evidence pattern: Multi-source data integration, entity resolution across databases, causal analysis from transaction patterns, uncertainty from data freshness and coverage.

Verification

  • Entity Coverage: All entities in scope identified with canonical IDs
  • Relationship Completeness: Key relationships mapped with evidence
  • State Validity: World state conforms to schema
  • Dynamics Defined: Transition rules and causal links documented
  • Uncertainty Quantified: Confidence scores for all major assertions
  • Provenance Complete: Source documented for >90% of facts
  • Simulation Validated: At least 1 scenario successfully executed

Verification tools: Read (for state files), Bash (for simulation), Web (for API validation)

Safety Constraints

  • mutation: false
  • requires_checkpoint: false
  • requires_approval: false
  • risk: medium

Capability-specific rules:

  • Do not modify source data during modeling
  • Flag entities with confidence < threshold
  • Document all assumptions explicitly
  • Preserve raw data alongside derived state
  • Validate schema conformance before completion
  • Rate-limit API calls to respect source limits

Composition Patterns

Commonly follows:

  • retrieve - After gathering raw data
  • receive - After ingesting real-time signals
  • inspect - After initial data quality assessment

Commonly precedes:

  • digital-twin-sync-workflow - World model is prerequisite for sync
  • simulate - To run what-if scenarios
  • forecast-risk - To predict future states
  • summarize - To generate executive reports

Anti-patterns:

  • Never skip identity resolution before state construction
  • Never omit uncertainty modeling for production use
  • Never finalize without provenance documentation
  • Never deploy model without simulation validation

Workflow references:

  • See reference/workflow_catalog.yaml#world-model-workflow for step definitions
  • See reference/world_state_schema.yaml for canonical state format

Didn't find tool you were looking for?

Be as detailed as possible for better results