Claude Code skill (namidb-guide)

The docs repo ships a Claude Code Skill — namidb-guide — that loads automatically when Claude Code detects a NamiDB-related prompt. It contains:

• A tight system-level summary of the engine (the bucket-as-database model, single-writer-per-namespace, six URI schemes, v0.3 breaking _id change, common pitfalls)
• A Cypher subset reference (every clause, function, operator)
• A URI grammar reference (every scheme, every credential mechanism)
• An SDK reference (Python sync + async, Rust, CLI, HTTP)
• Copy-pasteable Cypher snippets (CRUD, LDBC IC01/IC02 shapes, bulk ingest, EXPLAIN)

What triggers it

The skill’s description field is tuned to fire when you mention or write any of:

• Cypher keywords (MATCH, CREATE, MERGE, RETURN, …)
• tg.Client(...), import namidb, client.cypher, merge_nodes, merge_edges
• parse_uri, WriterSession, commit_batch, namidb::storage
• NamiDB URI schemes (memory://, file://, s3://, gs://, az://) — especially with ?ns=
• namidb-server, /v0/cypher, NAMIDB_* env vars
• Manifest CAS / epoch fencing errors (412 Precondition Failed, epoch fenced)
• LDBC SNB Interactive queries (IC01–IC12)

It also auto-activates inside files matching **/*.cypher, **/*.py, **/*.rs, **/Cargo.toml, **/pyproject.toml, **/docker-compose.y*ml.

Install — three paths

The skill is hosted directly on this site at docs.namidb.com/skill/namidb-guide/, with a downloadable archive at docs.namidb.com/skill/namidb-guide.tar.gz. Both are rebuilt on every push to the docs site.

One-line install (recommended)

Downloads and unpacks the skill into your user-level Claude Code directory so it fires in every Claude Code session:

mkdir -p ~/.claude/skills
curl -fsSL https://docs.namidb.com/skill/namidb-guide.tar.gz \
  | tar -xzC ~/.claude/skills/

Verify:

ls ~/.claude/skills/namidb-guide/
# SKILL.md  references/  examples/

To update later, re-run the same command — tar -xz overwrites in place.

Per-file (inspect first)

If you want to read the files before installing them, pull each one individually:

BASE=https://docs.namidb.com/skill/namidb-guide
DEST=~/.claude/skills/namidb-guide

mkdir -p "$DEST"/{references,examples}

curl -fsSL "$BASE/SKILL.md"                      -o "$DEST/SKILL.md"
curl -fsSL "$BASE/references/cypher-subset.md"   -o "$DEST/references/cypher-subset.md"
curl -fsSL "$BASE/references/uris.md"            -o "$DEST/references/uris.md"
curl -fsSL "$BASE/references/sdks.md"            -o "$DEST/references/sdks.md"
curl -fsSL "$BASE/examples/queries.md"           -o "$DEST/examples/queries.md"

You can also browse the files in your browser at the same URLs before installing.

Plugin (when available)

Once published to a Claude Code plugin marketplace, install via:

/plugin install namidb-guide

The .claude-plugin/plugin.json ships with the skill bundle. Marketplace publication is on the roadmap; for now prefer the one-line install above.

Project-local install (team only)

If you have collaborator access to the (private) docs repo github.com/namidb/namidb-docs, you can clone it and Claude Code will auto-load the skill from .claude/skills/namidb-guide/ for any session inside that working directory. External users should use the one-line install above.

Verify it’s loaded

In a Claude Code session, run:

/skills

You should see namidb-guide listed.

Or test the auto-fire by typing:

write a Cypher query that returns the 10 oldest Person nodes from my s3 namespace

Claude should respond with a v0.3-correct query using _id (not id) and reference tg.Client("s3://...?ns=...").

What it looks like inside

.claude/skills/namidb-guide/
├── SKILL.md                         # entry point (frontmatter + body)
├── references/
│   ├── cypher-subset.md             # every clause / function / operator
│   ├── uris.md                      # URI grammar, credential matrix
│   └── sdks.md                      # Python / Rust / CLI / HTTP
└── examples/
    └── queries.md                   # copy-pasteable snippets

The SKILL.md body is kept under 500 lines (it counts toward token cost for the entire session once loaded). Heavier reference content sits in the supporting files — Claude pulls them in on demand.

Customizing the skill

Fork the docs repo and edit .claude/skills/namidb-guide/ to add your team’s conventions (preferred ingestion patterns, internal namespace naming, custom IAM policies). Then symlink or copy your fork into ~/.claude/skills/. Local edits don’t conflict with upstream updates.

Frontmatter — what we set and why

---
name: namidb-guide
description: |
  Use when the user is working with NamiDB, the cloud-native graph
  database whose state lives in an S3-compatible bucket. Triggers on
  Cypher queries, tg.Client(...) calls, /v0/cypher endpoint calls,
  NamiDB URI schemes, and NAMIDB_* env vars.
when_to_use: |
  Also fire when troubleshooting manifest CAS errors, tuning the
  cost-based optimizer or caches, or migrating from Kùzu / Neo4j.
paths:
  - "**/*.cypher"
  - "**/*.cql"
  - "**/*.py"
  - "**/*.rs"
  - "**/Cargo.toml"
  - "**/pyproject.toml"
  - "**/docker-compose.y*ml"
---

Field	Why
name	Stable identifier; kebab-case, ≤ 64 chars
description	What Claude reads to decide whether to fire — specificity matters
when_to_use	Secondary triggers appended to description (1,536-char combined cap)
paths	File globs that auto-activate the skill in those contexts

We deliberately do not set disable-model-invocation or user-invocable: false — we want both auto-fire and manual /skills invocation.

Feedback

Spot something wrong in SKILL.md or the references? The skill is the engine team’s recommended LLM context for NamiDB — keeping it sharp matters. Email hello@namidb.com with the diff or the issue. Engine-specific issues (parser, optimizer, storage) belong on the public engine repo at github.com/namidb/namidb.

See also

• Overview
• llms.txt — for non-Claude-Code agents
• Cursor, Codex, AGENTS.md — for other AI front-ends
• Anthropic’s Claude Code Skills spec — authoritative reference