Nostr Event Builder

Overview

Construct correct Nostr event structures from natural language descriptions. This skill handles the non-obvious parts: choosing the right kind, building proper tag arrays with correct markers, enforcing NIP-10 vs NIP-22 threading rules, and producing valid event JSON ready for signing.

When to Use

• The task is to construct or validate a concrete Nostr event JSON object and its tag array.
• The user describes what they want to publish and needs the exact event shape, kind, tags, and content rules.
• The problem is correctness of event structure for replies, comments, metadata, or other publishable events.
• The output should be an event payload, not protocol-planning advice.

Do NOT use when:

• The task is deciding which NIPs apply at a high level.
• The work is subscription filter design or relay query construction.
• The problem is relay implementation rather than event payload construction.

Response format

Always structure the final response with these top-level sections, in this order:

1. Summary — state the task, scope, and main conclusion in 1-3 sentences.
2. Decision / Approach — state the key classification, assumptions, or chosen path.
3. Artifacts — provide the primary deliverable(s) for this skill. Use clear subheadings for multiple files, commands, JSON payloads, queries, or documents.
4. Validation — state checks performed, important risks, caveats, or unresolved questions.
5. Next steps — list concrete follow-up actions, or write None if nothing remains.

Rules:

• Do not omit a section; write None when a section does not apply.
• If files are produced, list each file path under Artifacts before its contents.
• If commands, JSON, SQL, YAML, or code are produced, put each artifact in fenced code blocks with the correct language tag when possible.
• Keep section names exactly as written above so output stays predictable across skills.

Workflow

1. Identify the Event Kind

Ask: "What is the developer trying to publish?"

| Intent | Kind | Category | Key NIP | | ----------------------------- | ----- | ----------- | ------- | | Post a short text note | 1 | Regular | NIP-10 | | Reply to a kind:1 note | 1 | Regular | NIP-10 | | Comment on non-kind:1 content | 1111 | Regular | NIP-22 | | Set/update user profile | 0 | Replaceable | NIP-01 | | Update follow list | 3 | Replaceable | NIP-02 | | Delete events | 5 | Regular | NIP-09 | | Repost a note | 6 | Regular | NIP-18 | | React to an event | 7 | Regular | NIP-25 | | Publish a long-form article | 30023 | Addressable | NIP-23 |

See references/event-kinds.md for full kind-to-structure mapping.

Critical routing rule:

Is the target a kind:1 note?
  YES → Use kind:1 reply with NIP-10 e-tag markers
  NO  → Use kind:1111 comment with NIP-22 uppercase/lowercase tags

2. Build the Tag Array

Tags are the hardest part. Follow the tag guide for your kind:

For kind:1 replies (NIP-10):

Direct reply to root (no intermediate replies):

{
  "kind": 1,
  "tags": [
    ["e", "<root-event-id>", "<relay-url>", "root", "<root-author-pubkey>"],
    ["p", "<root-author-pubkey>"]
  ],
  "content": "Your reply text"
}

Reply to a reply in a thread:

{
  "kind": 1,
  "tags": [
    ["e", "<root-event-id>", "<relay-url>", "root", "<root-author-pubkey>"],
    [
      "e",
      "<parent-event-id>",
      "<relay-url>",
      "reply",
      "<parent-author-pubkey>"
    ],
    ["p", "<root-author-pubkey>"],
    ["p", "<parent-author-pubkey>"]
  ],
  "content": "Your reply text"
}

For kind:1111 comments (NIP-22):

Top-level comment on a regular event:

{
  "kind": 1111,
  "tags": [
    ["E", "<root-event-id>", "<relay-url>", "<root-author-pubkey>"],
    ["K", "<root-event-kind>"],
    ["P", "<root-author-pubkey>", "<relay-url>"],
    ["e", "<root-event-id>", "<relay-url>", "<root-author-pubkey>"],
    ["k", "<root-event-kind>"],
    ["p", "<root-author-pubkey>", "<relay-url>"]
  ],
  "content": "Your comment text"
}

Top-level comment on an addressable event (kind 30000-39999):

{
  "kind": 1111,
  "tags": [
    ["A", "<kind>:<pubkey>:<d-tag>", "<relay-url>"],
    ["K", "<root-event-kind>"],
    ["P", "<root-author-pubkey>", "<relay-url>"],
    ["a", "<kind>:<pubkey>:<d-tag>", "<relay-url>"],
    ["e", "<event-id>", "<relay-url>"],
    ["k", "<root-event-kind>"],
    ["p", "<root-author-pubkey>", "<relay-url>"]
  ],
  "content": "Your comment text"
}

Comment on a URL or external identifier:

{
  "kind": 1111,
  "tags": [
    ["I", "<url-or-identifier>"],
    ["K", "<identifier-type>"],
    ["i", "<url-or-identifier>"],
    ["k", "<identifier-type>"]
  ],
  "content": "Your comment text"
}

Reply to an existing comment:

{
  "kind": 1111,
  "tags": [
    ["E", "<original-root-event-id>", "<relay-url>", "<root-author-pubkey>"],
    ["K", "<original-root-kind>"],
    ["P", "<root-author-pubkey>"],
    [
      "e",
      "<parent-comment-id>",
      "<relay-url>",
      "<parent-comment-author-pubkey>"
    ],
    ["k", "1111"],
    ["p", "<parent-comment-author-pubkey>"]
  ],
  "content": "Your reply to the comment"
}

See references/tag-guide.md for complete tag semantics.

3. Set the Content Field

Content format depends on the kind:

| Kind | Content Format | | ----- | ---------------------------------------------------------------- | | 0 | Stringified JSON: {"name":"...","about":"...","picture":"..."} | | 1 | Plaintext (no markdown, no HTML) | | 5 | Optional deletion reason text | | 6 | Stringified JSON of the reposted event | | 7 | + (like), - (dislike), or emoji | | 1111 | Plaintext comment | | 30023 | Markdown-formatted article body |

4. Construct the Complete Event

Assemble the unsigned event object:

{
  "pubkey": "<32-bytes-lowercase-hex-public-key>",
  "created_at": "<unix-timestamp-seconds>",
  "kind": "<integer>",
  "tags": [["..."]],
  "content": "<string>"
}

The id is computed as SHA-256 of the serialized form:

[0, "<pubkey>", <created_at>, <kind>, <tags>, "<content>"]

Serialization rules:

• UTF-8 encoding, no whitespace/formatting
• Escape in content: \n, \", \\, \r, \t, \b, \f
• All other characters verbatim

The sig is a Schnorr signature (secp256k1) of the id.

5. Validate Before Signing

Checklist before the event is ready:

• [ ] kind is correct for the intent
• [ ] All required tags present for this kind
• [ ] e tags have correct markers (root/reply for kind:1)
• [ ] p tags include ALL participants in the thread
• [ ] NIP-10 kind:1 replies only target other kind:1 events
• [ ] NIP-22 kind:1111 comments do NOT target kind:1 events
• [ ] K and k tags present for kind:1111 comments
• [ ] Uppercase tags (E/A/I/K/P) point to root scope in kind:1111
• [ ] Lowercase tags (e/a/i/k/p) point to parent item in kind:1111
• [ ] content format matches the kind's requirements
• [ ] created_at is a Unix timestamp in seconds (not milliseconds)
• [ ] All hex values are 32-byte lowercase

Common Mistakes

| Mistake | Why It Breaks | Fix | | --------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------ | | Using kind:1 to reply to a kind:30023 article | NIP-10 kind:1 replies MUST only reply to other kind:1 events | Use kind:1111 (NIP-22 comment) for non-kind:1 targets | | Using kind:1111 to reply to a kind:1 note | NIP-22 comments MUST NOT reply to kind:1 | Use kind:1 with NIP-10 e-tag markers | | Missing root marker on e tags in kind:1 | Clients can't reconstruct the thread tree | Always use marked e tags: ["e", "<id>", "<relay>", "root"] | | Only one e tag with reply marker (no root) | Direct replies to root need root marker, not reply | Single e tag = use root marker only | | Missing p tags for thread participants | Users don't get notified of replies | Include p tags for ALL pubkeys in the thread | | Lowercase e/k/p tags for root scope in kind:1111 | Root scope MUST use uppercase E/K/P tags | Uppercase = root scope, lowercase = parent item | | Missing K or k tags in kind:1111 | Both are REQUIRED by NIP-22 | Always include ["K", "<root-kind>"] and ["k", "<parent-kind>"] | | created_at in milliseconds | Nostr uses seconds, not milliseconds | Use Math.floor(Date.now() / 1000) | | Content as object instead of string for kind:0 | Content must be stringified JSON | Use JSON.stringify({name: "...", ...}) | | Missing d tag on addressable events (30000-39999) | Relay can't address the event properly | Always include ["d", "<identifier>"] | | Positional e tags without markers | Deprecated; creates ambiguity in thread reconstruction | Always use marked e tags with root/reply |

Kind Category Quick Reference

| Range | Category | Behavior | | --------------------- | ----------- | --------------------------------- | | 1000-9999, 4-44, 1, 2 | Regular | Stored by relays, all kept | | 10000-19999, 0, 3 | Replaceable | Latest per pubkey+kind kept | | 20000-29999 | Ephemeral | Not stored by relays | | 30000-39999 | Addressable | Latest per pubkey+kind+d-tag kept |

Example: Complete Event Construction

User says: "I want to reply to my friend's note in an existing thread"

Step 1 — Identify kind: Replying to a kind:1 note → use kind:1 (NIP-10)

Step 2 — Determine thread position: This is a reply to a reply (not the root), so we need both root and reply e tags.

Step 3 — Build the event:

{
  "pubkey": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "created_at": 1709827200,
  "kind": 1,
  "tags": [
    ["e", "aaa111...", "wss://relay.example.com", "root", "f7234bd4..."],
    ["e", "bbb222...", "wss://relay.example.com", "reply", "93ef2eba..."],
    ["p", "f7234bd4...", "wss://relay.example.com"],
    ["p", "93ef2eba...", "wss://relay.example.com"]
  ],
  "content": "Great point! I totally agree with this take."
}

Step 4 — Validate: Root e tag has root marker ✓, reply e tag has reply marker ✓, p tags include both the root author and the parent author ✓, content is plaintext ✓.