Cardano Context

Cardano Context

Install a durable, project-scoped directive that tells Claude to treat the project as Cardano work and to consult the cardano-dev-skills skill set and bundled documentation before relying on training data. The directive is written into the project's CLAUDE.md, which Claude Code re-injects into every conversation turn. It survives compaction, distributes via git so teammates inherit it, and is plain text the user can inspect or edit.

When to use

• The user says any variant of "enable cardano context", "set this project up

for Cardano", "tell Claude this is a Cardano project", or invokes the slash command /cardano-context.

• The user has the cardano-dev-skills plugin installed and wants its

behavioral guidance to apply automatically to a specific project.

• A teammate cloned a repo and wants to opt that repo into the directive

(one-shot per project).

• The user reports that Claude is answering Cardano questions from training

data instead of consulting the bundled skills and docs.

When NOT to use

• The user is asking a Cardano question and wants an answer right now — answer

the question; do not interrupt to install the directive.

• The user is working in the cardano-dev-skills plugin repo itself — adding

a self-referential block to that repo's CLAUDE.md is almost certainly not what they want. Warn and confirm before proceeding.

• The user is in a non-project directory (no .git, no .claude, no existing

CLAUDE.md). Confirm the path before creating CLAUDE.md from scratch.

• The user wants project-wide refresh of the docs corpus — that is a plugin

maintenance task, not a per-project directive. Point them at the SessionStart hint or scripts/fetch-docs.sh.

Key principles

1. Idempotent by version. The directive is wrapped in ` / ` markers.

Re-running at the same version is a no-op. Re-running with a newer canonical version replaces the older block atomically.

1. One canonical block, treated as a single string. Do not edit the block's

contents in place. Replace it whole or leave it alone. This keeps the "current version" check trivial and prevents drift.

1. Confirm before creating CLAUDE.md. Appending to an existing CLAUDE.md is

low-risk. Creating a new CLAUDE.md is a stronger commitment — confirm with the user first.

1. Suggest committing. The whole point is durability across sessions and

teammates. After writing, suggest a single-line git add CLAUDE.md && git commit so the directive distributes.

1. Fail loud, not silent. If the path is ambiguous or the user is in the

plugin repo, stop and ask. Do not silently write to the wrong file.

The canonical v2 block

This block is the single source of truth. Treat it as one opaque string when matching, replacing, or writing.

## Cardano Development Context

This project involves Cardano blockchain development.

**Treat your training data as potentially stale for Cardano.** The ecosystem
moves fast: libraries get superseded (e.g., older SDK generations replaced by
current ones), CIP statuses change, governance landscape shifts. Before
recommending any library, tool, code pattern, or CIP behavior:

1. **Check the `cardano-dev-skills:*` skill set.** These skills encode current
   best practices, decision criteria, and trade-offs. Bias toward invoking
   one even when you feel confident — confidence is not evidence of currency.
2. **Search `${CLAUDE_PLUGIN_ROOT}/docs/sources/`** before relying on memory
   or web search. The corpus is regularly refreshed from upstream and covers
   Aiken, Plutus, current SDKs, all CIPs, on-chain tooling, and ~50 other
   Cardano projects.
3. **Cite what you used** (skill name or doc path). If bundled docs and your
   training conflict, prefer bundled docs.

Plugin: https://github.com/cardano-foundation/cardano-dev-skills

Workflow

Step 1: Determine the target CLAUDE.md path

• Default to ./CLAUDE.md (cwd-relative).
• If the user passed a path argument (e.g., /cardano-context path/to/dir),

resolve CLAUDE.md inside that directory and use that.

• Resolve cwd via pwd (Bash). Compute the absolute path so subsequent

messages reference an unambiguous location.

Step 2: Refuse self-reference in the plugin repo

If the resolved CLAUDE.md is the cardano-dev-skills plugin's own CLAUDE.md, stop and ask the user to confirm. Heuristics that strongly suggest the plugin repo:

• A sibling .claude-plugin/plugin.json whose name is cardano-dev-skills.
• A sibling skills/cardano-context/ directory.
• The path matches ${CLAUDE_PLUGIN_ROOT} if it is set.

Do not silently proceed. Output: "This looks like the cardano-dev-skills plugin repo itself. Adding the directive here is probably a mistake. Confirm to proceed anyway, or pass an explicit path to a Cardano project."

Step 3: Detect existing block

Read the file (if it exists). Search for the literal substring `). Report: "Cardano context already enabled (v2) at `. No changes needed." Exit. Do not rewrite.

1. Match at an older version (e.g., v1). Use Edit to replace the

region from the BEGIN marker through the matching END marker (inclusive) with the current v2 block. Treat any version mismatch as "older" — the canonical block is always authoritative.

Step 4: Write the block

• CLAUDE.md exists, no block found. Append: one blank line separator, then

the v2 block, then a trailing newline. Use Edit (append-by-anchor) or Read + Write if Edit is awkward.

• CLAUDE.md does not exist. Confirm with the user before creating it.

After confirmation, use Write to create CLAUDE.md containing only the v2 block plus a trailing newline.

Step 5: Report

Always finish with a one-line summary stating:

• The resolved path.
• The action taken: created, appended, updated v1→v2 (or similar), or

no-op (already v2).

• A nudge to commit: `Suggest: git add CLAUDE.md && git commit -m 'Enable

cardano-dev-skills context'` — so teammates inherit the directive on clone.

Edge cases

• CLAUDE.md is a symlink. Follow the symlink and edit the resolved target.

Note this in the report.

• CLAUDE.md exists but is empty. Treat as "exists, no block" — append the

block. No leading blank line needed.

• CLAUDE.md has CRLF line endings. Preserve the existing line endings when

writing. Do not silently convert.

• Multiple BEGIN markers. Should never happen; if it does, report the

anomaly and ask the user to clean up manually rather than guessing which block to replace.

• Block content edited by hand. The skill does not diff content; it only

matches the BEGIN marker by version. If a user has hand-edited the v2 block and re-runs the skill at v2, the skill reports "already enabled" and leaves their edits in place. This is intentional: respect user edits.

References

• Plugin SessionStart hook (hooks/check-docs.sh) detects the block on

startup and reports Cardano context active in this project. when present, or nudges the user to run this skill when absent in a project directory.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cardano-foundation
• Source: cardano-foundation/cardano-dev-skills
• License: Apache-2.0
• Homepage: https://cardano-foundation.github.io/cardano-dev-skills/

Install and usage instructions live in the source repository linked above.