From cardano-dev-skills
Scaffolds a new Cardano dApp project with on-chain (Aiken) and off-chain (Evolution SDK, Mesh SDK, PyCardano, or cardano-client-lib) toolchains, using Cardano Foundation templates or custom use cases.
How this skill is triggered — by the user, by Claude, or both
Slash command
/cardano-dev-skills:scaffold-projectThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!-- Documentation lookup path: ${CLAUDE_SKILL_DIR}/../../docs/sources/ -->
Take a developer from "I want to build a Cardano dApp" to a working project skeleton: a chosen use case, directory layout, config files, devnet wiring, a starter validator, and the first off-chain transaction. The skill is read-only — it prints the canonical structure and file contents as guidance for the developer (or the agent) to write into their own working directory.
plutus.json) wired up correctlyconnect-walletsuggest-toolingsetup-devnetwrite-validatorbuild-transactionplutus.json blueprint emitter. Other on-chain languages exist; see references/stack-decision.md for why they are deferred.plutus.json is the contract between on-chain and off-chain. Aiken emits this natively at build time. The off-chain code loads it and never re-derives script hashes manually..env.example (committed) and .env (ignored). Provider API keys live in env vars.^), no tildes (~), no latest — exact versions only. Commit lockfiles.npm view <pkg> version (or pip index versions <pkg> / equivalent) at scaffold time and embed the exact returned value. The skill's layout files show current-at-time-of-writing values as defaults, but the agent must re-check.onchain/ and offchain/ (and optionally frontend/) into sibling directories with a shared plutus.json reference path.aiken check && aiken build produces plutus.json and npm install && npm run typecheck && npm run build (or the language equivalent) completes with zero errors. If the developer says "just scaffold it" without verification, still run the build commands and report the result — silent broken scaffolds waste hours downstream.Drive the scaffolding by what the contract does, not by the stack. Ask the developer to pick from one of the 21 reference use cases or describe their own.
The 5 curated use cases have hand-reviewed implementations across on-chain Aiken and all four off-chain stacks:
The other 16 use cases (bet, auction, crowdfund, vault, storage, simple-wallet, pricebet, payment-splitter, lottery, constant-product-amm, upgradable-proxy, factory, decentralized-identity, editable-nft, anonymous-data, atomic-transaction) have Aiken on-chain coverage upstream; off-chain code is agent-generated in-session.
For full descriptions and source-code paths see references/use-cases.md. For an end-to-end flagship walkthrough of vesting (the recommended first project) see references/vesting-walkthrough.md.
If the developer's case doesn't match any entry, treat it as a custom use case: read the closest upstream Aiken validator under ${CLAUDE_SKILL_DIR}/../../docs/sources/cardano-use-case-templates/<name>/onchain/aiken/ as a structural model and generalise from there.
Map the team's primary language and constraints to one of four stacks. Use this short decision matrix; for more depth see references/stack-decision.md and hand off to suggest-tooling if the developer wants a broader tour.
| Stack | On-chain | Off-chain | Pick when |
|---|---|---|---|
| 1 | Aiken | Evolution SDK | TypeScript team, want a pure-JS toolchain with composable types |
| 2 | Aiken | Mesh SDK | TypeScript team, want the broadest tutorial coverage |
| 3 | Aiken | PyCardano | Python backend, data team, scripting-heavy |
| 4 | Aiken | cardano-client-lib | Java/Kotlin team, JVM ecosystem |
Search the bundled docs for SDK details:
${CLAUDE_SKILL_DIR}/../../docs/sources/aiken/ — Aiken language docs${CLAUDE_SKILL_DIR}/../../docs/sources/aiken-stdlib/ — Aiken standard library${CLAUDE_SKILL_DIR}/../../docs/sources/evolution-sdk/ — Evolution SDK docs${CLAUDE_SKILL_DIR}/../../docs/sources/mesh-sdk/ — Mesh SDK docs${CLAUDE_SKILL_DIR}/../../docs/sources/pycardano/ — PyCardano docs${CLAUDE_SKILL_DIR}/../../docs/sources/cardano-client-lib/ — cardano-client-lib docsBefore scaffolding the layout, settle which network the project targets first. The choice changes .env.example, the off-chain provider initialisation, and the faucet URL.
| Network | Best for | Trade-off |
|---|---|---|
| Yaci DevKit (recommended default) | Learning, fast iteration, isolated testing | Instant finality; differs from mainnet behaviour around eras and slot timing |
| Preview testnet | Pre-mainnet integration testing | Slower than devnet (~20s blocks); shared state |
| Preprod testnet | Pre-production rehearsal | Mirrors mainnet parameters most closely |
| Mainnet | Production deployment only | Real funds — see guardrail below |
Mainnet guardrail. If the developer asks to scaffold with mainnet as the active network, stop and warn explicitly: scaffolded "hello world" validators must not be deployed to mainnet — bugs in untested code can lock real funds permanently. Default to a testnet. Only proceed with mainnet after the developer has explicitly acknowledged the warning, and even then, set the project's default CARDANO_NETWORK env to a testnet so a misconfigured run never accidentally lands on mainnet.
For Yaci DevKit launch details, hand off to setup-devnet. Faucets for preview and preprod live at https://docs.cardano.org/cardano-testnets/tools/faucet (the selector on the page picks preview vs preprod).
Default is yes. Ask the developer if they want to opt out.
When a frontend is included, scaffold a sibling Next.js App Router application that:
plutus.json) but does its own tx building client-sideWhen a frontend is excluded, the scaffold is backend-only (Aiken + the chosen off-chain SDK).
In all cases, hand off to connect-wallet for the actual CIP-30 wallet integration content. Do not duplicate it here.
Two shapes are supported. Pick once; do not mix.
Single-repo (flat). Use when: solo developer, prototyping, a library, or contract-only project. Everything sits at the repo root: aiken.toml, validators/, and the off-chain code in a language-appropriate location.
Monorepo (split). Use when: full-stack product, more than one developer, on-chain and off-chain evolve at different speeds. Sibling top-level directories:
my-project/
├── onchain/ # Aiken project, emits plutus.json
├── offchain/ # SDK code, consumes plutus.json
└── frontend/ # Optional Next.js app; only if Step 4 = yes
If the developer says "I prefer single-repo," respect that override even when the project looks like it wants a monorepo. Document the trade-off briefly: single-repo is simpler now but harder to split later.
Pick the matching reference file for the chosen stack and the chosen shape, and print the tree as a code block for the developer to materialize:
references/layout-aiken-evolution.mdreferences/layout-aiken-mesh.mdreferences/layout-aiken-pycardano.mdreferences/layout-aiken-cclib.mdEach reference shows both single-repo and monorepo variants, plus the optional frontend layout. Use the variants matching Steps 4 and 5.
Frame the output as "Generate the following structure" followed by the tree and then individual file contents. Do not invoke a writing tool from inside this skill.
Read references/config-templates.md and emit the templates relevant to the chosen stack and network:
aiken.toml — on-chain manifest (all stacks).gitignore — shared patterns plus stack-specific entries.env.example — network-specific placeholders, Blockfrost project ID, faucet pointer, devnet URLpackage.json + tsconfig.jsonpyproject.tomlpom.xmlEach emitted file preserves inline annotations (# or // comments) explaining each field. The annotations are part of the deliverable; they tell the developer what each line does so they can adapt it.
Versions follow the two-tier pinning policy (Key principle 10):
aiken.toml): paste the pinned values from the layout file directly. They are current and update with each skill revision. aiken new writes most of these for you.package.json, pyproject.toml, pom.xml): before writing the manifest, run npm view <pkg> version (or pip index versions <pkg>, or look up Maven Central for cclib) for each direct dep, and embed the exact returned value. The layout file shows defaults that are current-at-time-of-writing; refresh them. Do not write ^X.Y.Z or version placeholders.Yaci DevKit is the default local network. Do not duplicate setup details here; point the developer at the setup-devnet skill for installation, configuration, and pre-funded wallet handling.
What this skill provides in the scaffold:
.env.example includes a CARDANO_NETWORK toggle (defaults to a testnet) and a YACI_STORE_URL=http://localhost:10000 entryscripts/dev-up.sh (or equivalent) that launches Yaci DevKit; the script body is one line and points to the setup-devnet skill for the full commandThen hand off to setup-devnet for the actual launch.
End the scaffold with the starter on-chain and off-chain code for the use case picked in Step 1.
Starter validator. For a curated use case (simple-transfer, vesting, escrow, token-transfer, htlc), use the upstream Aiken validator from ${CLAUDE_SKILL_DIR}/../../docs/sources/cardano-use-case-templates/<name>/onchain/aiken/validators/ as the starting point. For an agent-generated use case, use the closest upstream validator as a model. For a fully custom case, fall back to the trivial "always succeeds when signed by the datum's owner" validator under each layout reference. After printing, hand off to write-validator for real business logic.
First transaction. A minimal off-chain script in the chosen SDK that: loads the plutus.json blueprint, builds a transaction that exercises the validator (lock for vesting/escrow/HTLC; transfer for simple-transfer; etc.), signs it with the dev key, submits it, and prints the resulting tx hash. The exact code lives in the stack's layout reference and (for vesting) in references/vesting-walkthrough.md. After printing, hand off to build-transaction for richer transaction logic.
If the developer enabled a frontend in Step 4, also note: "For the wallet-connect path see connect-wallet."
Do not call the scaffold done until the project actually builds. This step exists because broken scaffolds eat hours downstream.
Run, in order:
cd onchain
aiken check # compiles AND runs unit tests; both must pass
aiken build # produces plutus.json
cd ../offchain
npm install # or pip install -e . / mvn install — stack-dependent
npm run typecheck # or mypy / mvn compile
npm run build # or python -m build / mvn package
A working scaffold reaches the end with zero errors. If anything fails:
aiken check): verify aiken.toml lists the right dependency pins (compare against the stack's layout reference). Check that validators/*.ak imports resolve — most common cause is missing the sidan-lab/vodka dep when copying a CF use-case validator.npm install fails on EEXISTS/peer-deps: the version pinned in the layout reference is stale. Re-run npm view <pkg> version and update.npm run typecheck fails on unknown identifiers: the off-chain SDK had a breaking change. Search ${CLAUDE_SKILL_DIR}/../../docs/sources/<sdk>/ for the current API signatures and adjust the starter snippet.Report the final state to the developer plainly: "Scaffold built successfully. Run npm run <use-case> to exercise it end-to-end against Yaci DevKit (see setup-devnet)." Or, if something is still failing, explain what and why before handing off.
Aiken emits CIP-57 plutus.json as part of aiken build. This is the single source of truth that bridges on-chain and off-chain code. Every off-chain SDK in the v1 stack matrix can load this file directly:
applyParamsToScript(blueprint.validators[0].compiledCode, []) plus validatorToAddressapplyParamsToScript and serializePlutusScript consume the compiled CBORplutus.json and constructs PlutusV3Script from the CBORplutus.json via PlutusBlueprintLoader + PlutusBlueprintUtilIn every stack layout reference, the off-chain starter snippet shows the exact load pattern. The pattern is the same shape across all four: open the file, pick the named validator, hand the CBOR to the SDK. The developer never copies a script hash by hand.
These defaults are non-negotiable. The scaffold prints them; do not let a developer talk you into removing them.
.env is in .gitignore from the first commit.env.example ships placeholder values only; no real keys.keys/ directory that is also gitignoredpackage-lock.json / pnpm-lock.yaml, poetry.lock, Maven dependency tree pinned via <dependencyManagement>references/use-cases.md — the 21 reference use cases, curated vs agent-generated, with source-code pointersreferences/vesting-walkthrough.md — flagship end-to-end walkthrough across all four off-chain stacks, plus the frontend story; includes a full PyCardano implementationreferences/stack-decision.md — decision aid for picking one of the four stacks; brief notes on deferred stacks and why they are not v1 defaultsreferences/config-templates.md — annotated aiken.toml, package.json, pyproject.toml, pom.xml, .gitignore, .env.example (with per-network Blockfrost / faucet guidance)references/layout-aiken-evolution.md — stack 1: Aiken + Evolution SDK directory tree, skeletons, optional Next.js frontendreferences/layout-aiken-mesh.md — stack 2: Aiken + Mesh SDK directory tree, skeletons, optional Next.js frontendreferences/layout-aiken-pycardano.md — stack 3: Aiken + PyCardano directory tree, skeletons, optional sibling Next.js frontendreferences/layout-aiken-cclib.md — stack 4: Aiken + cardano-client-lib directory tree, skeletons, optional sibling Next.js frontendsetup-devnet for Yaci DevKit launch and configurationsuggest-tooling for deeper SDK and language trade-off discussionwrite-validator for real on-chain logicbuild-transaction for real transaction-building logicconnect-wallet for a Next.js / React frontend with wallet integrationnpx claudepluginhub cardano-foundation/cardano-dev-skills --plugin cardano-dev-skillsProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.