From spicedb-dev
Use when implementing SpiceDB client calls, choosing a consistency model, handling errors and retries, or optimizing permission check performance - provides language-specific patterns for Go/TypeScript/Python with fail-safe error handling
npx claudepluginhub authzed/authzed-marketplace --plugin spicedb-devThis skill uses the workspace's default tool permissions.
This skill provides guidance on using SpiceDB client libraries effectively, understanding consistency guarantees, optimizing performance, and implementing robust authorization code.
Implements structured self-debugging workflow for AI agent failures: capture errors, diagnose patterns like loops or context overflow, apply contained recoveries, and generate introspection reports.
Monitors deployed URLs for regressions in HTTP status, console errors, performance metrics, content, network, and APIs after deploys, merges, or upgrades.
Provides React and Next.js patterns for component composition, compound components, state management, data fetching, performance optimization, forms, routing, and accessible UIs.
This skill provides guidance on using SpiceDB client libraries effectively, understanding consistency guarantees, optimizing performance, and implementing robust authorization code.
SpiceDB is a distributed authorization system. To use it effectively:
| Need to... | Read This |
|---|---|
| See client setup for Go/TS/Python | references/client-patterns.md |
| Understand consistency / zookies | references/consistency-deep-dive.md |
| Optimize performance or add caching | references/performance-tuning.md |
| Bootstrap existing data into SpiceDB | references/bootstrapping.md |
| Deploying SpiceDB to production | references/production-deploy.md |
| See a complete Go client example | examples/go-client.go |
| See a complete TypeScript example | examples/typescript-client.ts |
| See a complete Python example | examples/python-client.py |
SpiceDB provides official clients for multiple languages. Each follows similar patterns but with language-specific idioms.
See references/client-patterns.md for full code examples (Go, TypeScript, Python) covering:
TOUCH for idempotency)LookupResources, LookupSubjects)See examples/go-client.go, examples/typescript-client.ts, examples/python-client.py
for complete, runnable demos with all four operations.
Core rules:
OPERATION_TOUCH for writes (idempotent, safe to retry)HAS_PERMISSION grants access; both NO_PERMISSION
and CONDITIONAL_PERMISSION deny -- treat them identically unless your code explicitly
supplied caveat context (see /spicedb-dev:implement-spicedb-checks for handling)WrittenAt ZedToken after writes (see Consistency section)SpiceDB offers four consistency levels. Choosing correctly avoids both stale reads and
unnecessary latency. See references/consistency-deep-dive.md for the full guide including
API defaults, ZedToken routing pattern, and storage recommendations.
Summary:
minimize_latency (may be stale)fully_consistent (always committed)at_least_as_fresh with the WrittenAt ZedToken from your writefully_consistent on reads bypasses the cache -- only for admin/debug/auditat_exact_snapshot can fail with "Snapshot Expired" if the GC window has passedZedToken routing (the correct read-your-writes pattern):
Write → capture WrittenAt token → pass in HTTP response header → use as AtLeastAsFresh
in next CheckPermission. Store ZedTokens as text / varchar(1024) in your database.
Write to your database first, commit, then write to SpiceDB with OPERATION_TOUCH.
Do NOT use a distributed transaction (2PC) spanning your DB and SpiceDB.
TOUCH is idempotent -- if the SpiceDB write fails after your DB commit, it is safe to
retry without risk of duplicate or inconsistent state. If the write repeatedly fails, the
system is in a temporarily inconsistent state (DB committed, SpiceDB not updated); implement
a reconciliation job or retry queue for production systems.
If you find yourself:
references/client-patterns.md for exact patternsreferences/consistency-deep-dive.mdreferences/consistency-deep-dive.mdreferences/performance-tuning.md for batch/cache patternsspicedb-schema-design skillspicedb-schema-design skill for thatauthorization-testing skill for that/spicedb-dev:implement-spicedb-checks or /spicedb-dev:implement-spicedb-relationships for thatFail-safe on any error: deny access when SpiceDB is unavailable. Retry transient errors
(Unavailable, DeadlineExceeded, ResourceExhausted) with exponential backoff. Do not
retry client errors (InvalidArgument, PermissionDenied).
See references/client-patterns.md for Go code patterns for each gRPC status code and
the exponential backoff retry pattern.
See references/performance-tuning.md for detailed guidance including:
CheckBulkPermissions vs looping CheckPermission (always prefer bulk)ImportBulkRelationships for large data loads (>1,000 relationships)RESOURCE_EXHAUSTED and ABORTED alongside UNAVAILABLE)Key rules: Batch writes up to 1,000 per request; use ImportBulkRelationships for larger imports.
Use CheckBulkPermissions for any list-filtering scenario. Profile before optimizing.
Caveats add dynamic, context-aware conditions evaluated at check time.
Use caveats for: Time-based conditions, request context (IP, user agent), simple attributes. Don't use caveats for: Static relationships (use relations), complex business logic, multi-step workflows.
Supply caveat context in CheckPermissionRequest.Context at check time. Handle
PERMISSIONSHIP_CONDITIONAL_PERMISSION when context was not fully provided.
Recommendation: Start without caveats; add only when dynamic runtime context is truly needed. For temporary access (SpiceDB v1.40+), prefer native expiration over time-based caveats.
For detailed implementation patterns and advanced techniques:
references/client-patterns.md - Language-specific client patternsreferences/consistency-deep-dive.md - Detailed consistency guaranteesreferences/performance-tuning.md - Advanced performance optimizationWorking examples in examples/:
examples/go-client.go - Complete Go client exampleexamples/typescript-client.ts - Complete TypeScript exampleexamples/python-client.py - Complete Python exampleWorkflow summary: Initialize client (once, reuse) → Write relationships (TOUCH for idempotency) → Check permissions (choose consistency level) → Handle errors (fail-safe: deny on error) → Optimize (batch, cache, profile before tuning). Security principle: deny by default on any error.