Prompting Best Practices

Even with Agent Skills installed, how you ask still decides how good the answer is. This page keeps only the patterns that actually move accuracy — copy and use directly.

First, know which environment you're in

	Skill-native (Cursor / Claude Code, installed via the setup guide)	Web chat (ChatGPT / DeepSeek / etc., not installed)
How to use it	Just describe what you need — the tool routes itself to the right skill	Describe what you need, and also include `https://docs.ckbccc.com/skill.md`, asking it to "fetch first, then answer" — with no local files to route from, that link is what lets it find the right skill

Haven't run the install command from the setup guide? Use the web chat version.

Core principle: verify before writing

Without a source, the model falls back on EVM training patterns and guesses; give it a source, and it has something to check itself against. Same task, the only difference is this one sentence:

Vague prompt: "Write a function using CCC that sends 100 CKB from the connected wallet."
Verified prompt: "…Before writing the code, confirm CKB-specific rules first (amount units, transaction ordering, etc.) — don't rely on training memory." (In web chat, add https://docs.ckbccc.com/skill.md so it can route itself to the right rules.) The code each prompt produces differs in exactly these lines:

// ❌ Vague prompt
capacity: 100 * 1e8                         // number, not bigint
await tx.completeFeeBy(signer);             // fee computed before inputs are filled
await tx.completeInputsByCapacity(signer);

// ✅ Verified prompt
capacity: ccc.fixedPointFrom(100)           // bigint, in Shannon
await tx.completeInputsByCapacity(signer);  // inputs must come before fee
await tx.completeFeeBy(signer);

One rule is enough to remember:

In skill-native environments, just describe the task in your own words — no need to know or type any skill name, the tool routes itself based on each skill's description.
In web chat there's no local file to route from, so a skill.md link is the substitute for that ability.

Task templates

Web chat version = skill-native version + "fetch https://docs.ckbccc.com/skill.md first" — that one rule is more useful than memorizing the 7 rows below.

Task	What to ask (skill-native)
Not sure which package	"I'm building `<a React app / a Node.js script / a custom UI>` — which `@ckb-ccc/*` package should I use?"
Implement a known guide	"Implement `<feature>` following the `<connect-wallets / compose-transactions / UDT>` guide."
Debug an error	"I'm getting this error: `<error>`. Does it match a known cause in the relevant skill's common-pitfalls table?"
Review AI-generated code	"Review this against the CCC pre-submit checklist and mark each item PASS/FAIL — don't just give a summary."
Exact method signature	"What are the parameter types for `<method>`? Check `api.ckbccc.com`, don't guess."
Find an existing example	"Is there an existing example for `<feature>` I can adapt instead of writing it from scratch?"
Verify in Playground first	"Format this as a runnable script for `live.ckbccc.com` (CCC Playground) so I can test it on testnet first."

The rows above are single-feature prompts, narrow enough that the tool naturally matches the right skill. "Build a whole app from scratch" is too generic a phrasing, though — the AI will likely just treat it as an everyday web-dev task and never think to check the CCC rules at all. So these two examples add one generic nudge (still no specific skill name required): web chat substitutes the link, skill-native substitutes a line like "use the CCC-related skill(s)":

xUDT issuance/transfer app

Web chat:

Please visit https://docs.ckbccc.com/skill.md first, then build a React web app for me:
after connecting a wallet, users can issue an xUDT token and also transfer that token.

Skill-native:

Use the CCC-related skill(s) to build a React web app for me:
after connecting a wallet, users can issue an xUDT token and also transfer that token.

On-chain guestbook

Web chat:

Please visit https://docs.ckbccc.com/skill.md first, then use the CCC SDK to build a React web app
on Nervos CKB: after connecting a wallet, users can post a short message, which gets written into
the cell data of a CKB transaction so it's permanently on-chain. The homepage lists all messages and
their senders' addresses, newest first.

Skill-native:

Use the CCC-related skill(s) to build a React web app on Nervos CKB:
after connecting a wallet, users can post a short message, which gets written into the cell data
of a CKB transaction so it's permanently on-chain. The homepage lists all messages and their
senders' addresses, newest first.

5 common mistakes, one-line fixes

If you spot any of these symptoms, just send the matching line back to the AI and have it regenerate:

Symptom	One-line fix
Amount is a `number` or has decimals	"CKB amounts are always a bigint in Shannon. Construct them with `ccc.fixedPointFrom()`, not a float — please fix."
Fee computed before inputs are filled	"The order must be outputs → completeInputsByCapacity → completeFeeBy → sendTransaction — please reorder."
Next.js component errors, missing `"use client"`	"This file uses `ccc.Provider`/a CCC hook, so it must be a client component — add `\"use client\"` as the first line."
UDT transfer silently drops change	"For UDT transfers, call `udt.completeBy(tx, signer)` first to add UDT inputs and change, then `completeInputsByCapacity` for CKB capacity — please fix the order."
Node script imports from `@ckb-ccc/core`	"Backend scripts should import from `@ckb-ccc/shell` (which re-exports core) — please switch it."

If all five come back wrong, it's probably not a prompting problem — the skill likely isn't loaded. Check Verify & Troubleshoot instead of tweaking your prompt further.

Three closing habits

Run mainnet-bound transactions on ClientPublicTestnet first — don't trust a "should work" answer.
For protocol-level questions (e.g. what a DOB's contentType should be), don't trust a single example file — have the AI cross-check the official protocol docs instead of "copying whatever example it found."
Don't trust what the AI said earlier in the conversation. CCC packages keep iterating and API fields change with them — the AI having "said it once" doesn't mean it's still correct. E.g. if it looked up which package to use back at message 3, and you rely on that again at message 50, don't let it just repeat its earlier answer — ask it to verify the choice, not recall it.
Skills themselves get updated too. In skill-native environments (Cursor / Claude Code, etc.), run npx skills update ckb-devrel/ccc occasionally so your local copy doesn't fall behind the latest rules — but note update only refreshes skills you've already installed, it won't pull in newly added ones. If we add a new skill (say a future ckb-ccc-fiber), you'll need to re-run npx skills add ckb-devrel/ccc --all to get it. Web chat doesn't have this problem — it fetches skill.md fresh every time, so it's always current.