next.orly.dev/.claude/skills/nostr/README.md

Nostr Protocol Skill

A comprehensive Claude skill for working with the Nostr protocol and implementing Nostr clients and relays.

Overview

This skill provides expert-level knowledge of the Nostr protocol, including:

• Complete NIP (Nostr Implementation Possibilities) reference
• Event structure and cryptographic operations
• Client-relay WebSocket communication
• Event kinds and their behaviors
• Best practices and common pitfalls

Contents

SKILL.md

The main skill file containing:

• Core protocol concepts
• Event structure and signing
• WebSocket communication patterns
• Cryptographic operations
• Common implementation patterns
• Quick reference guides

Reference Files

references/nips-overview.md

Comprehensive documentation of all standard NIPs including:

• Core protocol NIPs (NIP-01, NIP-02, etc.)
• Social features (reactions, reposts, channels)
• Identity and discovery (NIP-05, NIP-65)
• Security and privacy (NIP-44, NIP-42)
• Lightning integration (NIP-47, NIP-57)
• Advanced features

references/event-kinds.md

Complete reference for all Nostr event kinds:

• Core events (0-999)
• Regular events (1000-9999)
• Replaceable events (10000-19999)
• Ephemeral events (20000-29999)
• Parameterized replaceable events (30000-39999)
• Event lifecycle behaviors
• Common patterns and examples

references/common-mistakes.md

Detailed guide on implementation pitfalls:

• Event creation and signing errors
• WebSocket communication issues
• Filter query problems
• Threading mistakes
• Relay management errors
• Security vulnerabilities
• UX considerations
• Testing strategies

When to Use

Use this skill when:

• Implementing Nostr clients or relays
• Working with Nostr events and messages
• Handling cryptographic signatures and keys
• Implementing any NIP
• Building social features on Nostr
• Debugging Nostr applications
• Discussing Nostr protocol architecture

Key Features

Complete NIP Coverage

All standard NIPs documented with:

• Purpose and status
• Implementation details
• Code examples
• Usage patterns
• Interoperability notes

Cryptographic Operations

Detailed guidance on:

• Event signing with Schnorr signatures
• Event ID calculation
• Signature verification
• Key management (BIP-39, NIP-06)
• Encryption (NIP-04, NIP-44)

WebSocket Protocol

Complete reference for:

• Message types (EVENT, REQ, CLOSE, OK, EOSE, etc.)
• Filter queries and optimization
• Subscription management
• Connection handling
• Error handling

Event Lifecycle

Understanding of:

• Regular events (immutable)
• Replaceable events (latest only)
• Ephemeral events (real-time only)
• Parameterized replaceable events (by identifier)

Best Practices

Comprehensive guidance on:

• Multi-relay architecture
• NIP-65 relay lists
• Event caching
• Optimistic UI
• Security considerations
• Performance optimization

Quick Start Examples

Publishing a Note

const event = {
  pubkey: userPublicKey,
  created_at: Math.floor(Date.now() / 1000),
  kind: 1,
  tags: [],
  content: "Hello Nostr!"
}
event.id = calculateId(event)
event.sig = signEvent(event, privateKey)
ws.send(JSON.stringify(["EVENT", event]))

Subscribing to Events

const filter = {
  kinds: [1],
  authors: [followedPubkey],
  limit: 50
}
ws.send(JSON.stringify(["REQ", "sub-id", filter]))

Replying to a Note

const reply = {
  kind: 1,
  tags: [
    ["e", originalEventId, "", "root"],
    ["p", originalAuthorPubkey]
  ],
  content: "Great post!"
}

Official Resources

• NIPs Repository: https://github.com/nostr-protocol/nips
• Nostr Website: https://nostr.com
• Nostr Documentation: https://nostr.how
• NIP Status: https://nostr-nips.com

Skill Maintenance

This skill is based on the official Nostr NIPs repository. As new NIPs are proposed and implemented, this skill should be updated to reflect the latest standards and best practices.

License

Based on public Nostr protocol specifications (MIT License).