nostr-event-builder

name	nostr-event-builder
description	Construct valid Nostr event JSON and tag structures from requirements when the task is to create or validate concrete events rather than choose which NIPs to use.

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 ✓.

Optimization Notes

• Preserve the user's requested output shape exactly and do not substitute generic advice for concrete artifacts.
• Include exact commands, code structures, protocol fields, tags, parameters, file paths, or deliverable sections when the task asks for them.
• Make safety gates explicit before irreversible, destructive, externally visible, or compliance-sensitive actions.
• For multi-step work, present steps in execution order and include validation or rollback checks where relevant.
• Avoid overfitting to a single eval example: express lessons as reusable rules, not as task-specific answers.