@paystage/skill 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +22 -2
  2. package/SKILL.md +52 -0
  3. package/package.json +25 -4
package/README.md CHANGED
@@ -1,3 +1,23 @@
1
- # Temporary Holding Version
1
+ # @paystage/skill
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A skill for agents that are about to spend money.
4
+
5
+ Drop `SKILL.md` into your agent's skills directory (Claude Code, Cursor, or anything that reads
6
+ skill files) and the agent gains one instruction it did not have before: **evaluate the 402
7
+ challenge before signing**.
8
+
9
+ It ships no code and no dependency. The work is done by the hosted endpoint or the MCP server,
10
+ both of which are free to call:
11
+
12
+ ```bash
13
+ npx -y -p @paystage/mcp paystage-mcp
14
+ # or https://api.paystage.xyz/mcp (Streamable HTTP, listed as a remote server in the MCP registry)
15
+ ```
16
+
17
+ ## Why a skill rather than a library
18
+
19
+ The failure this prevents is not a parsing bug — it is an agent doing what it was told. A library
20
+ has to be wired in by someone; a skill is read by the agent itself, at the moment it is deciding.
21
+ The next best thing to a seatbelt is the instruction to check one.
22
+
23
+ MIT.
package/SKILL.md ADDED
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: paystage
3
+ description: Check an x402 payment against a policy before signing it. Use whenever an agent is about to pay an HTTP 402 challenge, is told to "just pay", or receives a 402 it does not recognise. Returns pay, review or do_not_pay with the rule that fired.
4
+ ---
5
+
6
+ # PayStage — check before you sign
7
+
8
+ You are about to spend money. Before any signature, evaluate the challenge.
9
+
10
+ ## The one rule
11
+
12
+ **Never sign a payment the evaluator has not returned `pay` for.** `review` means stop and ask the
13
+ human. `do_not_pay` means refuse and say which rule fired.
14
+
15
+ ## How to call it
16
+
17
+ The hosted endpoint needs no key and no signup:
18
+
19
+ ```bash
20
+ curl -s https://api.paystage.xyz/v1/evaluate_mcp_payment \
21
+ -H 'content-type: application/json' \
22
+ -d '{"payment_required": <the 402 challenge>, "policy": <the operator policy>}'
23
+ ```
24
+
25
+ MCP clients can use the server instead:
26
+
27
+ ```bash
28
+ npx -y -p @paystage/mcp paystage-mcp # stdio
29
+ # or connect to https://api.paystage.xyz/mcp (Streamable HTTP)
30
+ ```
31
+
32
+ ## What a verdict looks like
33
+
34
+ ```json
35
+ { "decision": "do_not_pay", "reasons": [{ "code": "payee_not_allowed", "detail": "…" }] }
36
+ ```
37
+
38
+ Quote the reason code back to the human. It is the only part that explains *why*, and it is the
39
+ part a policy fix acts on.
40
+
41
+ ## Rules of engagement
42
+
43
+ 1. **A missing policy is not permission.** If no policy exists, ask for one — do not invent limits.
44
+ 2. **Do not retry a `do_not_pay` with a changed amount.** That is the attack the gate exists for.
45
+ 3. **Do not pay to learn.** The evaluation is free; settlement is not.
46
+ 4. **Report the verdict, not just the outcome.** "Paid" without the decision is unauditable.
47
+
48
+ ## What this does not do
49
+
50
+ It does not hold keys and cannot sign. It does not know what the seller does after payment. Post-
51
+ settlement reversals and off-chain promises are outside its scope, and saying so is part of using
52
+ it honestly.
package/package.json CHANGED
@@ -1,6 +1,27 @@
1
1
  {
2
2
  "name": "@paystage/skill",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Agent skill: check an x402 payment against a policy before signing it",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/base-buzz/paystage.git",
9
+ "directory": "packages/skill"
10
+ },
11
+ "files": [
12
+ "SKILL.md",
13
+ "README.md"
14
+ ],
15
+ "keywords": [
16
+ "x402",
17
+ "agent-skills",
18
+ "claude-skills",
19
+ "agent-payments",
20
+ "preflight",
21
+ "402"
22
+ ],
23
+ "scripts": {
24
+ "build": "node -e \"process.exit(0)\"",
25
+ "test": "node -e \"process.exit(0)\""
26
+ }
27
+ }