feat: implement multi-skill architecture for AI coding assistants and add AI Resources documentation

packages/docs/app/llms.txt/route.ts

@@ -17,8 +17,7 @@ Notes for AI agents:
 
 - All links below are absolute URLs. Append \`.md\` to any docs page URL to get its raw Markdown version (e.g. ${siteUrl}/en/docs/getting-started/introduction.md).
 - The entire documentation concatenated into a single file: ${siteUrl}/llms-full.txt
-- Agent skill (product-specific operating guidance): ${siteUrl}/skill.md
-- Blog (release notes & tutorials): ${siteUrl}/en/blog/rgbpp-new-sdk-preview
+- Agent skills index (product-specific operating guidance, split by topic): ${siteUrl}/skill.md
 - Chinese versions of every page are available by replacing \`/en/\` with \`/zh/\` in the URL.
 - API reference: https://api.ckbccc.com | Playground: https://live.ckbccc.com | Source: https://github.com/ckb-devrel/ccc
 
@@ -31,6 +30,7 @@ Notes for AI agents:
 - [Core Packages](${siteUrl}/en/docs/packages/core-packages): Core primitives, aggregated entry points, and wallet connectors.
 - [Protocol Support Layer](${siteUrl}/en/docs/packages/protocol-sdks): Protocol-level SDKs — Spore, UDT, SSRI, and Lumos patches.
 - [Wallet Integrations](${siteUrl}/en/docs/packages/wallet-integrations): Connect any wallet through one unified \`Signer\` interface.
+- [AI Resources](${siteUrl}/en/docs/ai-resources): How this documentation is built for AI agents, and how developers should configure and prompt their own AI tools to use it correctly.
 
 ## Common tasks (recommended reading paths)
 

packages/docs/app/skill.md/route.ts

@@ -0,0 +1,105 @@
+import { gitConfig, siteUrl } from '@/lib/shared';
+
+export const revalidate = false;
+
+const repoSlug = `${gitConfig.user}/${gitConfig.repo}`;
+const rawBase = `https://raw.githubusercontent.com/${repoSlug}/refs/heads/${gitConfig.branch}/skills`;
+
+interface SkillEntry {
+  name: string;
+  role: 'hub' | 'spoke';
+  dependsOn: string;
+  summary: string;
+}
+
+// Kept in sync manually with the `skills/` directory at the repo root —
+// update this list whenever a skill is added, renamed, or removed there.
+const skills: SkillEntry[] = [
+  {
+    name: 'ckb-ccc-fundamentals',
+    role: 'hub',
+    dependsOn: 'none',
+    summary:
+      'Cell model, package selection, address handling, Shannon/CKB amount conversion, the KnownScript enum, and how to look up exact API signatures (DeepWiki/Context7/api.ckbccc.com) or navigate docs.ckbccc.com. Load this first for any CKB/CCC task.',
+  },
+  {
+    name: 'ckb-ccc-signer-setup',
+    role: 'spoke',
+    dependsOn: 'ckb-ccc-fundamentals',
+    summary: 'Connecting a wallet in a React/Next.js dApp, or creating a private-key Signer in a Node.js backend; the supported wallet matrix; message signing/verification.',
+  },
+  {
+    name: 'ckb-ccc-transactions',
+    role: 'spoke',
+    dependsOn: 'ckb-ccc-fundamentals, ckb-ccc-signer-setup',
+    summary: 'Composing and sending CKB transactions — outputs, completeInputsByCapacity/completeFeeBy ordering, cell deps, and querying the chain. The base pattern ckb-ccc-udt and ckb-ccc-spore build on.',
+  },
+  {
+    name: 'ckb-ccc-udt',
+    role: 'spoke',
+    dependsOn: 'ckb-ccc-fundamentals, ckb-ccc-transactions',
+    summary: 'Issuing (Single-Use-Seal), transferring, and reading metadata for UDT/xUDT fungible tokens.',
+  },
+  {
+    name: 'ckb-ccc-spore',
+    role: 'spoke',
+    dependsOn: 'ckb-ccc-fundamentals, ckb-ccc-transactions',
+    summary: 'Creating, transferring, and melting Spore protocol NFTs/DOBs, including cluster handling and the DOB/0 + DOB/1 content-type conventions.',
+  },
+  {
+    name: 'ckb-ccc-playground',
+    role: 'spoke',
+    dependsOn: 'ckb-ccc-fundamentals, ckb-ccc-transactions',
+    summary: 'The CCC Playground (live.ckbccc.com) — the @ckb-ccc/playground module, UI controls, and the two ways to share runnable code.',
+  },
+  {
+    name: 'ckb-ccc-examples-finder',
+    role: 'spoke',
+    dependsOn: 'ckb-ccc-fundamentals',
+    summary: 'Locating existing, ready-made CKB/CCC example code by category instead of writing something from scratch or guessing at patterns.',
+  },
+];
+
+const preamble = `# CCC Agent Skills (CKB / CCC development)
+
+> Modular, machine-readable operating guidance for AI coding assistants building on CKB with the CCC SDK. Each skill below is a directory with a SKILL.md (YAML frontmatter + Markdown body), following the Agent Skills format (https://agentskills.io/specification).
+
+## Install
+
+If your tool/agent can run a shell command, install with the [\`skills\` CLI](https://github.com/vercel-labs/skills) (supports Cursor, Claude Code, GitHub Copilot, Windsurf, Codex, and 60+ other agents — auto-discovers the \`skills/\` directory and writes each skill to the right path for your tool):
+
+\`\`\`bash
+npx skills add ${repoSlug}
+\`\`\`
+
+If your tool/agent can only fetch URLs (no shell access — browser-based agents, plain chat models, etc.), fetch the raw \`SKILL.md\` files directly from the table below. Always fetch \`ckb-ccc-fundamentals\` first, then the spoke skill matching the task.
+
+## Notes for AI agents
+
+- Always load \`ckb-ccc-fundamentals\` first — it's the hub skill; every spoke skill assumes it's already loaded.
+- Then load the spoke skill(s) matching the task at hand — see the table below, or each skill's own \`description\` frontmatter field for exactly when to use it.
+- Tools that natively support multiple skill files/directories (e.g. Claude Code) should fetch the whole \`skills/\` directory at once.
+- Tools that only support a single rule/context file should load \`ckb-ccc-fundamentals\` as the default and fetch additional skill URLs on demand, per the task.
+- Raw file URLs below always reflect the latest version on the \`${gitConfig.branch}\` branch.
+- Full docs: ${siteUrl} — docs index: ${siteUrl}/llms.txt — API reference: https://api.ckbccc.com
+
+## Skills
+
+| Skill | Role | Depends on | SKILL.md |
+| --- | --- | --- | --- |
+${skills
+  .map((s) => `| \`${s.name}\` | ${s.role} | ${s.dependsOn} | ${rawBase}/${s.name}/SKILL.md |`)
+  .join('\n')}
+
+## Skill summaries
+
+${skills.map((s) => `### ${s.name}\n\n${s.summary}\n`).join('\n')}`;
+
+export function GET() {
+  return new Response(preamble, {
+    headers: {
+      'Content-Type': 'text/markdown; charset=utf-8',
+      'Cache-Control': 'public, max-age=3600, must-revalidate',
+    },
+  });
+}

packages/docs/content/docs/ai-resources/index.mdx

@@ -0,0 +1,37 @@
+---
+title: AI Resources
+description: Make Cursor, Claude Code, Copilot, and other AI assistants write correct CKB/CCC code — set them up, prompt them well, and verify the result.
+icon: Bot
+---
+
+import { Wrench, MessageSquare, ShieldCheck } from 'lucide-react';
+
+This section is for developers who use an AI coding assistant (Cursor, Claude Code, GitHub Copilot, Windsurf, ChatGPT, …) to build on CKB with CCC. Its only goal: make your assistant write **correct** CCC code instead of confidently wrong code.
+
+Why the extra effort is needed: CKB uses the **Cell model** (a generalized UTXO model), which barely appears in the Ethereum-heavy data most LLMs were trained on. Left unguided, an assistant will produce CCC code that looks right but isn't — wrong transaction ordering, invented methods, `number` where CKB needs `bigint`, EVM-style assumptions. CCC ships a set of machine-readable [Agent Skills](/skill.md) — one hub skill (`ckb-ccc-fundamentals`) plus a spoke skill per task area (signer setup, transactions, UDT, Spore, playground, examples) — that encode the CCC-specific rules; these pages show you how to feed them to your tool and get reliable output.
+
+## Do this once, then it just works
+
+1. **[Set up your tool](./ai-resources/set-up-ai-tools)** — one-time config so your assistant always loads CCC's rules (under 2 minutes).
+2. **[Verify it worked](./ai-resources/verify-and-troubleshoot)** — ask one canary question to confirm the rules actually loaded. Don't skip this: a silently-failed setup looks configured but isn't.
+3. **[Prompt it well](./ai-resources/prompting-best-practices)** — per request, name the exact package and point it at the relevant guide.
+
+<Callout type="info">
+  New here? Start with **[Set Up Your AI Tools](./ai-resources/set-up-ai-tools)** and do the 2-minute setup for the tool you use — everything else builds on it.
+</Callout>
+
+## Pages in this section
+
+<Cards cols={2}>
+  <Card title="Set Up Your AI Tools" icon={<Wrench />} href="./ai-resources/set-up-ai-tools">
+    Copy-paste config for Cursor, Claude Code, GitHub Copilot, Windsurf, and ChatGPT — plus which CCC links to point your assistant at.
+  </Card>
+
+  <Card title="Prompting Best Practices" icon={<MessageSquare />} href="./ai-resources/prompting-best-practices">
+    A before/after example, prompt templates by task, and the specific CKB mistakes AI makes — with the one-line correction for each.
+  </Card>
+
+  <Card title="Verify & Troubleshoot" icon={<ShieldCheck />} href="./ai-resources/verify-and-troubleshoot">
+    Canary questions to confirm your setup actually works, and a step-by-step decision tree for when the assistant still gets CKB wrong.
+  </Card>
+</Cards>

packages/docs/content/docs/ai-resources/index.zh.mdx

@@ -0,0 +1,37 @@
+---
+title: AI 资源
+description: 让 Cursor、Claude Code、Copilot 及其他 AI 助手写出正确的 CKB/CCC 代码——配置工具、写好提示词、验证结果。
+icon: Bot
+---
+
+import { Wrench, MessageSquare, ShieldCheck } from 'lucide-react';
+
+本部分面向使用 AI 编程助手（Cursor、Claude Code、GitHub Copilot、Windsurf、ChatGPT……）在 CKB 上基于 CCC 开发的开发者。其唯一目标是：让你的助手写出**正确**的 CCC 代码，而不是自信满满地写出错误代码。
+
+为什么需要额外花这些功夫：CKB 采用 **Cell 模型**（泛化的 UTXO 模型），这在 LLM 训练数据中占绝大比重的以太坊相关内容里几乎不存在。如果不加引导，助手生成的 CCC 代码看起来像那么回事，但实际是错的——交易顺序不对、方法凭空捏造、该用 `bigint` 的地方用了 `number`、沿袭 EVM 风格的前提假设。CCC 提供了一套机器可读的 [Agent Skills](/skill.md)——包含一个 hub skill（`ckb-ccc-fundamentals`）和每个任务领域对应的 spoke skill（signer 配置、交易、UDT、Spore、playground、示例）——其中编码了 CCC 特有的规则；本部分页面会告诉你如何将这些 skill 喂给工具，并稳定获得正确输出。
+
+## 一次配置，之后无需操心
+
+1. **[配置你的工具](./ai-resources/set-up-ai-tools)**——一次性配置，让你的助手始终加载 CCC 的规则（不到 2 分钟）。
+2. **[验证配置是否生效](./ai-resources/verify-and-troubleshoot)**——用一个金丝雀问题确认规则确实被加载了。不要跳过这一步：静默加载失败的配置看起来配好了，但实际上没有。
+3. **[写好提示词](./ai-resources/prompting-best-practices)**——每次请求时，明确指出要用的包名，并将其引导至相关的指南页面。
+
+<Callout type="info">
+  新手？从 **[配置你的工具](./ai-resources/set-up-ai-tools)** 开始，花 2 分钟为你使用的工具完成配置——其余内容都建立在这个基础上。
+</Callout>
+
+## 本部分页面
+
+<Cards cols={2}>
+  <Card title="配置 AI 工具" icon={<Wrench />} href="./ai-resources/set-up-ai-tools">
+    Cursor、Claude Code、GitHub Copilot、Windsurf、ChatGPT 的配置粘贴方案——以及应该将哪些 CCC 链接指向你的助手。
+  </Card>
+
+  <Card title="提示词最佳实践" icon={<MessageSquare />} href="./ai-resources/prompting-best-practices">
+    改造前后的示例、按任务分类的提示词模板，以及 AI 常犯的 CKB 特定错误——并附上每种错误的单行修正方法。
+  </Card>
+
+  <Card title="验证与故障排查" icon={<ShieldCheck />} href="./ai-resources/verify-and-troubleshoot">
+    用于确认配置是否真正生效的金丝雀问题，以及当助手仍然答错 CKB 相关问题时的排查步骤。
+  </Card>
+</Cards>

packages/docs/content/docs/ai-resources/meta.json

@@ -0,0 +1,8 @@
+{
+  "title": "AI Resources",
+  "pages": [
+    "set-up-ai-tools",
+    "prompting-best-practices",
+    "verify-and-troubleshoot"
+  ]
+}

packages/docs/content/docs/ai-resources/meta.zh.json

@@ -0,0 +1,8 @@
+{
+  "title": "AI 资源",
+  "pages": [
+    "set-up-ai-tools",
+    "prompting-best-practices",
+    "verify-and-troubleshoot"
+  ]
+}