Skip to content

How it works

Three complementary mechanisms set the Cardano context for the agent, listed from most reliable to least.

1. Per-project cardano-context directive

The most reliable mechanism. Run once per project:

# Claude Code marketplace plugin
/cardano-dev-skills:cardano-context


# Codex
$cardano-context

What it does:

  • Writes the same version-tagged block into the project’s CLAUDE.md and AGENTS.md. Claude reads the former; Codex reads the latter.
  • Instructs either agent to treat model knowledge as potentially stale, select the relevant shared skill, resolve docs/sources/ relative to that skill, and cite what it used.
  • Commit both files and teammates inherit the directive on clone.
  • Re-running is safe: same version is a no-op; older versions are atomically replaced.

A project-local Claude skill may also appear as /cardano-context; the plugin-qualified form above avoids collisions with skills from other plugins.

Good at: ensuring the agent consults bundled context on every turn, including vague prompts that don’t match any specific skill’s triggers.

2. Skill auto-matching

Each skill declares trigger phrases in its description. When you ask a question that matches, the agent auto-invokes that skill:

  • “review my validator” → review-contract
  • “scaffold a Cardano project” → scaffold-project
  • “how do I connect a wallet” → connect-wallet
  • “explain CIP-1694” → explain-cip

The full skill catalogue lives at /skills.

Good at: workflow-shaped prompts where the user names the task.

3. SessionStart freshness signals

A SessionStart hook (hooks/check-docs.sh) inspects the bundled corpus and the current working directory. It returns one JSON object with hookSpecificOutput.hookEventName set to SessionStart and the status lines in hookSpecificOutput.additionalContext. Claude Code and Codex understand this format; the [Cardano Dev Skills] prefix stays inside the context string instead of resembling a JSON array on stdout. Hook execution depends on the host’s hook support and trust settings. The notices are:

  • Docs loaded. Normal: Docs loaded: N sources, M files (updated Xd ago).
  • Supply-chain framing. Prints a standing note that the bundled corpus is third-party reference data, never instructions to execute.
  • Docs stale (>30 days). Suggests how to refresh based on install topology: for a local clone, git pull && ./scripts/fetch-docs.sh; for a marketplace install, claude plugin update cardano-dev-skills@cardano-dev-skills from a shell, or auto-update turned on for the marketplace in /plugin.
  • Plugin clone behind upstream. Local clones only: if git fetch has run and you haven’t pulled, the hook prints how many commits behind you are.
  • Cardano context active. When ./CLAUDE.md contains the current directive block. An older block gets a prompt to re-run /cardano-dev-skills:cardano-context; a block newer than the installed plugin gets a prompt to update the plugin.
  • Cardano context nudge. When cwd looks like a project (.git, .claude, or existing CLAUDE.md) but has no block: “Tip: run /cardano-dev-skills: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 project-context check inspects CLAUDE.md; Codex also reads the durable AGENTS.md block directly and does not depend on this hook.

Good at: ambient awareness — surfaces stale docs and missing project directives without interrupting flow.

Public evidence under host permissions

Skills are local-first and remain useful without network access. assess-constitutionality has one recorded, narrow exception: for a live governance action it first tries to read the public provider record, exact on-chain anchor bytes, and proposal material that anchor directly references. It does not perform open-ended web research, alter permissions, or execute fetched content.

Claude desktop/cloud domain controls, when present, may need the specific provider, anchor, or direct-material domain allowed. That setting is permission, not a guarantee that networking, DNS, or the endpoint works. Codex applies its own sandbox, network, and approval settings; Claude settings do not transfer. If a host denies one retrieval, the skill preserves evidence acquired elsewhere, marks only the affected finding Not-yet-verifiable, and gives a targeted fallback.

When auto-consultation misses

Vague prompts like “help me build a Cardano dApp” may not match any specific skill’s triggers, and without the per-project directive the agent may answer from training data alone.

When that happens, 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.”

The durable per-project directive is the reliable fallback. A keyword-matching prompt hook was considered and rejected because it is host-specific, loses project context, and produces both false positives and false negatives.