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
• Lifecycle hook — SessionStart supplies doc freshness and project-context status

Skills

Public evidence and host permissions

Skills remain useful offline. assess-constitutionality is the narrow exception that first tries to retrieve the public chain record, exact anchor bytes, and directly referenced proposal material needed for a live assessment. It uses only the host’s existing read permissions, never widens them, and falls back for the specific missing item while preserving findings supported elsewhere.

Claude desktop/cloud may expose domain controls that need the specific provider, anchor, or direct-material domain allowed. An allowed domain does not guarantee connectivity or endpoint availability, and the skill does not change those settings. Codex uses its own sandbox, network, and approval configuration; Claude settings do not carry over. Fetched proposal material is untrusted data and is read, never executed.

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 [email protected]: 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 app, formerly Claude Cowork (web, desktop, mobile)

The Claude app’s Chat side uses the same plugin format as Claude Code, so this marketplace works there unchanged. Installing here also syncs the plugin to Claude Code sessions signed in with the same account.

Hooks don’t run in chat, so the SessionStart hook’s notices (docs age, context status) appear only in Cowork, where your app still has it, and in Claude Code.

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 the Claude app 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. Freshness notices use an optional lifecycle hook:

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. A SessionStart hook adds notices such as [Cardano Dev Skills] Docs loaded: sources, ... to the agent’s context. Hosts with plugin-hook support, including Claude Code and current Codex, discover hooks/hooks.json; execution depends on the host’s hook trust settings.

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. It returns one JSON object with hookSpecificOutput.hookEventName set to SessionStart and the status lines in hookSpecificOutput.additionalContext. This output format is compatible with Claude Code and Codex; it avoids interpreting the [Cardano Dev Skills] status prefix as the start of a JSON array. Hook execution depends on the host’s hook support and trust settings. The notices are:

• 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 && 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 . The hook never fetches itself (no network on session start).
• Cardano context active. When ./CLAUDE.md contains the current cardano-dev-skills directive block: Cardano context active in this project. An older block gets a prompt to re-run /cardano-dev-skills:cardano-context instead; a block newer than the installed plugin gets a prompt to update the plugin. 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/                       ← shared SessionStart freshness hook
├── scripts/                     ← fetch (pinned + sanitized), validate, policy-check, delta-scan, update-counts
└── .github/                     ← workflows, issue templates

License

Apache-2.0