CtrlK
BlogDocsLog inGet started
Tessl Logo

stripe-best-practices

Guides Stripe integration decisions across development and test environment planning (separate sandboxes vs the shared test mode sandbox), API selection (Checkout Sessions vs PaymentIntents), Connect platform setup (Accounts v2, controller properties), billing/subscriptions, tax and registrations (Stripe Tax, automatic_tax, product tax codes), Treasury financial accounts, integration options (Checkout, Payment Element), migrating from deprecated Stripe APIs, and security best practices (API key management, API key permissions, webhooks, OAuth). Use when planning, building, modifying, testing, or reviewing any Stripe integration, including choosing a development environment, accepting payments, building marketplaces, integrating Stripe, processing payments, setting up subscriptions, collecting sales tax, VAT, or GST, creating connected accounts, or implementing secure key handling.

80

1.78x
Quality

81%

Does it follow best practices?

Impact

100%

1.78x

Average score across 2 eval scenarios

SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

71%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured routing-style skill: concrete commands and parameter-level rules, a clear domain-to-reference routing table, and a verified one-level-deep bundle. The main costs are time-sensitive version tables and SDK rows inlined in the body, plus slightly padded rationale in the payment-methods rule.

Suggestions

Move the 'Latest API version' line and the SDK version table into a dedicated reference file or a 'current versions' section so stale numbers don't burden the always-loaded body.

Trim the rationale in the payment_method_types rule ('to maximize conversion', 'dynamically display the most relevant eligible payment methods') to a one-line directive.

Add a one-line correct-pattern example of instantiating a StripeClient, since the rule currently only shows the deprecated anti-patterns.

DimensionReasoningScore

Conciseness

Mostly efficient directive prose, but time-sensitive version data sits in the main body rather than a deprecated/old-patterns section ('Latest Stripe API version: 2026-08-26.dahlia' plus a 7-row SDK version table), and a few passages explain rationale Claude doesn't need (the payment_method_types rule spends several clauses justifying dynamic payment methods and conversion). This fits 'Mostly efficient but includes some unnecessary explanation or could be tightened'.

3 / 5

Actionability

Highly concrete throughout: exact commands ('npm i -g @stripe/cli', 'stripe sandbox create', 'stripe whoami --format json'), exact parameter names ('payment_method_types', 'allowed_payment_method_types', 'integration_identifier', 'automatic_tax: { enabled: true }'), and named deprecated patterns. It falls just short of fully copy-paste ready because the StripeClient rule says what not to do ('Do not use the deprecated global/module-level API key pattern') without showing the correct instantiation example.

4 / 5

Workflow Clarity

The routing table gives a clear decision flow, 'Read the relevant reference file before answering any integration question or writing code' sets the sequence, and the tax rule includes an explicit pre-flight checkpoint ('read the tax reference and confirm the user has an active registration') with the failure consequence. It matches 'Clear sequence with most checkpoints present; minor validation gaps' — there is no explicit error-recovery/feedback loop, but no destructive or batch operation requires one.

4 / 5

Progressive Disclosure

The body is a lean overview that routes each domain to a real one-level-deep bundle file via the integration routing table (payments, connect, billing, tax, treasury, security — all verified present in references/), with a mandatory 'read the relevant reference' directive and no nested references inside the bundle. This matches 'Clear overview with well-signaled one-level-deep references; content appropriately split; easy navigation'.

5 / 5

Total

16

/

20

Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: third-person voice, concrete and comprehensive capability list, and an explicit multi-phrase 'Use when' clause. Its only weakness is slight over-length and a few missing natural trigger terms (invoices, refunds, disputes), which keeps trigger coverage just below comprehensive.

Suggestions

Trim the capability list to the highest-value domains to reduce description length without losing trigger coverage.

Add a few common natural trigger phrases such as 'creating invoices', 'handling refunds or disputes', or 'setting up webhooks' to round out keyword coverage.

DimensionReasoningScore

Specificity

The description enumerates many concrete, named capabilities — 'API selection (Checkout Sessions vs PaymentIntents)', 'Accounts v2, controller properties', 'automatic_tax, product tax codes', 'Treasury financial accounts', 'API key management, API key permissions, webhooks, OAuth' — giving comprehensive, non-abstract coverage of the skill's scope. It clearly matches the anchor 'Lists multiple specific concrete actions; comprehensive coverage'; nothing is generic filler.

5 / 5

Completeness

Both questions are answered explicitly: 'Guides Stripe integration decisions across...' states what the skill does, and 'Use when planning, building, modifying, testing, or reviewing any Stripe integration, including...' gives concrete, multiple trigger phrases. This matches the anchor for 'Clearly and explicitly answers both what AND when with concrete trigger phrases'.

5 / 5

Trigger Term Quality

The 'Use when' clause covers many natural phrasings — 'accepting payments', 'building marketplaces', 'setting up subscriptions', 'collecting sales tax, VAT, or GST', 'creating connected accounts', 'implementing secure key handling' — plus synonyms. A few common natural terms users would say are still missing (e.g. invoices, refunds, disputes, webhooks as a trigger), placing it between the 4 anchor ('good keyword coverage; a few natural terms missing') and 5.

4 / 5

Distinctiveness Conflict Risk

The description is tightly scoped to the Stripe domain with distinct, Stripe-specific triggers (Checkout Sessions, Connect, Stripe Tax, Treasury, connected accounts), so it is unlikely to fire for unrelated skills. It matches 'Clear niche with distinct triggers; minimal conflict risk'.

5 / 5

Total

19

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository
stripe/ai
Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.