linkfox-amazon-store-auth

🛑 If

linkfox-amazon-store-auth

is not installed / loaded, please install it first before using this skill.

1. Read any of the following paths (skill loading path depends on the runtime environment;

   scripts/check_auth_dependency.py

   will automatically detect following the same rules):
   • Repository / general flat directory:

     <skills_dir>/linkfox-amazon-store-auth/SKILL.md

   • Claude:

     ~/.claude/skills/linkfox-amazon-store-auth/SKILL.md

   • Cursor:

     ~/.cursor/skills/...

     、

     ~/.cursor/skills-cursor/...

   • OpenClaw:

     <OPENCLAW_WORKSPACE>/skills/...

     、

     ~/.openclaw/skills/...

     、

     ~/.agents/skills/...

     (consistent with common paths in OpenClaw Skills Documentation)
   • Hermes Agent:

     ~/.hermes/skills/<category>/linkfox-amazon-store-auth/SKILL.md

     , and

     ~/.hermes/plugins/<plugin>/skills/linkfox-amazon-store-auth/SKILL.md

     (consistent with the layout in Hermes Skills Documentation)
2. Or run the script directly:

   python scripts/check_auth_dependency.py

   , the script will exit with exit code

   42

   when the dependency is missing, and output structured prompts starting with

   DEPENDENCY_MISSING:

   to stderr. The script has built-in path judgment for OpenClaw / Hermes; if

   skills.external_dirs

   is configured in Hermes'

   config.yaml

   , please set the environment variable

   HERMES_SKILLS_EXTERNAL_DIRS

   (concatenate multiple directories with system path separators) for detection.
3. If all the above checks fail, it is determined that

   linkfox-amazon-store-auth

   is not installed.

linkfox-amazon-store-auth

1. Attempt automatic installation (priority):
   • If the current runtime has a skill installation tool (such as skill marketplace / skill management MCP /

     install_skill

     -like tools), call it immediately to install

     linkfox-amazon-store-auth

     .
   • After successful installation, reload and execute this skill from the beginning.
2. Guide users to install manually (fallback):
   • Explain to the user: "This skill depends on

     linkfox-amazon-store-auth

     , which has not been installed yet. Please go to LinkFox Skills to install this skill, and let me know when it's done, I will continue to pull the report for you."
   • Do not bypass the dependency to directly call interfaces like

     /spApi/authorizeUrl

     ,

     /spApi/storeTokens

     ,

     /spApi/authorizedStores

     — the store selection and token processes for authorization are the responsibilities of

     linkfox-amazon-store-auth

     , this skill only handles report-related business.
3. Do not silently degrade: If neither automatic installation nor user confirmation is available, stop execution and report the dependency missing fact to the user, do not attempt alternative solutions without permission.

• This skill will internally call

  /spApi/storeTokens

  provided by the dependent skill to obtain

  accessToken

  , then execute the report lifecycle via

  /spApi/developerProxy

  .
• Operations such as authorization, pre-authorization store selection, token refresh — handled by

  linkfox-amazon-store-auth

  ; this skill does not repeat these tasks.

• Report Type: Official Amazon report type enumerations, such as

  GET_MERCHANT_LISTINGS_ALL_DATA

  ,

  GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL

  . The complete list can be found in

  references/report-types.md

  .
• Marketplace ID: Specific site ID within a region, e.g., US =

  ATVPDKIKX0DER

  .
• Report lifecycle: Request report → poll

  processingStatus

  (

  IN_QUEUE

  /

  IN_PROGRESS

  /

  DONE

  /

  FATAL

  /

  CANCELLED

  ) → get

  reportDocumentId

  when

  DONE

  → retrieve download URL → download (mostly gzip TSV) → decompress.
• Rate limits: Reports API is approximately 0.0222 req/s; polling intervals must be maintained (default 30s).

• scripts/get_report.py

  ⭐ — End-to-end automated report retrieval (recommended)

• scripts/check_auth_dependency.py

  — Actively check if the dependent skill

  linkfox-amazon-store-auth

  is installed

1. Try to read

   linkfox-amazon-store-auth/SKILL.md

   (if allowed by the tool)
2. Or execute:
   bash

   python scripts/check_auth_dependency.py

3. If the exit code is non-zero or stderr contains

   DEPENDENCY_MISSING:

   , follow the process in "Standard Handling When Dependency Is Not Installed" above
4. Proceed to normal business scenarios only after dependencies are met

1. Dependency check (Scenario 0)
2. Pre-selection of store + token retrieval: Delegate to

   linkfox-amazon-store-auth

   • Call

     /spApi/authorizedStores

     to let the user select a store
   • Call

     /spApi/storeTokens

     to obtain the token (this skill's script will automatically complete this step, no manual call needed)
3. Identify report type: Match

   reportType

   based on user's request
   • Inventory:

     GET_MERCHANT_LISTINGS_ALL_DATA

     ,

     GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA

   • Orders:

     GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL

   • Sales and traffic:

     GET_SALES_AND_TRAFFIC_REPORT

   • Finance:

     GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE

   • Complete list:

     references/report-types.md

4. Execute script:
   bash

   python scripts/get_report.py '{
     "sellerId": "A1EC6SZ7XAMURH",
     "region": "NA",
     "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
     "marketplaceIds": ["ATVPDKIKX0DER"]
   }'

5. The script will automatically: retrieve token → request report → poll → download → decompress → preview → output JSON; upon completion, it will provide the local absolute path (

   downloadPath

   ), local file URI (

   localFileUri

   ) in stderr and JSON, and by default start a temporary local HTTP service to generate

   extractedFileHttpUrl

   (for downloading the decompressed file in the browser on the same machine). When presenting to the user, at least show

   extractedFileHttpUrl

   ,

   downloadPath

   and

   fileName

   ; the script will shut down the service after

   serveSeconds

   expires, and the link will become invalid immediately. To get the Amazon source URL (mostly compressed packages), set

   includeAmazonSourceUrl: true

   only during debugging.

/spApi/developerProxy

1. Retrieve existing reports (faster):

   path: reports/2021-06-30/reports
   method: GET
   queryString: reportTypes=<type>&marketplaceIds=<ids>

2. Create new report:

   path: reports/2021-06-30/reports
   method: POST
   body: {"reportType": "...", "marketplaceIds": [...]}

3. Check status:

   path: reports/2021-06-30/reports/{reportId}
   method: GET

4. Retrieve download link:

   path: reports/2021-06-30/documents/{reportDocumentId}
   method: GET

1. Dependencies first, business later: Do not start any report-related calls until dependency check passes.
2. Only present data: Show report retrieval progress, download path, first few lines of preview; do not provide business interpretation.
3. Respect user-selected report type: Only pull the specified report type, do not switch to other types without permission.
4. Clear errors: When report retrieval fails (

   FATAL

   / 403, etc.), explain the reason and return the decision-making power to the user.
5. Security: Mask accessToken in logs.
6. Show addresses and local download links after completion: After the script successfully ends, must inform the user of

   extractedFileHttpUrl

   (temporary local HTTP download for decompressed files),

   downloadPath

   (local absolute path),

   fileName

   (file name) and

   localFileUri

   ; and explain that "it is only available on the same computer running the script and within the service retention period". Do not use the Amazon source URL as the default download entry for users; use

   includeAmazonSourceUrl

   only when explicitly requested by the user or for troubleshooting.

• NEVER automatically try alternative report types when user's specified report fails.
• When report request fails (

  FATAL

  , 403, etc.), stop immediately and inform the user of the failure.
• Do not decide on behalf of the user to pull other report types.
• Clearly state the failure reason and let the user decide the next step (retry / change type / check permissions, etc.).
• Example: When

  GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT

  fails, do not automatically switch to pulling

  GET_MERCHANT_LISTINGS_ALL_DATA

  .

• 403 Unauthorized

  : Missing API permissions or not enrolled in Amazon Brand Registry

• FATAL

  : This store does not support this report type or has insufficient data
• Brand Analytics reports require brand registration
• Vendor reports are only available for Vendor accounts

• Depends on

  linkfox-amazon-store-auth

  : Must install it first if not installed, see Prerequisites.
• Token expiration:

  accessToken

  expires after 1 hour, the script automatically retrieves the latest token internally.
• Rate limits: Reports API is 0.0222 req/s, default 30s polling interval is safe.
• Report timeliness: Some financial reports may take 10–30 minutes, adjust

  maxAttempts

  as needed.
• Path whitelist: Backend

  sp-api.developer-proxy.allowed-path-prefixes

  must allow

  reports/2021-06-30/reports

  .

• Authorize new stores, list authorized stores, refresh/query tokens → Use

  linkfox-amazon-store-auth

• Product listing management, order processing, advertising delivery → Handled by other skills

• This skill only handles "dependency check + report retrieval business", authorization/token management belongs to the dependent skill.
• Any call entering this skill must run Scenario 0 first.

1. The skill's function description does not match the actual behavior
2. The result does not match the user's intent
3. The user expresses dissatisfaction or appreciation
4. Other areas you think can be improved

references/api.md