Skip to content

README.md

Latest commit

 

History

History
210 lines (142 loc) · 11.1 KB

README.md

File metadata and controls

210 lines (142 loc) · 11.1 KB
Raw

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.
  • Hooks that auto-consult bundled context before the agent reaches for 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
  • Hooks — SessionStart reports doc freshness; a UserPromptSubmit auto-consultation hook is in development

Skills

Skill What it does
cardano-context Install a per-project Cardano directive into CLAUDE.md so the agent reliably consults 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 (recommended)

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 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 / other agents

git clone https://github.com/cardano-foundation/cardano-dev-skills.git
cd your-project
ln -s ../cardano-dev-skills/skills .agents/skills

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

Even with the plugin installed globally, Claude sometimes answers Cardano questions from training data instead of consulting these skills and bundled docs. Run the cardano-context skill once per project to install a durable directive:

/cardano-context

What it does:

  • Writes a version-tagged block into the project's CLAUDE.md (default ./CLAUDE.md). Claude Code re-injects CLAUDE.md into every conversation turn, so the directive survives compaction and applies on every new session.
  • The block tells Claude to treat training data as potentially stale for Cardano, to bias toward invoking cardano-dev-skills:* skills, to search ${CLAUDE_PLUGIN_ROOT}/docs/sources/ before falling back on memory, and to cite what it used.
  • Commit CLAUDE.md and teammates inherit the directive on clone.
  • Re-running is safe: same version is a no-op; older versions are atomically replaced.

Automatic mechanisms (no setup)

The plugin also tries to set the context automatically. In a Claude Code session:

  1. Session start. A SessionStart hook reports doc freshness — you'll see [Cardano Dev Skills] Docs loaded: <n> sources, ... at the top of every session in any directory.
  2. 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 auto-invokes that skill.
  3. Doc consultation (in development). A UserPromptSubmit hook scans your prompt for Cardano-specific keywords (aiken, plutus, cip-XXXX, ogmios, drep, …) and reminds the agent to consult bundled docs before training data or the web.

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."

We're tracking which prompts fail to auto-consult so the keyword set + skill triggers can be tuned over time (observability layer in development).

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: Refresh via: /plugin marketplace update cardano-dev-skills.
  • 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.
  • Cardano context nudge. When cwd looks like a project (.git, .claude, or existing CLAUDE.md) but has no block: Tip: run /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)

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" or run /give-feedback: 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/
├── registry/sources.yaml        ← canonical source list
├── skills/                      ← developer skills (flat layout)
├── docs/sources/                ← extracted upstream docs (auto-refreshed)
├── hooks/                       ← session and prompt hooks
├── scripts/                     ← fetch (pinned + sanitized), validate, policy-check, delta-scan, update-counts
└── .github/                     ← workflows, issue templates

License

Apache-2.0