# 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
```javascript
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
```javascript
const filter = {
  kinds: [1],
  authors: [followedPubkey],
  limit: 50
}
ws.send(JSON.stringify(["REQ", "sub-id", filter]))
```

### Replying to a Note
```javascript
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).