Skill card — agent instructions
=================================

Goal
----
Turn a real skill into a skill card JSON payload, encode it into a share URL
on https://glosscard.nonlinearlabs.ai/prompt-card with prefix v2., and give the
user a PREVIEW link before they share. The card lives entirely in the URL
fragment (after #); nothing is stored on the server.


Before you build the card
-------------------------
1. Read the skill's real files on disk before writing triggers, inputs, files,
   or why notes. If a field is your guess, say so to the user.
2. Ask the user for anything missing: intended use, out of scope, triggers,
   inputs, files, produces, why notes, worked example, limitations, what next.
3. Read schema.md in the repo (src/lib/prompt-card/schema.md) for the full
   field reference.


Required JSON (schema v2)
-------------------------
  v          — always 2
  type       — always "skill"
  name       — short title for the card
  body       — array of segments (see below); same shape as a prompt template

Optional but recommended:
  version, date, intended_use, out_of_scope, triggers, inputs, files, produces,
  why, example, limitations, next, links


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

The blank invocation (what the copy button exports) joins every segment's text in
order, with no markup.


Highlights and why-notes
------------------------
- Use 1–8 highlights only where a fill-in or critical phrase needs explanation.
- Each highlight N needs a matching why entry { "n": N, "text": "..." }.
- Prefer three highlights when you can.


Links
-----
links is an optional array of { "rel", "type?", "name", "url" }.
  rel — "uses" for a lower card (concept, tool, or prompt); "see_also" otherwise.
  url — http or https only.


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 (- and _ instead of + and /, no =).
5. Prepend v2. to the payload.

Final URL shape:

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

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 #v2. fragment).
2. Ask them to open it and check sections, highlights, and wording.
3. Remind them: sharing = sending that URL.


Safety
------
Never put secrets, tokens, or private data in a card. Anyone with the link can
read the entire card.


Reference
---------
Site: https://glosscard.nonlinearlabs.ai/prompt-card
Schema: https://glosscard.nonlinearlabs.ai/prompt-card/skill-instructions.txt (this file).