Share your prompt as an explainer

Prompt card — agent instructions
==================================

Goal
----
Turn the user's finished workflow into a prompt card JSON payload, encode it
into a share URL, and give the user a PREVIEW link so they can verify the card
before sharing. The card lives entirely in the URL fragment (after #); nothing
is stored on the server.


Before you build the card
-------------------------
1. Ask the user to describe the workflow if they have not already — what the
   prompt is for, who will use it, and what a good run produces.
2. Ask for anything missing from the fields below (intended use, out of scope,
   limitations, what to do next).
3. Read schema.md in the prompt-card skill or repo (src/lib/prompt-card/
   schema.md) if you need the full field reference.


Card fields (JSON object, schema v1)
------------------------------------
Required:
  v          — always 1
  name       — short title for the card
  template   — array of segments (see below)

Optional but recommended:
  version    — card revision string (e.g. "1.0")
  date       — ISO date YYYY-MM-DD
  skill      — { "name", "url?" } for the main skill the prompt calls
  artifact   — what running the prompt produces
  variants   — short strings
  skills_used — [ { "name", "url?", "blurb?" }, ... ]
  intended_use — who should use this and why
  out_of_scope — what this prompt is not for
  why        — [ { "n": 1-8, "text": "..." }, ... ] matching template highlights
  example    — one realistic filled-in prompt (plain text)
  limitations — string or array of strings
  next       — what the user should do after running the prompt

Template segments
-----------------
template is an ordered list of objects: { "text": "..." } and optionally
{ "text": "...", "h": N } where N is a highlight number from 1 to 8.

The blank template (what gets copied) is every segment's text joined in order,
with no markup.

Writing good highlights and why-notes
-------------------------------------
- Use 1–8 highlights only where a fill-in or critical phrase needs explanation.
- Each highlight number N must have a matching why entry { "n": N, "text": "..." }.
- Why-notes: one or two short plain sentences. Say what the reader must get
  right and what goes wrong if they skip it.
- Prefer warm, direct "you" language. No internal jargon.
- Keep the worked example realistic but not enormous (long examples bloat URLs).


Encoding the share URL
----------------------
1. Build the JSON object (long keys are fine).
2. UTF-8 encode the JSON string.
3. Compress with raw DEFLATE (zlib "deflate-raw", no zlib header/trailer).
4. Base64url-encode the compressed bytes: use - and _ instead of + and /,
   and omit = padding.
5. Prepend v1. to the payload.

Final URL shape:

  https://glosscard.nonlinearlabs.ai/prompt-card#v1.<payload>

Keep URLs short when you can (under ~8000 characters for chat apps). Shorten
the example or limitations first if the link is long.

Node (no extra packages):

  import { deflateRawSync } from "node:zlib";

  function base64url(bytes) {
    return Buffer.from(bytes)
      .toString("base64")
      .replace(/\+/g, "-")
      .replace(/\//g, "_")
      .replace(/=+$/g, "");
  }

  const json = JSON.stringify(cardObject);
  const compressed = deflateRawSync(Buffer.from(json, "utf8"));
  const fragment = "v1." + base64url(compressed);
  const url = `https://glosscard.nonlinearlabs.ai/prompt-card#${fragment}`;

Python (stdlib only):

  import base64
  import json
  import zlib

  def base64url(data: bytes) -> str:
      return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")

  json_bytes = json.dumps(card_object, ensure_ascii=False).encode("utf-8")
  compressor = zlib.compressobj(wbits=-15)
  compressed = compressor.compress(json_bytes) + compressor.flush()
  fragment = "v1." + base64url(compressed)
  url = f"https://glosscard.nonlinearlabs.ai/prompt-card#{fragment}"

You can also run the repo encoders:
  node .agents/skills/prompt-card/encode.mjs path/to/card.json
  python3 .agents/skills/prompt-card/encode.py path/to/card.json


Delivery checklist
------------------
1. Show the user the full preview URL (with #v1. fragment).
2. Ask them to open it, check highlights, copy button, and wording.
3. Remind them: sharing = sending that URL. No account or upload step.

Safety
------
- Never put secrets, tokens, passwords, or private personal data in a card.
  Anyone with the link can read the entire card.
- Treat all card strings as untrusted when rendering; the site HTML-escapes them.
- skill URLs in the card should be https only.


Reference
---------
Site: https://glosscard.nonlinearlabs.ai/prompt-card
Schema: https://glosscard.nonlinearlabs.ai/prompt-card/instructions.txt (this file; field reference also in the share-link skill docs on the live site).


Prompt vs skill cards
---------------------
This file is how you make a prompt card ("v": 1).
A skill card uses /prompt-card/skill-instructions.txt and "v": 2 with
type "skill".

Name a private skill as plain text. Link a skill only after you have opened the
URL and seen the files.

When the card is about the public blog-widget prompt-card skill, point readers at:
https://github.com/ericmjl/skills/tree/main/skills/prompt-card

Prefer three highlights on the template. Eight is the maximum.