Skill: ncreighton/supplychainsentinel (version 1.0.0)

--- name: supplychainsentinel description: "Monitor supplier APIs, port delays, and weather in real-time to trigger automatic PO rerouting and stakeholder alerts. Use when the user needs supply chain disruption detection, logistics risk mitigation, or backup sourcing automation." version: 1.0.0 homepage: https://github.com/ncreighton/empire-skills metadata: {"openclaw":{"requires":{"env":["SHIPPO_API_KEY","FLEXPORT_API_KEY","OPENWEATHER_API_KEY","SLACK_WEBHOOK_URL","SENDGRID_API_KEY","DATABASE_URL"],"bins":["curl","jq"]},"os":["macos","linux","win32"],"files":["SKILL.md"],"emoji":"⚓"}} --- ## Overview **SupplyChainSentinel** is a real-time supply chain monitoring and disruption response system that eliminates blind spots in modern logistics networks. Post-COVID supply chain fragility demands intelligent automation—this skill monitors 15+ shipping APIs, port delay databases, and weather systems to detect disruptions before they impact your operations, then automatically triggers PO rerouting workflows and notifies stakeholders with updated ETAs. ### Why This Matters Supply chain disruptions cost enterprises an average of $900K per incident (Gartner). Manual monitoring across Flexport, Shippo, AIS vessel tracking, customs databases, and weather APIs is impossible at scale. SupplyChainSentinel consolidates these signals into a single intelligent system that: - **Prevents stockouts** by detecting delays 48-72 hours early - **Reduces emergency shipping costs** by automating failover to backup suppliers - **Maintains customer trust** with proactive ETA recalculations - **Integrates with existing workflows** via Slack, email, and ERP systems (SAP, NetSuite, Microsoft Dynamics) --- ## Quick Start ### Example 1: Monitor Inbound Shipments for Port Delays ``` Monitor port delays for all active shipments using AIS data. Alert if any vessel is delayed >12 hours from expected arrival. Include vessel name, port code, current delay hours, and recommended alternative routes. ``` **What happens:** - Queries Flexport and Shippo APIs for all active shipments - Checks AIS (Automatic Identification System) vessel tracking data - Compares against scheduled ETAs - Sends Slack alert with delay details and backup supplier recommendations --- ### Example 2: Trigger Automatic PO Rerouting on Weather Risk ``` Check weather forecast for Shanghai and Rotterdam ports over next 7 days. If typhoon or severe storm detected with >60% probability, automatically create alternative POs with backup suppliers and notify procurement team. ``` **What happens:** - Queries OpenWeather API for port regions - Analyzes severe weather probability thresholds - Fetches backup supplier list from your database - Creates new POs in your ERP system - Sends email notifications to procurement stakeholders --- ### Example 3: Real-Time Supplier Status Dashboard ``` Generate a live supplier health report showing: supplier name, on-time delivery rate (last 30 days), current shipment count, average delay hours, and risk score (1-10). Highlight any suppliers with >15% late shipments. ``` **What happens:** - Aggregates historical shipment data from Shippo and Flexport - Calculates on-time delivery metrics per supplier - Scores supplier reliability in real-time - Outputs JSON dashboard data for integration with Tableau or Looker --- ## Capabilities ### 1. Real-Time Supplier API Monitoring Monitor shipment status across 15+ logistics providers with automatic data normalization: - **Shippo** — parcel tracking, label generation, carrier rates - **Flexport** — ocean freight, customs clearance, consolidation - **FedEx/UPS/DHL APIs** — express and ground shipments - **Maersk** — container vessel tracking and port schedules - **Port Authority APIs** — congestion metrics and berth availability **Usage:** ``` Poll supplier APIs every 30 minutes. Flag any shipment with status change to "delayed", "held_customs", or "vessel_diversion". Cross-reference with historical baseline to identify anomalies. ``` --- ### 2. Port Delay Detection via AIS & Customs Data Track vessel movements and port congestion in real-time: - **AIS vessel tracking** — real-time GPS coordinates, speed, ETA updates - **Port congestion indices** — berth wait times, queue lengths - **Customs clearance tracking** — document status, inspection hold-ups - **Weather impact correlation** — storm delays, port closures **Usage:** ``` For each active ocean shipment, retrieve vessel AIS data. Compare current position against expected trajectory. If vessel speed <3 knots for >4 hours in port area, flag as potential congestion and estimate delay. ``` --- ### 3. Weather Impact Forecasting Predict logistics disruptions from meteorological data: - **Typhoon/hurricane tracking** — probability, wind speed, affected ports - **Fog and visibility impacts** — on port operations (Singapore, Rotterdam) - **Temperature extremes** — for temperature-sensitive cargo (pharma, food) - **Port closure predictions** — 48-72 hour forecast based on weather thresholds **Usage:** ``` Daily 6 AM check: Query OpenWeather API for all active port regions. If severe weather probability >50% and shipment ETA within 5 days, trigger alternative routing evaluation. ``` --- ### 4. Automatic PO Rerouting to Backup Suppliers Intelligently failover to alternative suppliers when disruptions detected: - **Backup supplier database** — pre-configured alternatives per SKU - **Automated PO creation** — generates new purchase orders in your ERP - **Cost comparison** — selects backup based on price + delivery speed - **Inventory optimization** — prevents over-ordering via safety stock adjustment **Usage:** ``` When primary supplier shipment delayed >24 hours, automatically: 1. Query backup supplier inventory for same SKU 2. Compare landed cost (price + expedited shipping) 3. Create PO if cost delta <15% and delivery <original ETA 4. Notify procurement with comparison matrix 5. Update master schedule with new ETA ``` --- ### 5. Stakeholder Notifications with ETA Recalculations Multi-channel alerts with updated delivery timelines: - **Slack integration** — real-time alerts to #supply-chain channel - **Email notifications** — detailed reports to procurement, sales, finance - **ERP system updates** — automatic PO and delivery schedule changes - **Customer notifications** — optional proactive outbound to B2B customers - **ETA recalculation** — machine learning model factors in port delays, weather, carrier performance **Usage:** ``` When disruption detected, send Slack alert: "🚨 SUPPLY CHAIN ALERT: Maersk vessel UASC-2847 delayed 18 hours at Rotterdam. Original ETA: Jan 15, 2 PM. Revised ETA: Jan 16, 8 PM. Backup supplier PO created. Procurement notified. [View Details]" ``` --- ## Configuration ### Required Environment Variables ```bash # Shipping & Logistics APIs export SHIPPO_API_KEY="your_shippo_token" export FLEXPORT_API_KEY="your_flexport_api_key" export MAERSK_API_KEY="your_maersk_api_key" # Weather & Geolocation export OPENWEATHER_API_KEY="your_openweather_key" export AIS_API_KEY="your_ais_provider_key" # e.g., MarineTraffic # Notifications export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL" export SENDGRID_API_KEY="your_sendgrid_key" # Database & ERP export DATABASE_URL="postgresql://user:pass@localhost/supply_chain_db" export NETSUITE_ACCOUNT_ID="your_netsuite_account" export NETSUITE_API_KEY="your_netsuite_key" ``` ### Configuration Options ```yaml monitoring: poll_interval_minutes: 30 # How often to check APIs delay_threshold_hours: 12 # Trigger alert if delayed >12h weather_severity_threshold: 0.60 # Storm probability threshold rerouting: cost_variance_threshold: 0.15 # Allow 15% cost increase for backup enable_auto_po_creation: true # Auto-create POs or notify only safety_stock_buffer_days: 2 # Additional buffer for backup orders notifications: slack_enabled: true email_enabled: true channels: - "#supply-chain" - "[REDACTED_SECRET]" - "[REDACTED_SECRET]" # Finance alerts on cost changes ``` ### Setup Instructions 1. **Create supplier master data table:** ```sql CREATE TABLE suppliers ( supplier_id UUID PRIMARY KEY, name VARCHAR(255), api_type VARCHAR(50), api_credentials JSONB, backup_suppliers UUID[], on_time_rate DECIMAL, last_updated TIMESTAMP ); ``` 2. **Configure API credentials** in your `.env` file or secrets manager (AWS Secrets Manager, HashiCorp Vault) 3. **Connect to your ERP system** (NetSuite, SAP, Dynamics 365) via API or webhook 4. **Set up Slack workspace** and generate incoming webhook URL 5. **Initialize monitoring** with historical shipment data (last 90 days) to establish baselines --- ## Example Outputs ### Port Delay Alert (Slack) ``` 🚨 SUPPLY CHAIN DISRUPTION DETECTED Shipment: #SHP-2024-001847 Carrier: Maersk Line Vessel: UASC-2847 Current Location: Rotterdam Port, Netherlands Current Delay: +18 hours from scheduled ETA 📊 Details: • Scheduled Port Arrival: Jan 15, 2:00 PM UTC • Revised ETA: Jan 16, 8:00 PM UTC • Reason: Port congestion (12 vessels ahead in queue) • Weather Impact: None detected ✅ Action Taken: • Backup supplier PO created (cost +8%) • New delivery date: Jan 18, 10:00 AM • Procurement team notified • Customer notification scheduled 🔗 View Full Details | Escalate | Dismiss ``` ### Supplier Health Report (JSON) ```json { "report_date": "2024-01-15T10:30:00Z", "suppliers": [ { "supplier_id": "SUP-001", "name": "Shanghai Electronics Ltd", "on_time_delivery_rate": 0.94, "active_shipments": 7, "avg_delay_hours": 2.1, "risk_score": 3, "status": "healthy", "last_shipment": "2024-01-14T16:45:00Z" }, { "supplier_id": "SUP-004", "name": "Port Klang Logistics", "on_time_delivery_rate": 0.71, "active_shipments": 3, "avg_delay_hours": 14.8, "risk_score": 7, "status": "at_risk", "recommendation": "Shift 40% volume to backup supplier SUP-007" } ] } ``` ### ETA Recalculation Report (Email) ``` Subject: Supply Chain Update - Shipment #SHP-2024-001847 Dear Procurement Team, Your shipment from Shanghai to Rotterdam has been updated: Original ETA: January 15, 2:00 PM Updated ETA: January 16, 8:00 PM Delay Reason: Port congestion + AIS data indicates vessel speed reduced Backup Action: A secondary shipment has been created with Alternative Supplier (DHL Express) Expected Delivery: January 17, 6:00 PM Cost Impact: +$2,400 (8% premium) Next Steps: 1. Review backup PO in NetSuite: [Link] 2. Confirm customer notification preference 3. Approve cost variance (auto-approved if <15%) Questions? Contact [REDACTED_SECRET] ``` --- ## Tips & Best Practices ### 1. Establish Baseline Metrics First Before automating rerouting, collect 60-90 days of historical data to understand: - Typical delay patterns by supplier, route, season - Normal port congestion at key hubs (Shanghai, Rotterdam, Singapore) - Seasonal weather impacts (typhoon season, monsoons) **Action:** Run in "monitoring only" mode for 60 days before enabling auto-rerouting. --- ### 2. Pre-Configure Backup Suppliers Manually map 2-3 backup suppliers per critical SKU before activating automation: - Verify backup supplier quality, lead times, and pricing - Establish volume discounts and payment terms - Test API integration with backup supplier systems - Document cost variance thresholds (e.g., allow 10-15% premium for faster delivery) --- ### 3. Set Appropriate Alert Thresholds Too many false alarms cause alert fatigue; too few miss real disruptions: - **Port delays:** Alert at >12 hours (typical port delay = 4-8 hours) - **Weather:** Alert at >60% severe weather probability within 5 days of arrival - **Supplier delays:** Alert if on-time rate drops below 85% (30-day rolling) - **Customs:** Alert if clearance takes >48 hours longer than historical average --- ### 4. Integrate with Your ERP System Connect to NetSuite, SAP, or Dynamics 365 to: - Auto-update PO delivery dates in real-time - Trigger inventory rebalancing workflows - Generate financial impact reports (landed cost changes) - Maintain audit trail of all rerouting decisions **Example:** NetSuite webhook integration to update PO status and notify accounting of cost variances. --- ### 5. Monitor Machine Learning Model Performance The ETA recalculation model improves over time with more data: - Track prediction accuracy weekly (target: ±2 hours) - Retrain model monthly with latest shipment outcomes - Adjust weather and port congestion weights based on actual impact - A/B test rerouting decisions to optimize cost vs. speed trade-offs --- ### 6. Create Escalation Workflows Not all disruptions require immediate action: - **Green (Low Risk):** Monitor only, no action needed - **Yellow (Medium Risk):** Notify procurement, evaluate backup options - **Red (High Risk):** Auto-create backup PO, notify executive stakeholders **Example:** Typhoon warning for port closing = Red (auto-reroute). Single vessel delayed 6 hours = Green (monitor). --- ## Safety & Guardrails ### What This Skill Will NOT Do ❌ **Will NOT override human approval** for cost-significant decisions - Auto-rerouting is limited to cost variance <15% by default - Rerouting decisions >$50K require manual approval via Slack workflow - Finance team receives all cost impact notifications ❌ **Will NOT make supplier decisions based solely on price** - Quality metrics, delivery history, and risk scores weighted equally - Backup suppliers must meet minimum on-time delivery threshold (85%) - Supplier blacklist prevents routing to known problem vendors ❌ **Will NOT create orders for suppliers without pre-configuration** - Only suppliers in your approved supplier master database are eligible - New suppliers require manual setup and API testing before activation - Prevents accidental orders to unapproved or fraudulent suppliers ❌ **Will NOT send customer notifications without approval** - Optional feature disabled by default - Requires explicit opt-in per customer - Uses templated, reviewed messaging only ❌ **Will NOT bypass compliance or regulatory requirements** - Respects sanctioned country lists (OFAC, EU, etc.) - Maintains audit trail of all rerouting decisions - Compliant with export control regulations (EAR, ITAR) ### Known Limitations ⚠️ **API availability:** Relies on third-party APIs (Shippo, Flexport, OpenWeather). Degradation in their service = delayed alerts. **Mitigation:** Implement redundant data sources and fallback thresholds. ⚠️ **AIS data lag:** Vessel position data may be 15-30 minutes delayed. **Mitigation:** Use conservative delay thresholds (>12 hours) to avoid false alerts. ⚠️ **Weather forecast accuracy:** Severe weather predictions >5


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)