Skill: ivangdavila/shipping (version 1.0.0)

--- name: Shipping Operations slug: shipping version: 1.0.0 homepage: https://clawic.com/skills/shipping description: Plan and manage parcel shipping decisions with carrier selection, landed-cost math, customs checks, and delivery exception playbooks. changelog: Initial release with carrier selection, customs checks, and exception handling workflows. metadata: {"clawdbot":{"emoji":"BOX","requires":{"bins":[],"config":["~/shipping/"]},"os":["linux","darwin","win32"],"configPaths":["~/shipping/"]}} --- ## Setup On first use, read `setup.md` for integration guidelines. ## When to Use User needs to ship physical goods and wants reliable decisions across rates, packaging, customs, tracking, and delivery issues. Agent provides shipment planning, carrier choice, cost control, compliance checks, and incident response playbooks. This skill is advisory and workflow-focused. It does not buy labels, call carrier APIs, or access shipping accounts unless the user provides a separate integration workflow. ## Architecture Memory lives in `~/shipping/`. See `memory-template.md` for structure and status fields. ```text ~/shipping/ |- memory.md # Durable shipping context and preferences |- carrier-rules.md # Preferred carriers and service constraints |- international.md # Country and customs notes `- incidents.md # Repeated failure patterns and resolutions ``` ## Quick Reference Use the smallest relevant file for the current task. | Topic | File | |-------|------| | Setup flow | `setup.md` | | Memory template | `memory-template.md` | | Carrier selection | `carrier-selection.md` | | International customs | `international-customs.md` | | Delivery exception handling | `exception-playbook.md` | ## Core Rules ### 1. Confirm Shipment Profile First Before recommending any option, confirm: - Origin and destination - Package count, dimensions, and weight - Delivery deadline and budget ceiling - Value, fragility, and regulatory constraints Never optimize blind. ### 2. Price for Total Landed Cost Always show total cost, not just carrier label price: - Transport fee - Packaging and handling - Fuel, remote, residential, signature, and insurance surcharges - Duties, taxes, and brokerage where applicable If any component is unknown, mark it as estimate and show risk. ### 3. Select Carrier by SLA Risk, Not Sticker Price Pick service based on the real failure cost: - Time-critical shipment: prioritize reliability and claims process - Low-value shipment: prioritize cost efficiency - International shipment: prioritize customs support and tracking depth State tradeoffs explicitly before final recommendation. ### 4. Validate Compliance Before Label Purchase For cross-border shipments, verify: - Commodity description and HS code quality - Declared value consistency with invoice - Prohibited or restricted item checks - Incoterm and importer responsibilities Do not proceed when documentation is incomplete. ### 5. Run Tracking Checkpoints Proactively Set checkpoints at minimum for: - Label created but not scanned within 24h - Customs hold or pending documents - Out for delivery delays beyond promised window For each checkpoint, provide next action and owner. ### 6. Treat Exceptions as Playbooks, Not Improvisation Use a defined response path for lost, damaged, delayed, returned, or refused shipments: - Capture facts and evidence first - Notify customer with realistic timeline - Open claim/escalation within carrier deadline - Decide reshipment vs refund based on cost and SLA ### 7. Save Reusable Shipping Intelligence After each meaningful case, update memory with: - Carrier performance by route - Recurring surcharge patterns - Packaging failures and fixes - Country-specific documentation pitfalls This turns shipping from reactive to compounding. ## Common Traps - Comparing rates without normalizing surcharges -> false savings and margin loss. - Guessing box size from product photos -> dimensional weight surprises. - Declaring vague item descriptions -> customs holds and rejections. - Promising delivery dates without scan confirmation -> avoidable support escalations. - Filing claims without evidence package -> denied reimbursement. - Treating every delay as carrier fault -> misses internal pick-pack bottlenecks. ## Security & Privacy **Data that leaves your machine:** - None by default from this skill itself. **Data that stays local:** - Shipping context and learned patterns under `~/shipping/`. **This skill does NOT:** - Access undeclared external services automatically. - Buy labels or place shipping orders automatically. - Retrieve tracking events from carrier APIs automatically. - Store payment credentials or full card data. - Modify files outside `~/shipping/` for memory. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `ecommerce` - Store operations and conversion workflows. - `marketplace` - Multi-platform selling and fulfillment strategy. - `inventory` - Stock planning and replenishment control. - `sell` - Listing, pricing, and sales execution. - `buy` - Purchasing decisions and supplier-side evaluation. ## Feedback - If useful: `clawhub star shipping` - Stay updated: `clawhub sync`

path: carrier-selection.md
content: # Carrier Selection - Shipping Operations

## Service Selection Matrix

| Priority | Best fit | What to optimize |
|----------|----------|------------------|
| Lowest cost | Economy ground | Total landed cost and surcharge exposure |
| Fast delivery | Express air | On-time performance and recovery speed |
| Fragile/high value | Premium tracked service | Scan fidelity, insurance, claim quality |
| Cross-border | Carrier with customs support | Documentation quality and clearance speed |

## Minimum Inputs Before Quoting

- Origin and destination postal codes
- Package dimensions, weight, and quantity
- Delivery deadline and weekend requirement
- Declared value and insurance intent
- Signature requirement and remote-area risk

No final recommendation without these inputs.

## Landed Cost Formula

Use this formula for each candidate option:

```text
landed_cost = base_rate
            + fuel_surcharge
            + residential_or_remote_fees
            + additional_handling
            + signature_or_insurance
            + brokerage_duties_taxes
            + packaging_cost
```

Always compare options at equal service level and equal delivery promise.

## Dimensional Weight Guardrail

Calculate and compare:

```text
dim_weight = (length * width * height) / carrier_divisor
billable_weight = max(actual_weight, dim_weight)
```

If dim weight dominates, re-evaluate packaging before buying label.

## Recommendation Template

When presenting options, include:
- Option name and expected delivery window
- Total landed cost breakdown
- Top risks (delay, surcharge, claim friction)
- Why this option wins for the stated priority

Keep recommendation short and decision-ready.

## Red Flags

- Rate quote missing surcharges
- Delivery promise with no historical lane evidence
- Insurance excluded for high-value shipments
- Label purchase before package dimensions are confirmed


path: exception-playbook.md
content: # Exception Playbook - Shipping Operations

## Incident Types and First Response

| Incident | First move | Deadline risk |
|----------|------------|---------------|
| No first scan | Verify handoff proof and pickup event | Missed SLA within 24h |
| In-transit delay | Check lane disruption and update ETA | Customer trust erosion |
| Customs hold | Resolve missing document immediately | Return to sender risk |
| Damaged on arrival | Collect photos and packaging evidence | Claim denial if delayed |
| Lost package | Open trace and claim with full evidence | Claim window expiration |
| Refused delivery | Confirm reason and next disposition | Return fees and stock ambiguity |

## Evidence Checklist

Collect before escalation:
- Label and tracking number
- Pickup/dropoff proof
- Weight and dimensions used for quote
- Invoice and customs documents if international
- Photos for damage cases
- Customer communication timeline

No evidence package means weak claim position.

## Customer Communication Rules

- Acknowledge issue quickly with current facts only.
- Give next update time, not vague promises.
- State what you are doing and what is pending from carrier.
- Offer options when threshold is met: wait, reship, or refund.

Silence creates more support load than bad news.

## Escalation Thresholds

Use explicit triggers:
- First scan missing beyond 24h -> open carrier case.
- Delay beyond promised window -> proactive customer update.
- No carrier movement for 48h -> escalate to supervisor queue.
- Claim-relevant incident -> start claim workflow immediately.

Adjust thresholds per carrier SLA if documented.

## Postmortem Pattern

After resolution, log:
- Root cause category (label, handoff, lane, customs, packaging)
- Cost impact (refund, reship, surcharge, labor)
- Preventive control for next shipment

Feed results back into memory and carrier-selection rules.


path: international-customs.md
content: # International Customs - Shipping Operations

## Required Data Package

Before cross-border shipment, verify:
- Legal shipper and receiver identity
- Accurate product descriptions by line item
- HS code per item where required
- Country of origin
- Declared value aligned with commercial invoice
- Incoterm and duty/tax payer

Missing any field means higher hold risk.

## Description Quality Rules

Good description pattern:

```text
[Item type] + [material] + [use] + [model/part if relevant]
```

Avoid vague descriptions like:
- gift
- sample
- accessory
- parts

Vague descriptions increase inspection probability.

## Incoterm Quick Guide

| Incoterm | Seller handles | Buyer handles | Typical use |
|----------|----------------|---------------|-------------|
| DDP | Transport + duties + taxes | Receipt only | Premium customer experience |
| DAP | Transport to destination | Duties/taxes on arrival | Cost control with clear disclosure |
| EXW | Pickup availability | Main transport + import process | B2B where buyer controls freight |

Use one incoterm consistently across invoice and carrier docs.

## Customs Failure Prevention

- Keep invoice totals consistent with label declaration.
- Ensure restricted item checks are done before payment capture.
- Attach required licenses or declarations when category requires.
- Avoid under-declaration shortcuts that increase seizure risk.

## Escalation on Hold

If held in customs:
1. Identify specific missing or conflicting document.
2. Provide corrected file in carrier accepted format.
3. Notify customer with concrete next checkpoint.
4. Recalculate ETA and refund/reship threshold.

Track every hold reason for future prevention.


path: memory-template.md
content: # Memory Template - Shipping Operations

Create `~/shipping/memory.md` with this structure:

```markdown
# Shipping Operations Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending

## Business Context
<!-- Product types, average order value, destination mix -->
<!-- SLA promises, return policy constraints -->

## Carrier Preferences
<!-- Preferred carriers by lane and package profile -->
<!-- Known carrier constraints and account limits -->

## Cost Patterns
<!-- Repeated surcharges and landed-cost drivers -->
<!-- Packaging choices that reduced cost without damage -->

## International Rules
<!-- Country-specific customs notes and documents -->
<!-- Duties/taxes handling preferences and Incoterms -->

## Incident Patterns
<!-- Delay/loss/damage history with resolved outcomes -->
<!-- Which escalations worked fastest and why -->

## Notes
<!-- Stable operational insights worth reusing -->

---
*Updated: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Default learning state | Keep collecting route and carrier evidence |
| `complete` | Stable operating context | Use memory as primary default |
| `paused` | User wants fewer prompts | Ask only when critical data is missing |
| `never_ask` | User rejected setup prompts | Stop prompting and operate silently |

## Integration Values

| Value | Meaning |
|-------|---------|
| `pending` | Activation preference not confirmed |
| `done` | Activation preference confirmed |
| `declined` | User wants manual activation only |

## Key Principles

- Record decisions that improve future shipments, not chat transcripts.
- Keep memory concise and route oriented.
- Redact sensitive identifiers before storing notes.
- Update `last` whenever memory is edited.


path: setup.md
content: # Setup - Shipping Operations

Read this when `~/shipping/` is missing or empty. Start helping immediately while collecting only the context needed to avoid shipping mistakes.

## Your Attitude

Act like an operations lead focused on accurate delivery promises, clear tradeoffs, and fast exception recovery.

## Priority Order

### 1. First: Integration

In early conversation, confirm when this skill should activate:
- Every time shipping or fulfillment appears
- Only when user asks for shipping help directly
- Only for specific regions, carriers, or order types

If user confirms, save activation preference in `~/shipping/memory.md` only.

### 2. Then: Operational Context

Capture the minimum context that changes shipping decisions:
- Typical origins and destinations
- Typical parcel profile (weight, dimensions, value)
- Delivery promises and tolerance for delay
- Primary carriers and account constraints
- International vs domestic mix

Avoid long onboarding. Learn while solving live requests.

### 3. Finally: Decision Preferences

Infer and confirm the user operating style:
- Cost-first vs speed-first vs reliability-first
- Refund-first vs reship-first on incidents
- Aggressive vs conservative customs declarations
- Preferred communication frequency during delays

Store stable patterns, not one-off choices.

## What You Save Internally

Persist only reusable information in `~/shipping/memory.md`:
- Integration preference
- Route and carrier performance patterns
- Known surcharge hotspots
- Customs/documentation edge cases
- Incident outcomes that should influence future choices

Do not save secrets or unnecessary personal data.

## Golden Rule

Answer the active shipping problem first. Use setup context to improve decisions, never to block execution.


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