# Tuckmark Agent Import

> Parse private order exports outside Tuckmark, identify materials and quantities, research product pages when permitted, then submit and complete a Tuckmark managed inventory import with the released CLI. Use outside a Tuckmark source checkout for Taobao or other order-derived intake.

- Skill: `ivanli-cn/tuckmark-agent-import` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ivanli-cn/tuckmark-agent-import`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivanli-cn/tuckmark-agent-import/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ivanli-cn (https://skillmd.com/u/ivanli-cn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ivanli-cn/tuckmark-agent-import

---


# Tuckmark Agent Import

Use the released `tuckmark` CLI. Tuckmark itself does not parse order files, invoke an LLM, or automate a browser.

## Privacy Boundary

- Keep the original order export and product-page body local. Do not commit, upload, attach, log, or put either in a proposal.
- Use only a concise source note that the user approves. Never include account data, addresses, order numbers, or the session secret.
- Open a product page only in the user's already-authorized browser context. Stop for login, CAPTCHA, 2FA, payment, or any other identity challenge.

## Workflow

1. Resolve the named DEVD instance. Pass `--instance <name>` or set `TUCKMARK_DEVD_INSTANCE`; the command fails without one. The CLI uses local Unix socket / Named Pipe IPC and does not accept a DEVD URL or data directory.
2. Read only the Agent recommendation catalog and current inventory:

   ```bash
   tuckmark agent-import catalog --instance "$DEVD_INSTANCE"
   tuckmark agent-import inventory --instance "$DEVD_INSTANCE" --query "<model or keyword>"
   ```

   Catalog results include only system and shared-directory templates. `recommendedUse` is an optional human-readable suggested use; for **new** materials, use the material evidence to select and order up to three suitable templates. An absent suggestion means the template remains usable but is not a default recommendation.

3. Interpret the order outside Tuckmark. Decide material identity yourself; do not run name matching that silently converts a new item into a restock. Use `kind: "restock"` only with the exact `targetMaterialId` returned by inventory. Include that material's `updatedAt` as `targetMaterialUpdatedAt`.
4. Add `needsAttention` when identity, quantity, suffix, packaging, or other factual evidence is uncertain. It is non-blocking: do not force the user to certify the match.
5. Build a local, temporary `tuckmark.agent-import.v1` proposal. New items must have one default `template`, up to two ordered alternatives, positive inventory quantity, positive `labelPrintQuantity`, and material fields. `description` is the concise overview; `deviceDetails` is one Markdown string for factual device details. Do not turn that detail into a key-value object or manufacture attributes from incomplete evidence. Derive label quantity from storage packages or independently labeled units; never copy the inventory quantity blindly. Restocks must keep `template` absent.

   ```json
   {
     "schema": "tuckmark.agent-import.v1",
     "sourceNote": "purchase receipt",
     "items": [{
       "id": "agent-local-item-1",
       "kind": "new",
       "selected": true,
       "quantity": 100,
       "labelPrintQuantity": 1,
       "material": {
         "fullName": "Example IC",
          "description": "Single-line overview",
          "deviceDetails": "- Verified feature\n- Package evidence",
         "packagingRemark": "reel"
       },
       "sourceNote": "purchase receipt",
       "template": { "source": "system", "id": "cable-tag", "name": "Cable Tag", "fields": [] },
       "templateAlternatives": [],
       "templateInput": {},
       "revision": 0,
       "pendingTemplateEventId": null
     }]
   }
   ```

6. Create the session. The CLI opens the confirmation page unless `--no-open` is supplied. It prints a session ID and permission-restricted credential-file path, never the secret.

   ```bash
   tuckmark agent-import create --file /tmp/proposal.json --instance "$DEVD_INSTANCE"
   ```

7. Wait for user changes. If the user switches a new-material template, DEVD creates a field-contract event and freezes only that label panel. Poll and fulfill the exact event revision:

   ```bash
   tuckmark agent-import wait --session <session-id> --instance "$DEVD_INSTANCE"
   tuckmark agent-import fulfill --session <session-id> --event <event-id> --revision <revision> \
     --input '{"field":"value"}' --instance "$DEVD_INSTANCE"
   ```

   Do not fulfill an event with guessed fields. A stale revision is rejected; refresh with `wait`, regenerate values for the new field contract, and continue waiting.

8. Do not confirm on the user's behalf. The user reviews, edits, selects items, and confirms in the Web App. Sessions expire after 30 minutes.