> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ckbccc.com/llms.txt - append ".md" to any page URL for its Markdown source.
> Use this file to discover all available pages before exploring further.

---
# Prompting Best Practices
URL: https://docs.ckbccc.com/en/docs/ai-resources/prompting-best-practices
Source: https://raw.githubusercontent.com/ckb-devrel/ccc/refs/heads/master/packages/docs/content/docs/ai-resources/prompting-best-practices.mdx
> A handful of prompts that help you get accurate, working CKB/CCC code faster.


Even with [Agent Skills](https://docs.ckbccc.com/skill.md) 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 [#first-know-which-environment-youre-in]

|               | Skill-native (Cursor / Claude Code, installed via the [setup guide](./set-up-ai-tools)) | 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](./set-up-ai-tools)? Use the web chat version.

## Core principle: verify before writing [#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:

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

```ts
// ✅ 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 [#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 [#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."                                                                   |

<Callout type="info">
  If all five come back wrong, it's probably not a prompting problem — the skill likely isn't loaded. Check [Verify & Troubleshoot](./verify-and-troubleshoot) instead of tweaking your prompt further.
</Callout>

## Three closing habits [#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.