CtrlK
BlogDocsLog inGet started
Tessl Logo

stripe-best-practices

Guides Stripe integration decisions across 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, restricted keys, webhooks, OAuth). Use when building, modifying, or reviewing any Stripe integration, including 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.

91

1.86x
Quality

89%

Does it follow best practices?

Impact

95%

1.86x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No findings from the security scan

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

SKILL.md
Quality
Evals
Security

Quality

Content

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

The body is a well-structured, actionable Stripe routing guide that uses progressive disclosure effectively, offloading domain detail to real reference files while keeping concrete commands and guardrails inline. Its main weakness is mild verbosity and inline time-sensitive version tables that could be trimmed or relocated.

Suggestions

Tighten the payment_method_types rule by dropping the Dashboard/conversion rationale and keeping only the directive plus the payment_method_configurations/excluded_payment_method_types alternatives.

Move the API-version date and per-language SDK version table into a clearly labeled 'versioning' or 'deprecated/old patterns' section, or into a reference file, so time-sensitive data does not penalize conciseness.

Add one minimal copy-paste code snippet (e.g. instantiating StripeClient and creating a Checkout Session with integration_identifier) to lift actionability from mostly-executable to fully copy-paste ready.

DimensionReasoningScore

Conciseness

The body is largely lean — a routing table, a critical-rules list, and terse CLI commands — but contains over-explanation (e.g. the payment_method_types rule's 'enables you to configure payment method settings from the Dashboard and dynamically display the most relevant eligible payment methods to each customer to maximize conversion') and inline time-sensitive version/date tables that the guidelines flag as a conciseness cost when not in a deprecated section. This fits 'efficient; minor instances of over-explanation that could be trimmed' (4) rather than the fully lean anchor (5) or mostly-efficient-with-notable-padding (3).

4 / 5

Actionability

Provides concrete, executable guidance: specific CLI commands ('npm i -g @stripe/cli', 'stripe sandbox create', 'stripe whoami --format json'), exact parameter names ('automatic_tax: { enabled: true }', 'payment_method_types: ["card_present"]', 'integration_identifier'), and a task→API routing table. It is mostly executable with minor gaps — full copy-paste code is sparse and implementation detail is deferred to reference files — fitting the 4 anchor better than the fully copy-paste-ready 5 anchor or the pseudocode/incomplete 3 anchor.

4 / 5

Workflow Clarity

The integration-routing table gives a clear decision sequence (what you're building → recommended API → reference file) with 'Read the relevant reference file before answering' as the next step, and the critical-rules section supplies guardrails including a validation checkpoint for the risky automatic_tax case ('confirm the user has an active registration'). This matches 'clear sequence with most checkpoints present; minor validation gaps' (4); it is not a fully checkpointed feedback-loop workflow (5), and the validation present keeps it above the no-validation 3 anchor.

4 / 5

Progressive Disclosure

SKILL.md is a concise overview with well-signaled one-level-deep references — the routing table maps each task to a real reference file (<references/payments.md>, connect.md, billing.md, tax.md, treasury.md, security.md), all of which exist in ./references/, and details are appropriately split out rather than inlined. This matches the anchor for a clear overview with well-signaled one-level-deep references and easy navigation; it is not merely 'mostly clear with minor gaps' (4).

5 / 5

Total

17

/

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.

The description is exemplary: third-person voice, comprehensive concrete actions, a broad set of natural trigger terms with synonyms, and an explicit 'Use when...' clause. It clearly distinguishes the skill's Stripe-specific niche with minimal conflict risk.

DimensionReasoningScore

Specificity

Lists multiple concrete actions across comprehensive domains — 'API selection (Checkout Sessions vs PaymentIntents)', 'Connect platform setup (Accounts v2, controller properties)', 'tax and registrations (Stripe Tax, automatic_tax, product tax codes)', 'Treasury financial accounts', 'migrating from deprecated Stripe APIs', and 'security best practices (API key management, restricted keys, webhooks, OAuth)'. This matches the anchor for listing multiple specific concrete actions with comprehensive coverage; it is not merely naming a domain with minimal actions (3) and goes beyond several actions with minor gaps (4).

5 / 5

Completeness

Clearly answers both 'what' ('Guides Stripe integration decisions across...') and 'when' with an explicit 'Use when building, modifying, or reviewing any Stripe integration, including...' clause bearing concrete trigger phrases. This matches the anchor that explicitly answers both what AND when with concrete triggers; it is not a case where 'when' is only weakly implied (3) or could be more explicit (4).

5 / 5

Trigger Term Quality

The 'Use when...' clause includes natural phrases users say with synonyms: '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.' This matches the anchor for comprehensive coverage of natural terms including synonyms; it is not missing common variations (3) or only a few terms short (4).

5 / 5

Distinctiveness Conflict Risk

Occupies a clear Stripe-integration niche with distinct, domain-specific triggers (Connect, Treasury, Stripe Tax, RAKs) that are unlikely to fire for unrelated skills. This matches the anchor for a clear niche with distinct triggers and minimal conflict risk; it is not merely mostly distinct with minor overlap (4).

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.

Validation16 / 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.