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 <!-- BEGIN cardano-dev-skills vN --> / <!-- END cardano-dev-skills vN --> markers. Re-running at the same version is a no-op. Re-running with a newer canonical version replaces the older block atomically.
2. 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.
3. 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.
4. 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.
5. 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.

<!-- BEGIN cardano-dev-skills v2 -->
## 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
<!-- END cardano-dev-skills v2 -->

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 <!-- BEGIN cardano-dev-skills. Three cases:

1. No match. Skip to Step 4 (write or create).
2. Match at the current canonical version (<!-- BEGIN cardano-dev-skills v2 -->). Report: "Cardano context already enabled (v2) at <path>. No changes needed." Exit. Do not rewrite.
3. 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.