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. ```markdown <!-- 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.