skill-review Skill
在合并前审查 Coupler.io 技能、审计现有技能或检查技能包的准确性时使用。触发词包括:“审查这个技能”、“检查这个 SKILL.md”、“这个技能准确吗”、“审查技能仓库中的 PR #N”、“审计 <平台> 技能包”,或任何要求核实技能中关于 Coupler.io 连接器或广告平台说法的请求。会对照实际工具和仓库规范检查事实准确性,但不评判领域专业水平。
安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。
技能指令原文(SKILL.md)
Skill Review
You review Coupler.io skills for claims that are wrong, unactionable, or contradicted elsewhere in the same file. The defects below are ones this repo has actually shipped, each found in a real review. Work the list; do not improvise a different one.
The rule the whole skill rests on: verify, never recall. Every factual claim about a connector, a report type, a column, a unit or a platform is checkable against a live tool or a file in this workspace. A claim you cannot source is a finding, whether or not it turns out to be true. Training-era knowledge of "how Google Ads structures its data" is a hint for where to look, never an answer.
What this does not review. Domain judgment — what counts as creative fatigue, which volume floor makes a verdict defensible, whether a cut is safe. That needs a practitioner who runs the accounts. Say so in the report rather than implying full coverage.
Sources of truth, in priority order
| Question | Where to look |
|---|---|
| Does this connector have that report type, entity or parameter? | get-integration on the live MCP — never the skill's own list |
| Can the assistant set that parameter, or must a human? | mcp_excluded_params in coupler-io-web/config/integrations/sources// |
| What is a column actually called, and what does it hold? | get-schema on a real dataset, then get-data to look at values |
| What can a dataflow do — sources, transformations, joins? | coupler-io-knowledge-base/coupler-product.md |
| Known traps for this connector | coupler-io-knowledge-base/sources/category/// |
| Default column labels, formats and visibility | coupler-io-web/config/integrations/sources//transformations/ |
| Column names for a connector with no transformations/ folder | The importer's field lists in coupler-io-serverless/functions//source-/ — columns arrive under raw API names |
| Can this user add the connector at all? | access.level and feature_flag in the connector's config |
| Platform behaviour (budgets, attribution, metric definitions) | The platform's own docs, fetched and read. Never memory |
| Has this platform rule been checked before, and what value do other skills use? | .agents/skills/platform-rules/registry.md. Start here, then check the source if the row is older than the change you suspect |
When two sources disagree, the live tool wins over config, config wins over the knowledge base, and the knowledge base wins over the skill under review. Record the disagreement — a KB page that contradicts the product is its own bug worth reporting.
The recurring defects
Check every one against the skill under review. Each has shipped in this repo at least once.
1. Asserted units
A skill telling the model that costs "may be in millionths" when the connector already converts them. The check is cheap and the failure is enormous: a spend figure wrong by a factor of a million.
The fix is never a corrected constant. It is an instruction to read the column name from get-schema and decide from that, because the answer differs across report types within one connector.
2. Dead ends that are not dead ends
"That section is dead." "Adding a report type will not fix it, that needs a change upstream." "Skip the section and say why."
A Coupler.io dataflow accepts unlimited sources, and most connectors expose far more report types than the wizard shows first. A missing table is nearly always one source away. Rewrite every such line to name the cause and the fix: which report type, which parameter, which credential.
Check an absence claim against every variant, not the first one that matches. Options are often scoped to one report type through dependsOn, and connectors ship variants of the same report with different dimensions and columns. A report that lacks the field can sit next to one that has it. Search for the field across every report type and every option list before accepting "not in this connector".
Check that the route is complete, not just that one exists. A skill can name the right fix and still understate it. paid-vs-organic-search-overlap (#33) offered per-action conversions through one Custom GAQL source, but a breakdown by conversion action can't carry cost, so cost per conversion by action takes the existing report plus a second source, joined on search term. When the fix needs another source and a join, the skill has to say both steps, or the model builds the first one, finds no cost and stops.
3. Fixes the assistant cannot perform
The mirror image of defect 2, and easier to miss because the text reads helpfully. A skill that says "unhide the column in the dataset step" is naming an action no MCP tool exposes. A skill that says "add the audience dimension" on a connector whose dimensions sit in mcp_excluded_params is naming an action the assistant cannot take.
Every recommended fix must be either executable by the assistant or explicitly handed to the user. "Say it can be added" and "offer to add it" are different instructions, and which one is correct depends on mcp_excluded_params for that connector. Check before you rewrite either into the other.
A missing column has two layers; check both. Whether the column is fetched is set by the source's columns parameter, which the assistant can change unless it sits in mcp_excluded_params. Whether it is visible is set in the dataset step, which only the user can change. shopify-sales-by-country-and-market (#40) called Customer order index "not checkable" when it is in the Orders entity's default columns and shown by default. The fix covers both cases: offer to add it to the source, and if it is fetched but hidden, ask the user to unhide it.
The same applies to recommending a connector or report type. One at access.level: dev or behind a feature_flag is invisible to most accounts, so a fix that tells the user to add it is a fix they cannot perform. Name the generally available option first and mark the gated one as available only where enabled.
A conditional fix must say how the assistant can tell whether the condition holds. "Offer it only where it is available" with no observable test gets guessed.
4. Non-additive metrics aggregated
Ratio metrics and de-duplicated counts cannot be summed or averaged across rows:
- Daily ratios — impression share and its lost-to-budget and lost-to-rank variants. Recover the raw numerator and denominator per row, sum those, then divide.
- De-duplicated people — reach, and frequency derived from it. Adding daily reach across a period counts the same person once per day.
- Running totals and snapshots — month-to-date spend, monthly or lifetime budgets, balances, any as-of value repeated on every date row. Summing them across dates multiplies the figure by the number of days. Take the latest complete row per entity.
Any skill that aggregates one of these over a window without saying how is producing a confident wrong number. This is the highest-severity defect that reads as correct prose.
5. Internal contradictions
A pack said "a native report type will not fix it" in one section and "a missing report type is a source you can add, not a dead end" in the same file's Rules section. The early instruction won, because it fired first.
Grep each file against itself for the claims you are checking. Where two passages conflict, the one earlier in the run wins in practice, so that is the one to fix.
6. Claims that came from training rather than the platform
Ad platforms change faster than skills do. Two from real reviews: a reviewer nearly "corrected" a correct 75% Meta daily-budget figure to the legacy 25%, and a metric assumed dead was confirmed alive only by querying live data.
Treat every platform number — attribution windows, budget flexibility, learning thresholds, metric availability — as unverified until sourced. Verify or delete. Do not soften into a hedge; a hedged wrong fact is still wrong.
Record what you verify. Platform rules live in the registry at .agents/skills/platform-rules/registry.md; its SKILL.md defines what counts as one. For every platform rule the skill under review states:
- Already in the registry: the skill must carry the registry's value. A different value is a contradiction between packs; one of them is wrong, so check the source before choosing. Add the skill to the row's
Used in. - Not in the registry: verify it against the platform's page and add a row in the same PR, or add it as
UnverifiableorSecondhandif the page can't be read. - Inline: the value carries its source and the date it was checked, plus the instruction to check the page when the agent can browse. A platform rule with no source or date is a finding.
#41 shows why: one "about 20% per step" rule was written for Google, Meta and TikTok, and the three platforms' own pages say three different things.
7. Column names and meanings carried over from a sibling pack
Packs are built by copying an existing one, and the copy keeps the source platform's column labels. A label that is right for one connector names a column that does not exist in the next: a connector with a transformations/ folder gets friendly labels, one without it gets raw API names.
Check every column the skill names against get-schema or the connector's own transformations or importer field lists, never against the sibling it was copied from.
The same goes for what a column means. shopify-product-and-variant-performance told the model that the cost column in Shopify's Orders with activities is cost at the time of sale, because it sits on dated sale rows. The importer reads it from variant.inventoryItem.unitCost, the item's current cost. #40 copied the claim into two more skills before review caught it. When a skill says what a column holds (historical or current, gross or net, per row or repeated), check what the importer actually reads into it, not what its neighbours suggest.
8. Facts deferred to the model at runtime
"Take the window from the platform's documentation or ask." "Leave the most recent days out." The skill names a fact it needs and does not state it, so each run recalls its own value and sibling skills disagree. The agent has no web access at runtime, so "check the docs" means "recall".
Look for "see the documentation", "ask", or an unsized "recent", "some" or "a few" standing in for a value. The fix is the value itself, stated once per pack, with a note on when to override it.
Except where the right value depends on the business. A volume floor that suits one market or industry is meaningless in another, so a fixed number is as wrong as a missing one. For those the fix is a procedure: if no value is saved for the dataset, suggest one from the data, confirm it with the user in the same message as the coverage verdict, and save it. A method is not such a value. A break rule or a threshold multiple is defined in the skill, because asking a user how far below baseline counts as a break gets a guess. Found across the SEO pack in #33, where every skill said "a volume floor stated" and none gave one.
9. Redundant metadata in the body
[Source tag: X] lines duplicating metadata.sources, or a version restated in prose. Frontmatter is the single source; the body should not repeat it.
One exception: the intro paragraph under the H1 (see the convention table in item 10). It repeats frontmatter on purpose, because it is what the GitHub page shows.
10. Convention drift
| Field | Rule |
|---|---|
| name | Exactly the folder slug, which is also how siblings cross-reference it |
| metadata.category | One of the categories already in skills-index.json, not a new invention |
| metadata.sources | The integration's name from get-integration, verbatim, for every connector the body handles, or [] for connector-agnostic skills. The Skills page filters on exact match, so a missing connector hides the skill from its users |
| metadata.version | 1.0.0 for a new skill. Do not adopt a sibling's version to look consistent |
| Intro under the H1 | metadata.short_description, then