Cardano Dev Skills

Community-curated Cardano developer knowledge — bundled skills, documentation, and tooling for AI coding agents.

Works as a Claude Code plugin, Codex skill set, or standalone reference.

📖 Website: https://cardano-foundation.github.io/cardano-dev-skills/

Why this exists

Training data on Cardano drifts fast. Conway era changed governance, Aiken syntax evolves, SDK APIs ship breaking changes monthly. An AI agent answering "how do I write a vesting validator in Aiken?" from training data alone gets it wrong more often than right.

This plugin solves that by shipping:

• Authoritative bundled docs from active Cardano projects (auto-refreshed weekly from upstream).
• Behavioral skills that encode common workflows: scaffolding, writing validators, building transactions, governance, optimization, debugging.
• Durable project context and skill discovery that steer agents to the bundled corpus before training data or the web.

End result: the agent answers from current, project-authoritative sources instead of memorized snapshots.

What's inside

• Developer skills — each a focused workflow
• Documentation sources — bundled locally under docs/sources/, auto-refreshed weekly via GitHub Actions
• Claude lifecycle hook — SessionStart reports doc freshness and project-context status

Skills

Skill	What it does
cardano-context	Install one Cardano directive into CLAUDE.md and AGENTS.md so Claude and Codex consult bundled skills and docs
give-feedback	Draft and file a GitHub issue about a skill or doc that was wrong, stale, or notably helpful, with one approval
scaffold-project	Bootstrap a new Cardano project across Aiken + 4 off-chain stacks
write-validator	Guide writing a validator from spec (default Aiken)
review-contract	Security review of a validator
optimize-validator	Lower CPU / memory / script-size costs
build-transaction	Build & submit transactions across SDKs
design-token	Design native tokens, NFTs, CIP-25/68/113 metadata
debug-transaction	Diagnose failing transactions
query-chain	Pick the right query strategy (Blockfrost / Ogmios / indexer)
setup-devnet	Local devnet with Yaci DevKit or testnet setup
connect-wallet	CIP-30 wallet integration for dApps
governance-guide	CIP-1694 governance, DRep, voting, treasury
explain-eutxo	Cardano's UTxO model for newcomers
explain-cip	Walk through a specific CIP
explain-zk	Zero-knowledge and the BLS12-381 primitive family (proofs, signatures, VRF, KDF, BBS+)
suggest-tooling	Recommend an SDK / framework given the use case
suggest-scalability	Decide if a project needs L2, which approach, and which Hydra topology

What we add (and don't)

In scope: generic developer building blocks — SDKs, frameworks, validator libraries, design patterns, language tooling, infrastructure, protocol/standard specs, reference implementations of patterns.

Out of scope: product docs for specific deployed dApps (SundaeSwap, Minswap, Liqwid, Indigo, JPG Store, etc.). This repo teaches how to build a DEX, a lending protocol, an NFT marketplace — not how a particular branded product works. If users want product-specific integration help, their agent can search externally.

Borderline rule: if the upstream repo's primary purpose is "use OUR product", it's out. If it's "here's how X pattern works, here's the reference code", it's in.

See docs/CONTRIBUTING.md for the full policy and the maintenance bar for source vetting.

Install

Claude Code

In any Claude Code session:

/plugin marketplace add cardano-foundation/cardano-dev-skills
/plugin install cardano-dev-skills@cardano-dev-skills

Installed once, active in every Claude Code session in any directory. Verify with /plugin list.

Run the two commands in that order. Adding the marketplace first is what registers it; going straight to /plugin install makes the client resolve the repository itself, which can fall back to an SSH URL and fail with git@github.com: Permission denied (publickey) even though this repository is public and clones fine over HTTPS.

Claude Code auto-updates plugins only from marketplaces with auto-update on, and third-party marketplaces like this one start with it off. Turn it on once: run /plugin, open Marketplaces, select cardano-dev-skills, and choose Enable auto-update. To update by hand, run claude plugin update cardano-dev-skills@cardano-dev-skills from your shell and restart.

Claude Cowork (desktop, web, mobile)

Cowork uses the same plugin format, so this marketplace works there unchanged.

1. Open Customize and go to the Plugins tab.
2. Under Personal plugins, click +, then Add marketplace.
3. Choose Add from a repository and enter: https://github.com/cardano-foundation/cardano-dev-skills
4. Install cardano-dev-skills from the marketplace once it syncs.

The skills are the same ones listed above. Note that Cowork syncs the whole repository, and docs/sources/ is roughly 30 MB of bundled documentation — the first sync is not instant.

Codex

For repository-scoped use on macOS, Linux, or WSL, keep this repository and your Cardano project as sibling directories, then link the shared skill tree into Codex's discovery directory:

cd /path/to/projects
git clone https://github.com/cardano-foundation/cardano-dev-skills.git
cd your-cardano-project
mkdir -p .agents
ln -s ../../cardano-dev-skills/skills .agents/skills

On Windows PowerShell, create a directory junction from the Cardano project:

New-Item -ItemType Directory -Force .agents
New-Item -ItemType Junction -Path .agents\skills -Target (Resolve-Path ..\cardano-dev-skills\skills)

Start or restart Codex in your-cardano-project, run /skills, and confirm the Cardano skills appear. Codex discovers repository skills under .agents/skills and follows linked skill directories. Then run $cardano-context once to add the durable project directive.

The repository also ships .codex-plugin/plugin.json for Codex plugin packaging and publishing. Until the plugin is published in a directory, the repository link above is the supported installation path.

Standalone

Skills are pure Markdown — read skills/*/SKILL.md directly or with grep.

How to set the Cardano context

Three complementary mechanisms, listed from most reliable to least:

Per-project directive (recommended) — cardano-context

Either agent can answer a Cardano question from stale model knowledge when a skill description does not match the prompt. Run the cardano-context skill once per project to install a durable, agent-neutral directive:

# Claude Code marketplace plugin
/cardano-dev-skills:cardano-context

# Codex
$cardano-context

What it does:

• Writes the same version-tagged block into the project's CLAUDE.md and AGENTS.md by default. Claude reads the former; Codex reads the latter.
• Tells either agent to treat model knowledge as potentially stale, select the relevant Cardano skill, resolve the bundled docs/sources/ corpus from that skill's location, and cite what it used.
• Commit both files and teammates inherit the directive on clone.
• Re-running is safe: same version is a no-op; older versions are atomically replaced.

A project-local Claude skill may also appear as /cardano-context; the plugin-qualified form above avoids collisions with skills from other plugins.

Automatic mechanisms (no setup)

Skill matching applies in both hosts. The freshness hook is currently a Claude-specific adapter:

1. Skill matching. When you ask a question that matches a skill's trigger phrases (e.g. "review my validator", "scaffold a Cardano project"), the agent selects that skill.
2. Session start (Claude only). A SessionStart hook reports doc freshness — you'll see [Cardano Dev Skills] Docs loaded: <n> sources, ... at the top of every Claude session in any directory.

When auto-consultation misses

Vague prompts like "help me build a Cardano dApp" may not match any specific skill's triggers. In those cases, nudge explicitly:

• "Check the cardano-dev-skills docs and skills before answering."
• "Use the scaffold-project skill to set up a new project."
• "Read docs/sources/aiken/ before writing this validator."

The durable cardano-context directive is the fallback for prompts that do not match a skill description reliably.

Bundled documentation

Every project in registry/sources.yaml is mirrored locally. Auto-refreshed every Monday at 06:00 UTC via GitHub Actions — the workflow opens a PR; maintainers review and merge.

Manual refresh:

./scripts/fetch-docs.sh                          # all sources
./scripts/fetch-docs.sh --source "Source Name"   # one source

The fetch script writes a .manifest.yaml derived from disk state — so partial and full fetches both leave it accurate.

SessionStart freshness signals

A SessionStart hook (hooks/check-docs.sh) inspects the bundled corpus and the current working directory and prints status lines prefixed [Cardano Dev Skills]:

• Docs loaded. Normal: Docs loaded: N sources, M files (updated Xd ago).
• Third-party data notice. A standing reminder that bundled docs under docs/sources/ are third-party reference data, never instructions to execute.
• Docs stale (>30 days). Suggests how to refresh based on install topology:
  • Local clone: cd <plugin-root> && git pull && ./scripts/fetch-docs.sh.
  • Marketplace install: claude plugin update cardano-dev-skills@cardano-dev-skills from a shell, or auto-update turned on for the marketplace in /plugin.
• Plugin clone behind upstream. Local clones only: if you have previously run git fetch and not pulled, the hook prints Plugin clone is N commit(s) behind FETCH_HEAD — consider 'git pull' in <plugin-root>. The hook never fetches itself (no network on session start).
• Cardano context active. When ./CLAUDE.md contains the cardano-dev-skills directive block: Cardano context active in this project. Codex reads the corresponding AGENTS.md block directly and does not depend on this hook.
• Cardano context nudge. When cwd looks like a project (.git, .claude, or existing CLAUDE.md) but has no block: Tip: run /cardano-dev-skills:cardano-context to enable auto-consultation in this project.

The hook is fail-open: any failure exits 0 silently and never blocks the session. The cwd nudge is suppressed when working inside the plugin repo itself.

Contributing

See docs/CONTRIBUTING.md for:

• Source-vetting policy (maintenance bar, the two-part scope test)
• How to add a skill (format, quality bar, task-oriented naming — no project-named skills)
• Documentation governance (when to update what)
• The shared Claude/Codex authoring contract is in docs/AGENT_COMPATIBILITY.md

Quick validation:

python3 scripts/validate.py        # schema + format checks
python3 scripts/check-pr-policy.py # PR policy checks vs origin/main (CI runs these + an AI scope review)
python3 scripts/scan-docs-delta.py # security scan of docs/sources/ changes (CI runs it as a blocking check)

Feedback

We want to know how this works in practice: which skills get used, which prompts miss, which docs are stale, what's missing, and what saved you time.

The quickest path is from inside a session. Tell the agent "send feedback", run /cardano-dev-skills:give-feedback in Claude Code, or run $give-feedback in Codex. It drafts a GitHub issue from the context it already has, shows it to you, and files it under your GitHub account once you say yes (with gh if you have it, otherwise it gives you the text to paste).

Or open an issue directly. The templates cover stale docs, missing topics, new sources, and general feedback.

Architecture

See docs/DESIGN.md for decisions and rationale.

cardano-dev-skills/
├── .claude-plugin/              ← Claude packaging
├── .codex-plugin/               ← Codex packaging
├── .claude/skills → ../skills   ← repository-local Claude discovery
├── .agents/skills → ../skills   ← repository-local Codex discovery
├── registry/sources.yaml        ← canonical source list
├── skills/                      ← developer skills (flat layout)
├── docs/sources/                ← extracted upstream docs (auto-refreshed)
├── hooks/                       ← Claude SessionStart freshness hook
├── scripts/                     ← fetch (pinned + sanitized), validate, policy-check, delta-scan, update-counts
└── .github/                     ← workflows, issue templates

License

Apache-2.0