What Should a Good SKU.md Tell an AI Agent?
v1.0.0 features
An annotated product-knowledge anatomy covering facts, guidance, limitations, compatibility, identifiers, and evidence without turning Markdown into a feed.
Status: This article reflects the current v1.0.0-beta boundary. It reports a method and its evidence requirements, not unverified adoption, ranking, citation, recommendation, or sales outcomes.
A good SKU.md document is not a shorter product page. It is a product knowledge record arranged around decisions an Agent must make. A useful way to review one is to take a single product and ask what each section contributes to a recommendation.
Working example: a compact travel charger
Assume a store sells a 65 W two-port charger in several plug variants. The product page can carry photographs, launch messaging, reviews, and a buy button. The knowledge document should make the stable decision facts explicit: output profiles, included plug type, supported devices, excluded use, model identifiers, and sources.
The document should describe the exact variant being discussed. “Works worldwide” is not an adequate fact if the plug or voltage assumptions vary by market.
Facts describe the product
Facts should be observable and specific: port types, maximum combined output, dimensions, weight, materials, or included components. Each fact needs a source that a consumer can inspect. Avoid adjectives such as “ultimate” or “best” unless the statement is a clearly attributed claim rather than a product fact.
Facts are not a dumping ground for volatile commerce fields. Current price and stock still belong to live authorities.
Guidance explains appropriate use
Guidance translates facts into supported use without pretending to know the shopper. For the charger, guidance may explain which device combinations stay within the power budget or when carrying one adapter can replace two. It should remain conditional and traceable to the product’s capabilities.
Good guidance helps the Agent ask better questions. If simultaneous charging changes output allocation, that condition belongs in the explanation.
Limitations and compatibility prevent expensive mistakes
Limitations state where the product should not be recommended: unsupported high-power laptops, wet environments, or regions requiring a different plug module. Compatibility names the interfaces, versions, accessories, dimensions, or environmental conditions that must match.
These sections carry more decision weight than generic benefits. A single incompatibility can invalidate an otherwise attractive recommendation.
Identifiers connect records without collapsing them
SKU, MPN, GTIN, and variant labels operate at different scopes. The document should bind each identifier to the product or variant it actually identifies. If the product page, feed, and JSON-LD disagree, preserve the conflict for review instead of silently choosing the most convenient value.
Identifiers make joins possible; they do not prove that every joined record is equivalent.
Sources make claims inspectable
A source URL belongs next to the statement it supports. A general home page is weak evidence for a technical compatibility claim. Prefer the product page, manual, support document, or official policy that contains the relevant information.
Record when the document was updated. Consumers should retain both the knowledge resource URL and the underlying claim source.
Anatomy review table
| Section | Question it answers | Failure to avoid |
|---|---|---|
| Facts | What is it? | marketing language treated as fact |
| Guidance | When is it useful? | unconditional advice |
| Limitations | When should it be excluded? | benefits overriding a veto |
| Compatibility | What must match? | assumed interface or version |
| Identifiers | Which exact record or variant? | product and variant IDs merged |
| Sources | Why should the claim be trusted? | unattributed summaries |
Publication test
Give the document to a reviewer who has not seen the product page. Ask them to identify the product, select an appropriate use case, reject an incompatible case, and trace every decisive claim. Any answer that requires guessing reveals a gap to fix before publication.
Anatomy of one useful product record
Imagine a stainless-steel bottle sold in two lid configurations. Facts can state capacity, material, dimensions, and insulation test conditions. Guidance can explain that the straw lid suits upright everyday use. Limitations can state that the straw lid is not leakproof when inverted and that the bottle is not intended for carbonated drinks. Compatibility can identify cup-holder diameter and replacement lids. Identifiers distinguish the bottle group from each lid-and-color variant. Every decisive statement links to a public source.
The categories prevent prose from doing too many jobs. “Ideal for any adventure” is not a testable fact. “Fits holders at least 76 mm wide” is a compatibility threshold. “Do not use with hot liquids when the straw lid is installed” is a limitation. A consumer can apply these statements differently because the merchant published their function explicitly.
Write claims at the strength of the evidence
Good knowledge is precise about scope. If a test covers one model, color, or configuration, the statement should not silently expand to every variant. If the source says “water resistant,” the document should not upgrade it to “waterproof.” If a dimension excludes a removable handle, state that condition. The source link proves where the claim came from; wording still determines whether the claim is faithful.
Unknown information belongs in the unknown set. Omitting a claim is safer than inferring it from a photograph or a neighboring product. If the missing fact is likely to decide recommendations, the merchant can add it to an editorial queue. A consumer should treat absence as absence, not as a positive or negative value.
Review with real shopper questions
An editorial review becomes stronger when it uses questions rather than a field checklist alone. Can the record answer who the product suits, who should avoid it, what it works with, which variant is meant, and which source supports the conclusion? Can it recognize when current stock, price, shipping, tax, or payment must be checked elsewhere?
Run the questions against every variant edge that matters. Ask a second reviewer to trace each answer back to the exact statement and source. The goal is not maximum text. It is the smallest maintained set of claims that supports correct matching, clear refusals, and a reliable handoff to live commerce.
Prefer bounded completeness over exhaustive copying
Copying every Product Information Management field can bury the statements that matter. Start from decisions: identity, suitability, incompatibility, variant selection, evidence, and live handoff. Add a fact when it helps one of those decisions and has a maintained public source. Leave internal logistics and duplicated marketing text out.
This keeps documents economical for both editors and consumers. It also makes change review meaningful: a diff shows a changed claim rather than thousands of regenerated attributes. Completeness means that the document supports its declared use cases and names its unknowns, not that it mirrors the merchant’s entire database.
Use identifiers to keep examples attached to the right item
Names alone are weak joins. A group may share a marketing name while sizes, colors, connectors, or regional models differ. Merchant SKU, MPN, GTIN, ISBN, and brand identifiers should be scoped to the entity they actually identify and copied exactly from an authoritative source. When identifiers conflict, the consumer must report the conflict rather than merge records because their titles look similar. This protects every fact and limitation that follows.