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.

84

1.78x
Quality

87%

Does it follow best practices?

Impact

100%

1.78x

Average score across 2 eval scenarios

SecuritybySnyk

Low

Low-risk findings worth noting

The canonical home for this skill is stripe-best-practices in stripe/ai

SKILL.md
Quality
Evals
Security

Quality

Content

75%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 skill: concrete, opinionated rules with real reference files behind each domain. Its main weaknesses are stale-prone inlined version data (API version date and SDK version table) and reference links that target web URLs rather than the bundled files.

Suggestions

Move the 'Latest Stripe API version' and 'Latest SDK versions' table into a reference file (or a clearly dated 'current versions' section) so the body stays evergreen and does not carry token cost that rots.

Change routing-table links to relative paths (e.g., [references/payments.md](references/payments.md)) so they resolve to the bundled files rather than docs.stripe.com.

Make the pre-launch validation explicit in sequence (e.g., a final step: 'Before go-live, walk the Go Live Checklist') so the webhook and registration checkpoints read as ordered gates rather than standalone rules.

DimensionReasoningScore

Conciseness

The body is mostly lean and Stripe-specific, but it inlines time-sensitive version data outside any 'old patterns'/'deprecated' section: 'Latest Stripe API version: 2026-08-26.dahlia', a full 7-language 'Latest SDK versions' table (Ruby 19.6.0 … .NET 52.4.0), and a dated reference to 'API version 2026-03-25.dahlia'. These stale-prone version numbers cost tokens now and will rot, which fits the 'mostly efficient but includes some unnecessary content' anchor rather than the 'minor trim' anchor above it.

3 / 5

Actionability

Guidance is fully concrete and executable: exact commands ('npm i -g @stripe/cli', 'stripe sandbox create', 'stripe whoami --format json'), exact endpoints ('Accounts v2 (/v2/core/accounts)'), and exact parameter-level rules ('automatic_tax: { enabled: true }', "payment_method_types: ['card_present']", 'allowed_payment_method_types', 'integration_identifier'). The explicit deprecated-pattern list ('stripe.api_key = …', 'Stripe.setApiKey', 'stripe.Key = …') makes the rules copy-checkable; absence of full code samples is appropriate for an instruction/routing skill.

5 / 5

Workflow Clarity

The integration routing table plus 'Read the relevant reference file before answering any integration question or writing code' gives a clear, unambiguous decision sequence, and the tax rule includes a real pre-flight checkpoint ('confirm the user has an active registration' before enabling automatic_tax). Not a 5 because other checkpoints are implicit rather than explicit — the webhook fulfillment gating and the go-live checklist are stated as rules or afterthoughts rather than sequenced validation steps. Not a 3 because the sequence that exists is coherent and the main failure mode (most common Stripe Tax mistake) is explicitly guarded.

4 / 5

Progressive Disclosure

The body is a true overview routing to six one-level-deep reference files (payments.md, connect.md, billing.md, tax.md, treasury.md, security.md), all of which exist in ./references/ and are clearly signaled per task in the routing table. Not a 5 because the routing links point at absolute web URLs ('[references/payments.md](https://docs.stripe.com/references/payments.md)') instead of relative paths to the bundled files, so navigation can misdirect to the hosted page rather than the local reference.

4 / 5

Total

16

/

20

Passed

Description

100%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.

An exemplary description: it states what the skill does with concrete, jargon-anchored specifics and gives an explicit, trigger-rich 'Use when' clause covering the full Stripe surface. Every clause carries information with no filler, and the scope is unmistakably distinct from non-Stripe skills.

DimensionReasoningScore

Specificity

It enumerates many concrete capability areas with specific artifacts: '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)', 'tax and registrations (Stripe Tax, automatic_tax, product tax codes)', 'security best practices (API key management, API key permissions, webhooks, OAuth)'. This matches the 'multiple specific concrete actions; comprehensive coverage' anchor; the abstract opener 'Guides Stripe integration decisions' is fully backed by enumerated specifics, so 4's 'minor gaps' does not fit.

5 / 5

Completeness

Both halves are explicit: 'what' is 'Guides Stripe integration decisions across [nine enumerated domains]' and 'when' is 'Use when planning, building, modifying, testing, or reviewing any Stripe integration, including [eight concrete trigger phrases]'. This mirrors the anchor-5 example structure exactly; 4's 'when could be more explicit' does not apply.

5 / 5

Trigger Term Quality

The 'Use when' clause is dense with natural user phrasing including synonyms: 'accepting payments', 'processing payments', 'building marketplaces', 'setting up subscriptions', 'collecting sales tax, VAT, or GST', 'creating connected accounts', 'implementing secure key handling', 'choosing a development environment'. This matches the comprehensive-with-synonyms anchor; secondary terms (refunds, invoices) are missing but the anchor is coverage of natural terms, which is met.

5 / 5

Distinctiveness Conflict Risk

The skill occupies a clear niche (Stripe integration guidance) with domain-locked triggers ('Checkout Sessions', 'PaymentIntents', 'Stripe Tax', 'connected accounts', 'automatic_tax') that no generic payments, tax, or security skill would claim. Minimal conflict risk; matches the clear-niche anchor.

5 / 5

Total

20

/

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.