This buildbook installs a skill that lets 📝Claude Code find any product on 📝Amazon and produce a correctly tagged affiliate link inline while writing, and it gates that skill behind the one validation step that cannot be automated. The gate is the point: Amazon returns HTTP 200 for any string in the tag parameter, so a wrong tracking ID produces links that look perfect, work perfectly, and earn nothing — silently, indefinitely, with no error anywhere.
This is a 📝Buildbook, not a 📝Runbook — it converges an environment to a target state once per adopter. Re-running it against a converged setup must produce zero changes and zero errors.
Prerequisites
- An Amazon Associates account with at least one tracking ID. Tracking IDs are listed under Associates Central → Account Settings → Manage Your Tracking IDs.
- Claude Code installed, with
WebSearchandWebFetchavailable. The skill performs a live product lookup on every link and cannot work without them. - Ability to sign in to Associates Central in a browser. Step 4 requires it and cannot be delegated to the agent.
- No Amazon API credentials. None exist to obtain — see the Reference section on why.
- Assumes the
amazon.commarketplace. Other locales work identically but need that locale's own tracking ID.
Quickstart
Every step checks current state before acting. Do not skip Step 4.
1. Check for an existing installation.
ls -la ~/.claude/skills/amazon-affiliate/SKILL.md 2>/dev/null || echo "NOT_INSTALLED"If the file exists, the skill is installed — verify its contents against the Reference Implementation below and correct any drift, then continue to Step 3. If NOT_INSTALLED, continue to Step 2.
2. Install the skill file.
Create the directory and write the file whose full contents appear in Reference Implementation. This artifact is owned by this buildbook, so reconcile it — bring it to match the reference exactly, and never leave a partial older version in place.
mkdir -p ~/.claude/skills/amazon-affiliate3. Set the partner tag.
Add your tracking ID to ~/.claude/settings.json under the env key. Check for an existing value first and correct it rather than adding a duplicate.
{
"env": {
"AMAZON_PARTNER_TAG": "yourtag-20"
}
}4. Validate the tag. This step is mandatory and cannot be automated.
Pick any Amazon product, build a link by hand in the form https://www.amazon.com/dp/{ASIN}?tag={YOUR_TAG}, and paste it into Associates Central → Tools → Link Checker. It must report success before you use the skill for anything.
Do not skip this because the tag "looks right." Do not let an agent substitute a curl check, a redirect trace, or a page fetch — those all pass for a garbage tag and prove nothing. If Link Checker does not validate, go to Troubleshooting; do not proceed.
5. Verify end to end.
Ask the agent for an affiliate link to a specific product. A correct result is a live lookup — a web search, then a page fetch to confirm the product — followed by a link in /dp/{ASIN}?tag= form carrying your validated tag. An agent that produces an ASIN instantly without searching has failed the check; the skill's core purpose is preventing exactly that.
Reference
The silent-failure mode
This is the whole reason the buildbook exists.
Amazon accepts any string in the tag parameter. A valid tracking ID, an invalid one, and a deliberately fabricated one all return an identical HTTP 200 with an identical product page. The tag is not echoed in the served HTML, so there is nothing to assert against. Redirect resolution, status codes, and response-body inspection are all useless here — verified by control request against a nonsense tag.
The consequence is that a typo in a tracking ID is undetectable from outside the account, produces working links, and costs every commission until someone happens to check the dashboard. There is no error, no warning, and no failed request.
Only two authenticated surfaces can confirm a tracking ID:
- Manage Your Tracking IDs in Associates Central — the authoritative list of every valid ID on the account.
- Link Checker, fed a hand-built product link. Amazon's help documentation states the checker is "intended primarily for people constructing or modifying their own Associate links," which is exactly the format this skill emits — so a failure there is real signal, not a format rejection. The same page warns it "does not work correctly with links that are copied from Associate Central or the Site Stripe," so validate a hand-built link, not a SiteStripe one.
Link format
The canonical form is https://www.amazon.com/dp/{ASIN}?tag={TAG}. An ASIN is exactly ten characters, beginning with B0 for products or a digit for books and ISBNs.
Never use search-results URLs, and strip any /ref= or session parameters down to the bare product path. Short links are permitted but not useful here: Amazon's own shortener produces amzn.to links only through SiteStripe, one manual click at a time, so an agent cannot generate them. Amazon's Operating Agreement does not ban shorteners outright — it prohibits using one "in a manner that makes it unclear that you are linking to an Amazon Site" — but the bare form is auditable at a glance and validatable in Link Checker, which the short form is not.
There is no product API
Do not attempt to wire this skill to an Amazon API. The Product Advertising API 5.0 is deprecated and returns HTTP 403; its documentation URLs redirect to a deprecation notice. Its successor, the Creators API, issues credentials only to accounts meeting a rolling qualified-sales threshold per locale. As of July 2026 no MCP server wrapped it — every published Amazon affiliate MCP either targets the dead API or builds URL strings without fetching anything, emitting search-results links this skill explicitly forbids. Live web search plus page verification is the correct approach, at the cost of price, availability, and image data.
Why the live lookup is non-negotiable
Agents confidently produce ASINs from training data. Those ASINs are frequently stale, consolidated into a different listing, or simply wrong, and a wrong ASIN yields a link to the wrong product or a dead page. Popular products are worse, not better, because the model is more confident. The skill enforces search-then-verify on every single link for this reason.
Reference Implementation
The complete skill file. Write this verbatim to ~/.claude/skills/amazon-affiliate/SKILL.md.
---
name: amazon-affiliate
description: Use when writing or editing content that references purchasable products and needs Amazon affiliate links. Triggers on "affiliate link", "Amazon link", "link to product", or when a memo mentions a specific product available on Amazon.
---
# Amazon Affiliate Link Builder
Search for Amazon products and construct affiliate-tagged links for embedding in content (memos, articles, emails).
## Step 1: Check for Partner Tag
```bash
if [ -n "$AMAZON_PARTNER_TAG" ]; then
echo "TAG: $AMAZON_PARTNER_TAG"
else
echo "MISSING_TAG"
fi
```
If `MISSING_TAG`: tell the user to add it to `~/.claude/settings.json` under the `env` key, then restart. STOP here until configured.
### Validate the tag before using it (REQUIRED on first use of any new tag)
**A non-empty tag is not a valid tag.** Amazon returns HTTP 200 for *any* string in
`?tag=` — including nonsense. A wrong tag produces working links that earn nothing,
and fails silently and indefinitely. Curl, redirect checks, and response-body
inspection CANNOT detect this. Do not attempt to validate a tag mechanically.
The only surfaces that can confirm a tracking ID are authenticated:
1. **Associates Central → Account Settings → Manage Your Tracking IDs** — the
authoritative list of every valid ID on the account.
2. **Associates Central → Link Checker**, fed a hand-built
`https://www.amazon.com/dp/{ASIN}?tag={TAG}` link. Amazon documents the checker
as "intended primarily for people constructing or modifying their own Associate
links" — that is exactly this format, so a failure here is real signal.
Neither is reachable from a session. When `AMAZON_PARTNER_TAG` changes, ask the user
to run check 2 once and report the result before you emit any links using it.
## Step 2: Find the Product on Amazon (REQUIRED)
**NEVER guess or recall ASINs from memory.** ASINs from training data may be stale, consolidated, or wrong. You MUST do a live lookup.
Use WebSearch to find the product on Amazon:
```
site:amazon.com {product name}
```
From the search results, find the Amazon product page URL. Amazon product URLs contain the ASIN in one of these patterns:
- `amazon.com/dp/ASIN`
- `amazon.com/gp/product/ASIN`
- `amazon.com/Some-Product-Name/dp/ASIN`
An ASIN is always exactly 10 characters, starting with `B0` (for products) or a digit (for books/ISBNs).
If WebSearch returns no Amazon results, try broader search terms or a different product name variation.
### Verification
After extracting the ASIN, use WebFetch on `https://www.amazon.com/dp/{ASIN}` to confirm:
1. The page loads (not a 404 or dog page)
2. The product title matches what the user asked for
If the product doesn't match, go back and try different search terms.
## Step 3: Construct the Affiliate Link
Format:
```
https://www.amazon.com/dp/{ASIN}?tag={AMAZON_PARTNER_TAG}
```
That's it. Do NOT use:
- Search URLs (`/s?k=...`) — these land on search results, not the product
- Long URLs with `/ref=` or session parameters — strip to `/dp/{ASIN}?tag=`
- Shortened URLs or link services
## Step 4: Format for Content
Return the link as a markdown hyperlink using the product name as anchor text, substituting the live value of `$AMAZON_PARTNER_TAG` for the tag.
**Never hardcode a literal tag in this file.** A literal example tag WILL eventually get copy-pasted into published content, crediting whoever owns it.
## Batch Mode
When content references multiple products, process them all in one pass:
1. Identify all product references in the content
2. WebSearch for each product
3. Construct all affiliate links
4. Present the full list for user review before inserting
## Common Mistakes
| Mistake | Fix |
|---------|-----|
| Guessing ASIN from training data | ALWAYS use WebSearch. ASINs change. |
| Using `/s?k=` search URLs | Use `/dp/{ASIN}` direct product links only |
| Including tracking/ref parameters | Strip to `/dp/{ASIN}?tag=` |
| Skipping verification | Always WebFetch the link to confirm product match |
| Forgetting the tag parameter | Every link must include the tag |
| Treating a non-empty tag as a valid tag | HTTP 200 proves nothing. Validate via Link Checker once per tag. |
| Hardcoding a literal tag in this file | Substitute the env var — a stale literal credits someone else |
| Trying to validate a tag with curl | Impossible. Amazon 200s any string. Ask the user to check Associates Central. |
## Red Flags — STOP
- You're about to type an ASIN without having searched for it → STOP, search first
- You "remember" the ASIN for a popular product → You don't. Search.
- WebSearch returned no Amazon results → Try different terms, don't guessExact Commands & Payloads
Check whether the skill is already installed — the idempotency guard for Step 1:
ls -la ~/.claude/skills/amazon-affiliate/SKILL.md 2>/dev/null || echo "NOT_INSTALLED"Create the skill directory. Safe to re-run:
mkdir -p ~/.claude/skills/amazon-affiliateConfirm the tag is visible to the agent's environment after configuring it:
if [ -n "$AMAZON_PARTNER_TAG" ]; then echo "TAG: $AMAZON_PARTNER_TAG"; else echo "MISSING_TAG"; fiThe settings block for ~/.claude/settings.json, merged into any existing env object rather than replacing it:
{
"env": {
"AMAZON_PARTNER_TAG": "yourtag-20"
}
}The link form to paste into Link Checker at Step 4, with your own tracking ID substituted:
https://www.amazon.com/dp/0887306667?tag=yourtag-20Troubleshooting
Symptom: Link Checker reports the link "could not be validated."
Cause: most likely the tracking ID is not valid on the account. The message also appears for unsupported formats, but a hand-built product link is the format Amazon documents the tool for, so treat this as a tag problem first.
Recovery: open Manage Your Tracking IDs and compare character by character against the value in settings. Correct the setting to a listed ID and re-check. Do not proceed until it validates.
Symptom: links work and traffic converts, but reporting shows zero commissions.
Cause: the classic silent failure — a valid-looking, invalid tag.
Recovery: run the Step 4 validation. Then audit previously published links; every link emitted with the bad tag needs its tag corrected, as none of them ever attributed.
Symptom: the agent returns an affiliate link instantly, without searching.
Cause: the skill is not loading, or the agent is recalling an ASIN from training data.
Recovery: confirm the file is at ~/.claude/skills/amazon-affiliate/SKILL.md and restart the session. Verify the returned ASIN by fetching the product page — a hallucinated ASIN usually resolves to an unrelated product rather than a 404, which is why this failure is easy to miss.
Symptom: published content carries a tag that is not yours.
Cause: a literal example tag was copy-pasted out of the skill file or from documentation.
Recovery: search published content for the tag parameter and correct every occurrence. Confirm the skill file contains no literal tag anywhere — examples must reference the environment variable.
Symptom: an agent proposes installing an Amazon MCP server or wiring up the Product Advertising API.
Cause: outdated training data. That API is deprecated and returns 403.
Recovery: stop. Nothing to install. See the Reference section on why live search is the correct path.