桥匠：SkillHub Pay 改造发布 Skill

概述

你可以直接这样说

• 把这个普通 Skill 改成腾讯 SkillHub Pay Skill，保留原 slug。
• 我的 402 返回了 code_url，怎么让用户直接看到微信二维码？
• 上传前帮我检查这个 Pay Skill 包会不会被审核拦住。

当前版本：v1.2.7。

说明：我们也是刚接触 SkillHub 的支付 Skill，这个转换器来自相光域这次把 16 个 Skill 跑通审核、上架、二维码付款和履约后的实战整理。它不一定完善，也不保证覆盖腾讯后续所有规则变化。如果你在审核、二维码、付款、查单、履约或文档字段上遇到问题，欢迎把反馈告诉我们；我们会根据真实反馈继续修改。

v1.2.6 更新说明：本 Skill 自身按免费 Skill 发布，不启用 SkillPay 收费，也不创建订单。它整理的是“把别的普通 Skill 改造成腾讯 SkillHub Pay Skill”的流程；按已跑通的微信 Agent Pay X402 流程补齐通用 Agent 付款兜底：优先使用 weixinpay_pay(paymentCode=<WeixinPay-Required>)；如果聊天客户端不能直接渲染支付卡片或二维码，就展示同一笔订单的 checkout_url，让用户打开订单页后直接看到微信付款二维码，并用 payment_status_url 查询同一订单状态。轮询、重试和履约都必须复用原始 X-Out-Trade-No 与完全相同的请求体，不得再生成第二个二维码、第二个订单，也不得在未确认支付成功前交付付费结果。

Use this skill when the user wants to turn an ordinary Skill into a Tencent SkillHub / SkillPay Pay Skill, or wants a batch of Skills prepared, checked, packaged, uploaded, reviewed, or corrected for that platform.

The desired outcome is boring and concrete: a preserved original Skill, a converted copy, a clean ZIP, synchronized versions, a callable production service, universal-Agent payment instructions, and a read-back status that separates local readiness, platform review, listing, payment, fulfillment, settlement, and withdrawable funds.

This adapter Skill itself is a free operational guide and local packaging/audit helper. It does not charge users, create orders, collect payment, or require a Product ID for itself.

“桥匠”这个名字取的是桥与工匠：桥，是把普通 Skill 渡到 SkillHub Pay 发布流程；匠，是把结构、边界、证据和审核材料一处处收紧。它帮你少走弯路，但不会替你绕过平台审核、商户权限、真实付款和最终人工判断。

Evidence and disclaimer

Evidence comes from local files, generated manifests, script outputs, service smoke tests, official SkillHub CLI/API responses, and platform dashboard read-back when the user authorizes external work. A passing local run proves only the checked files and commands at that time; it does not prove future Tencent rule compatibility, platform approval, real users, paid calls, settlement, withdrawable funds, or legal/commercial suitability.

Hard boundaries

• Do not treat a normal Skill listing as income. Pay Skill means per-call charging after platform eligibility, payment service behavior, merchant setup, and actual user calls.
• Do not invent or expose credentials, merchant secrets, API keys, private certificates, cookies, verification codes, or payment private keys. A Skill may document where secrets are expected at runtime, but the package must not contain them.
• Do not claim upload, approval, listing, revenue, settlement, or withdrawability without fresh read-back evidence for that exact state.
• Before external mutation, use the official CLI/API if currently available and sufficient. If not, use the logged-in platform UI only within the user-authorized scope.
• For approval/listing actions, act only on the target slug and target version. Old rejected versions often remain in the review list; do not approve, delete, or rewrite unrelated versions.
• If the platform requires login, CAPTCHA, KYC, merchant binding, payment permission, or a user choice, stop at the smallest blocker instead of bypassing it.
• Do not make WorkBuddy or any other named Agent client mandatory. weixinpay_pay is an optional enhanced channel; the baseline path is HTTPS plus a user-visible checkout_url and payment_status_url.
• A successful payment is not automatically a completed task. If the paid response unlocks an agent_task_specification, the Agent must execute it and deliver the actual result before claiming fulfillment.

Convert by input type

1. Already has a production HTTPS service
   • Keep the real service_url.
   • Add or verify /health, a task endpoint, and preferably /openapi.json.
   • Reuse an already proven shared payment gateway when it can safely isolate slug, version, Product ID, amount, request hash, and order state. Do not duplicate merchant-signing code in every Skill package.
   • Document request/response shape, exact 402 headers, both payment channels, same-body order retry, order lookup, fulfillment, and exception handling in SKILL.md.
2. Has only local scripts
   • Wrap the smallest useful path as an HTTP JSON service.
   • Keep deterministic local tests for the script and one service smoke test.
   • Do not package loopback, LAN, temporary tunnel, or local-only endpoints as the production endpoint.
3. Is prompt-only or document-only
   • Do not make it a Pay Skill by metadata alone.
   • Either create a callable service that performs the paid work, or report that it can be a normal Skill until a real service exists.
4. Calls third-party APIs
   • Keep provider credentials out of the package.
   • Document required environment variables and failure modes.
   • Add a preflight check that fails clearly when runtime configuration is absent.
5. Is already a Pay Skill
   • Compare against the most recent approved Skill in the same platform account when available.
   • Prefer copying the approved structure over inventing a new schema.
   • Sync SKILL.md, metadata, scripts, manifest, ZIP name, upload version, and dashboard version.
6. Batch conversion
   • Preserve originals.
   • Work in a separate converted-output directory.
   • Use stable ordered filenames such as PaySkill-01-名称-vX.Y.Z.zip.
   • Keep an upload checklist mapping display name, slug, version, ZIP path, product ID, and status.

Required Pay Skill content

Every converted Pay Skill should make these points easy for a reviewer and a new developer to see:

• Skill identity: display name, slug, version, author/team, short description.
• Production service: exact HTTPS service entry, endpoint path, health check, and response format.
• Pricing and product identity: price model and platform Product ID when it already exists. Do not invent these.
• Payment flow: wechat_agent_pay_x402, first request without an order header, HTTP 402 with WeixinPay-Required and X-Out-Trade-No, optional weixinpay_pay, universal checkout_url plus payment_status_url, and same-body retry after trade_state=SUCCESS.
• Order safety: bind slug, version, amount and request hash to the order; reject changed requests with ORDER_REQUEST_MISMATCH; reject unpaid orders with PAYMENT_NOT_CONFIRMED; never create a second order while polling or retrying the first.
• Fulfillment mode: say whether HTTP 200 contains the final business result or an agent_task_specification that the Agent must continue executing. Never present the latter as the final result.
• Secret boundary: runtime environment variables and server-side signing only; no merchant private key or certificate in the package.
• Deployment boundary: production URL is stable; local and temporary tunnel URLs are not acceptable upload endpoints.
• User-facing examples: up to the platform limit, practical for new users, professional enough for teams, and free of restricted or risky claims for that Skill.

For detailed checks, read [references/tencent-skillhub-pay-rules.md](references/tencent-skillhub-pay-rules.md).

Workflow

1. Discover current platform rules
   • Check official SkillHub tutorial, install doc, CLI/API, and the account’s current enterprise/merchant status before assuming an old rule still applies.
   • If the platform exposes a CLI/API, prefer that path for dry-runs, uploads, and read-back.
2. Audit the source Skill
   • Run scripts/audit_pay_skill.py <skill-folder-or-zip>.
   • Add --forbid <term> for terms the user banned from examples or docs.
   • Fix all error items before packaging. Treat warning items as explicit tradeoffs.
3. Convert in a copy
   • Preserve the original folder.
   • Add the minimum service wrapper, documentation, metadata, and examples needed for the actual Skill type. Prefer the existing proven gateway over a second payment implementation.
   • Choose one fulfillment mode: server-executed result, or paid unlock of an executable Agent task specification.
   • Keep names graceful but clear: literary tone is fine, but reviewers and new users must still understand the function.
4. Sync versions
   • Use the version in SKILL.md as the source of truth unless the user says otherwise.
   • Align top-level version, metadata version, script/service version, release manifest, ZIP name, upload form, and platform dashboard.
5. Package
   • Run scripts/package_pay_skill.py <converted-folder> --out <zip-path>.
   • This creates a clean ZIP from a temporary copy, regenerates RELEASE_MANIFEST.json, excludes common caches/junk, and refuses likely secret files.
6. Verify locally
   • unzip -tq <zip>.
   • Run the platform CLI dry-run when available.
   • Run service /health and one task endpoint smoke test when the service is in scope. The first valid call must return a real 402 contract, not a mock success.
   • Verify both client paths in docs: AI payment card when weixinpay_pay exists, and QR/link checkout when it does not.
   • For a user-authorized real-payment acceptance run, confirm payment, retry the exact original body with the original X-Out-Trade-No, and verify the returned result is actually fulfilled. Do not require a second payment for that order.
   • Re-run audit_pay_skill.py on the final ZIP.
7. Upload and read back
   • Upload only after local gates are clean or the remaining warning is deliberately accepted.
   • Read back exact slug/version/status from the platform.
   • Understand status progression in plain Chinese: safety scan, team admin review, platform review, approved/listed.
   • Team admin review may be the owner’s own team admin gate; approve only the intended latest versions.

Output format for a conversion handoff

Report in this order:

1. Converted ZIPs created or updated.
2. Slug/version/name mapping.
3. Local checks run and result.
4. Platform upload/read-back status if authorized.
5. Payment and fulfillment evidence, kept separate.
6. Remaining blockers, if any, using the platform’s original feedback text.

Keep the handoff human: short, concrete, and careful about what has actually happened.

Executable helpers

Use these commands when the user asks for local adaptation or a pre-upload check:

python scripts/audit_pay_skill.py /absolute/path/to/skill-or-zip
python scripts/audit_pay_skill.py /absolute/path/to/skill-or-zip --forbid 上市 --forbid 融资
python scripts/package_pay_skill.py /absolute/path/to/converted-skill --out /absolute/path/to/PaySkill-name-v1.0.0.zip
unzip -tq /absolute/path/to/PaySkill-name-v1.0.0.zip

If the audit reports problems, fix those before upload. If only warnings remain, state which warnings are deliberate and why.

Failure handling and uncertainty

• If official CLI/API behavior differs from this skill, follow the current official rule and note the drift.
• If a required production service, merchant binding, Product ID, or payment permission is missing, stop at that gate; do not fill placeholders.
• If platform feedback is available, quote the short original reason and edit against that reason rather than guessing.
• If a local check passes but platform status is unknown, report only local readiness.
• If a platform version is approved/listed, still do not claim revenue, settlement, or withdrawable funds without separate payment evidence.