Saltearse al contenido
NamiDB NamiDB

Skill de Claude Code (namidb-guide)

El repo de docs incluye una Skill de Claude Code — namidb-guide — que se carga automáticamente cuando Claude Code detecta un prompt relacionado con NamiDB. Contiene:

  • Un resumen apretado a nivel de sistema del motor (modelo bucket-como-base-de-datos, single-writer-per-namespace, seis URI schemes, breaking change de _id en v0.3, pitfalls comunes)
  • Una referencia del subset de Cypher (cada clause, función, operador)
  • Una referencia de la gramática de URIs (cada scheme, cada mecanismo de credenciales)
  • Una referencia de SDK (Python sync + async, Rust, CLI, HTTP)
  • Snippets de Cypher listos para copiar/pegar (CRUD, shapes IC01/IC02 de LDBC, bulk ingest, EXPLAIN)

Qué la activa

El campo description de la skill está tuneado para activarse cuando mencionas o escribes cualquiera de:

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

También se auto-activa dentro de archivos que matchean **/*.cypher, **/*.py, **/*.rs, **/Cargo.toml, **/pyproject.toml, **/docker-compose.y*ml.

Instalación — tres caminos

La skill se hostea directamente en este sitio en docs.namidb.com/skill/namidb-guide/, con un archivo descargable en docs.namidb.com/skill/namidb-guide.tar.gz. Ambos se rebuildean en cada push al sitio de docs.

Descarga y descomprime la skill en tu directorio user-level de Claude Code para que se active en cada sesión:

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

Verificar:

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

Para actualizar después, vuelve a correr el mismo comando — tar -xz sobreescribe in-place.

Verificar que está cargada

En una sesión de Claude Code, correr:

/skills

Debería aparecer namidb-guide listada.

O testear el auto-fire escribiendo:

escribir una query de Cypher que devuelva los 10 Person más viejos de mi namespace de s3

Claude debería responder con una query v0.3 correcta usando _id (no id) y referenciar tg.Client("s3://...?ns=...").

Cómo se ve por dentro

.claude/skills/namidb-guide/
├── SKILL.md                         # entry point (frontmatter + body)
├── references/
│   ├── cypher-subset.md             # cada clause / función / operador
│   ├── uris.md                      # gramática de URIs, matriz de credenciales
│   └── sdks.md                      # Python / Rust / CLI / HTTP
└── examples/
    └── queries.md                   # snippets para copiar/pegar

El body de SKILL.md se mantiene bajo las 500 líneas (cuenta como costo de token para toda la sesión una vez cargado). El contenido más pesado vive en los archivos de soporte — Claude los trae bajo demanda.

Frontmatter — qué seteamos y por qué

---
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"
  - "**/*.py"
  - "**/*.rs"
  - "**/Cargo.toml"
  - "**/pyproject.toml"
  - "**/docker-compose.y*ml"
---
CampoPor qué
nameIdentificador estable; kebab-case, ≤ 64 chars
descriptionLo que Claude lee para decidir si activarse — la especificidad importa
when_to_useTriggers secundarios appendeados a description (cap combinado de 1,536 chars)
pathsGlobs de archivos que auto-activan la skill en esos contextos

Deliberadamente no seteamos disable-model-invocation ni user-invocable: false — queremos tanto auto-fire como invocación manual con /skills.

Feedback

¿Detectaste algo mal en SKILL.md o en las referencias? La skill es el contexto LLM recomendado por el equipo del motor para NamiDB — mantenerla afilada importa. Escribí a hello@namidb.com con el diff o el issue. Los issues específicos del motor (parser, optimizador, storage) van al repo público del motor en github.com/namidb/namidb.

Ver también