agentleFS
DeltologicDeltologic/datadoe-ai-skills/skills/amazon-asin-search-auditor/SKILL.md

amazon-asin-search-auditor

Skill8 starsChanged 45 days agoMITView on GitHub

Audit an Amazon seller's organic and sponsored search visibility by combining DataDoe search-term data, live Amazon search results, owned-ASIN matching, screenshots, and a reusable dashboard report. Use when asked to run an Amazon ASIN/search visibility audit for a specific DataDoe seller.

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. About 0 are common, 11 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use the built-in browser directly for any ASIN analysis work.

    line 18
  2. Distinctive:

    Do not finish until all steps are done.

    line 19
  3. Distinctive:

    If you need a script to perform an action, use NodeJS.

    line 20
  4. Very specific:

    Create a new directory in the project root at runs/RUN_DIR, with RUN_DIR being run_YY_MM_DD_HH_mm.

    line 21
  5. Very specific:

    Read references/asin-visibility-auditor.md when the user asks for analysis, optimization, or audit work on a specific ASIN.

    line 22
  6. Distinctive:

    When the Action Plan tells you to do so, you MUST spawn a sub-agent.

    line 23
  7. Distinctive:

    Do not repeat the steps that were sent to the sub-agent.

    line 25
  8. Distinctive:

    If the DataDoe Seller or Vendor is not provided: Ask the user to input the Seller or Vendor to use.

    line 28
  9. Distinctive:

    Use the 'sellers_and_vendors_list' tool.

    line 30
  10. Distinctive:

    5 unique: search terms after dedup.

    line 40
  11. Very specific:

    Add all other available metrics to the data, using child_asin_search_query_score for Amazon Search Query Score.

    line 41
  12. Very specific:

    Write coreSearchSummaries.json with normalized fields matching references/dashboard.md.

    line 45
  13. Distinctive:

    Always use web browser cards that are visible to the user, so the user can follow your actions.

    line 49
  14. Distinctive:

    If prompted: Accept cookies usage.

    line 50
  15. Distinctive:

    Search for each unique search term and collect all ASINs with their organic/paid search ranks:

    line 53
  16. Very specific:

    Use this command to URL encode: node -e "console.log(encodeURIComponent('SEARCH_TERM'))".

    line 55
  17. Very specific:

    Before collecting the data, make sure that Deliver to, language, and currency are properly set.

    line 56
  18. Very specific:

    If the user asks for analysis / optimization / audit / etc.

    line 107

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Amazon ASIN Search Auditor

General Rules

  • Execute exactly all actions from the "Action Plan".
  • Use the built-in browser directly for any ASIN analysis work.
  • Do not finish until all steps are done.
  • If you need a script to perform an action, use NodeJS.
  • Create a new directory in the project root at runs/RUN_DIR, with RUN_DIR being run_YY_MM_DD_HH_mm. Store all run files in that directory and only in that directory.
  • Read references/asin-visibility-auditor.md when the user asks for analysis, optimization, or audit work on a specific ASIN.
  • When the Action Plan tells you to do so, you MUST spawn a sub-agent. Spawn sub-agents for those steps and only for those steps.
    • Pause your work until the sub-agent is done. It is OK if you need to wait for the sub-agent for a few minutes.
    • Do not repeat the steps that were sent to the sub-agent.

Action Plan

  1. If the DataDoe Seller or Vendor is not provided: Ask the user to input the Seller or Vendor to use.
  2. (Spawn a sub-agent for this step) DataDoe resolver:
    • Use the 'sellers_and_vendors_list' tool.
    • Return only {sellerId, marketplace, displayName}.
  3. (Spawn a sub-agent for these steps) Core term export normalizer:
    • Fetch the following top search terms data:
      • Source: amazon_child_product_organic_search_ranks_per_week.
      • Total top 5 search terms by child_asin_purchase_count from the last 60 days.
      • This source is weekly-grain (one row per ASIN/term/week), so a row is NOT a unique term - ORDER BY child_asin_purchase_count DESC LIMIT 5 returns 5 rows that can dedupe to fewer terms. Pull a larger limit (15-20 rows) ordered by child_asin_purchase_count DESC from the last 60 days, then take the first 5 unique search terms after dedup.
      • Add all other available metrics to the data, using child_asin_search_query_score for Amazon Search Query Score.
      • child_asin_organic_search_rank is a deprecated compatibility name and should not be used; neither name measures organic search position. Keep scores per ASIN and period, never use them as browser-observed ranks.
      • Download the report to file using exports_raw_url_get method.
      • It is OK if there are fewer than 60 days of data.
    • Write coreSearchSummaries.json with normalized fields matching references/dashboard.md.
    • Return only the top terms + totals.
  4. Prepare a list of unique search terms that appeared in the data.
  5. Open the Amazon website for the seller's marketplace in the built-in browser if available, otherwise fall back to Chrome MCP:
    • Always use web browser cards that are visible to the user, so the user can follow your actions.
  6. If prompted: Accept cookies usage.
  7. Change the Deliver to to a valid postal code from the capital of the marketplace country.
  8. Change the language of the page and currency to the ones local to the marketplace.
  9. Search for each unique search term and collect all ASINs with their organic/paid search ranks:
    • To search, enter a URL matching this pattern: https://AMAZON_DOMAIN/s?k=SEARCH_TERM_URL_ENCODED.
    • Use this command to URL encode: node -e "console.log(encodeURIComponent('SEARCH_TERM'))".
    • Before collecting the data, make sure that Deliver to, language, and currency are properly set.
    • Take a screenshot of the top of each results page in the built-in browser and save it in search_results/screenshots/st-SEARCH_TERM.png.
    • Sponsored results are marked as sponsored. If a result is sponsored, it is not organic (a single ASIN cannot be both).
    • For each search term, prepare a JSON file named search_results/st-SEARCH_TERM.json with the following content:
        {
            "searchTerm": "SEARCH_TERM",
            "amazonMarketplace": "AMAZON_DOMAIN",
            "checkedAt": "CURRENT_DATE",
            "screenshotLocation": "run-root-relative path to the screenshot",
            "organicRanks": [
                {
                    "asin": "ASIN",
                    "organicRank": rank as int,
                    "price_value": price as float 00.00,
                    "price_currency": "CURRENCY_CODE",
                    "asin_name": "NAME_OF_THE_ASIN (exact as displayed in search results)",
                    "asin_rating" review rating as float 0.0 or null if not given in the result tile,
                    "asin_image_url": "LINK_TO_THE_ITEM_IMAGE",
                    "asin_url": "LINK_TO_THE_ITEM (exact URL as the user would click it)",
                    "my_listing": null
                }
            ],
            "ppcRanks": [
                {
                    "asin": "ASIN",
                    "ppcRank": rank as int,
                    "price_value": price as float 00.00,
                    "price_currency": "CURRENCY_CODE",
                    "asin_image_url": "LINK_TO_THE_ITEM_IMAGE",
                    "asin_url": "LINK_TO_THE_ITEM",
                    "my_listing": null
                }
            ]
        }
  10. (Spawn a sub-agent for this step) Extract unique ASINs from all results for each search term using scripts/list-asins.js.
  11. (Spawn a sub-agent for this step) Fetch the seller's active listings for the candidate ASINs only (the unique ASINs from step 11 / asins.json) using DataDoe, and save to CSV:
    • Source: amazon_listings_with_cogs.
    • Filter: child_asin IN [the step-11 candidate ASINs] AND listing_status = Active.
    • This targets the few dozen ASINs from the search results, so it never hits the export row cap (1,000 rows JSON / 5,000 CSV) and needs no pagination - correct regardless of catalog size. Do NOT dump the whole catalog: an unordered listing_status = Active pull on a large catalog can drop an actively-selling owned ASIN off page 1, which then reads as "not mine" and shows a competitor beating a rank that is actually yours.
    • Request child_asin in the columns. DataDoe prepends 8 utility columns before child_asin, so downstream parsing must be header-based, not column-position (see scripts/mark-my-listings.js).
    • (Fallback, only if a full-catalog snapshot is ever required: add a deterministic orderByColumn and loop - "while returned rowCount == limit, repeat with skip += limit" - so the cap never silently drops rows.)
  12. (Spawn a sub-agent for these steps) Run the file-based post-processor for the step 11 ASIN list, step 12 listings export, and the dashboard build:
    • Mark my listings in JSONs using scripts/mark-my-listings.js.
    • Generate report-data.json.
    • Render report.html.
    • Run contract checks.
    • Return only summary stats + paths.
  13. That's all. Open the report page for the user.

If the user asks for analysis / optimization / audit / etc. of a specific ASIN, then follow references/asin-visibility-auditor.md directly with the ASIN, the marketplace domain to use, and the location of your run data. Never run this task in a sub-agent.

Glossary

  • ASIN:
    • An ASIN (Amazon Standard Identification Number) is a unique 10-character code Amazon uses to identify and manage products in its marketplace.
    • ASIN matches the regex: \b[a-zA-Z0-9]{10}\b.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.