Cardano Foundation Cardano Context

---
name: cardano-context
description: >-
  Enable durable Cardano development context in the current project by writing
  a delimited directive block into CLAUDE.md. Tells Claude to consult the
  cardano-dev-skills skill set and bundled docs before relying on training
  data. Trigger phrases: "enable cardano context", "set up cardano for this
  project", "tell claude this is a cardano project", "mark this as a cardano
  project", "/cardano-context".
allowed-tools: Read Edit Write Glob Bash(pwd)
disallowed-tools: WebFetch WebSearch
---

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