CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

90

1.22x
Quality

88%

Does it follow best practices?

Impact

98%

1.22x

Average score across 3 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

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 skill: an overview body with a task-to-API routing table, clearly signaled one-level references that actually exist, and unusually specific critical rules with a real validation checkpoint for tax. The main weaknesses are embedded time-sensitive version numbers in the main body and the absence of any inline code examples.

Suggestions

Move the SDK version table and the 'Latest Stripe API version: 2026-09-30.endive' line into a dedicated versions/maintenance reference file (or a clearly dated section) so the main body does not silently go stale; keep only a pointer plus the 'always use the latest' rule inline.

Add one short executable snippet in the body (or in a shared reference) showing correct client instantiation, e.g. `stripe = StripeClient("rk_...")` vs. the deprecated `stripe.api_key = ...` pattern, since the StripeClient rule currently names the anti-pattern without showing the replacement.

Make the workflow slightly more explicit: number the core sequence (pick environment → route via table → read reference → check critical rules) and add a checkpoint for webhook verification, mirroring the existing tax-registration validation step.

DimensionReasoningScore

Conciseness

The body is mostly lean and directive (no basics-of-Stripe explanations, no padding), but it embeds time-sensitive version data outside any 'old patterns'/'deprecated' section: "Latest Stripe API version: 2026-09-30.endive", a 7-row latest-SDK-versions table, and a second dated API version ("2026-03-25.dahlia") in the integration_identifier rule. Per the rubric guideline, version numbers and dates in the main body penalize conciseness; this is more than a trimmable minor instance, matching anchor 3 ('mostly efficient but... could be tightened') rather than anchor 4's 'minor instances'.

3 / 5

Actionability

Guidance is largely executable: exact commands ("npm i -g @stripe/cli", "stripe sandbox create", "stripe whoami --format json"), exact parameter names and values ("payment_method_types: ['card_present']", "automatic_tax: { enabled: true }", "allowed_payment_method_types"), and a concrete routing endpoint ("/v2/core/accounts"). It falls short of anchor 5 only because there are no copy-paste code examples in the body itself (e.g., an actual StripeClient instantiation snippet lives only implicitly in the references); it clearly exceeds anchor 3's pseudocode/incompleteness.

4 / 5

Workflow Clarity

A clear implicit sequence exists: choose environment (sandbox vs test mode) → route via the integration table → "Read the relevant reference file before answering any integration question or writing code" → apply the critical rules, with a genuine validation checkpoint in the tax rule ("confirm the user has an active registration. Without one, Stripe calculates and collects no tax") and ordered CLI steps (create sandbox, then "stripe sandbox claim" before MCP). It is not numbered as an explicit workflow and checkpoints are not systematic, so anchor 5 ('explicit validation steps; feedback loops') is not fully met, but anchor 3's 'checkpoints missing or implicit' understates what is present.

4 / 5

Progressive Disclosure

The body is a concise overview with a routing table that splits content across six real, one-level-deep reference files (payments.md, connect.md, billing.md, tax.md, treasury.md, security.md all exist and contain substantive content, verified), plus external docs links. Navigation is easy: each task row names its API and reference path. The only quirk is the table's angle-bracket pseudo-links ("<references/payments.md>") rather than markdown links, which is cosmetic and does not impede navigation, so anchor 5 fits better than anchor 4's 'minor organization gaps'.

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

A strong description: specific, comprehensive, and rich in natural trigger terms with an explicit 'Use when...' clause covering what and when clearly. It is on the long side with minor redundancy (payment-related terms appear in both the what and when lists), but no dimension suffers for it.

DimensionReasoningScore

Specificity

The description enumerates many concrete capability areas with named Stripe APIs and parameters — "separate sandboxes vs the shared test mode sandbox", "Checkout Sessions vs PaymentIntents", "Accounts v2, controller properties", "automatic_tax, product tax codes", "API key management... webhooks, OAuth" — covering environments, payments, Connect, billing, tax, treasury, migration, and security comprehensively. This matches the anchor 'Lists multiple specific concrete actions; comprehensive coverage'; the only nitpick is slight redundancy ("integration options (Checkout, Payment Element)" overlaps "API selection"), which is not a coverage gap, so the score-4 anchor ('minor gaps in coverage') fits worse.

5 / 5

Completeness

It explicitly answers 'what' ("Guides Stripe integration decisions across development and test environment planning... security best practices") and 'when' ("Use when planning, building, modifying, testing, or reviewing any Stripe integration, including...") with concrete trigger phrases. This is a direct match for the score-5 anchor; the score-4 anchor ('when could be more explicit') does not apply since the when-clause enumerates nine specific scenarios.

5 / 5

Trigger Term Quality

The 'Use when...' clause includes natural user phrasings with synonyms: "accepting payments", "building marketplaces", "setting up subscriptions", "collecting sales tax, VAT, or GST", "creating connected accounts", "implementing secure key handling", "choosing a development environment". Coverage of natural terms including synonyms is comprehensive, matching the score-5 anchor; no common variation a Stripe user would say is missing.

5 / 5

Distinctiveness Conflict Risk

It occupies a clear niche (Stripe integration decisions) with Stripe-specific trigger vocabulary ("connected accounts", "Stripe Tax", "sandboxes", "Checkout Sessions"), so it is unlikely to fire for a non-Stripe skill. Third-person voice is used consistently ("Guides..."), so no specificity penalty applies.

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

Path

providers/claude/plugin/skills/stripe-best-practices/SKILL.md

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.