mkd
Decision deck in the browser for collecting many decisions or point-by-point feedback. Use when more than about three decisions need the person's verdict, each with justified options; when a long plan or report needs a reaction per section. Not for one yes/no or a two-option pick (use the harness question tool).
How do I install this agent skill?
npx skills add https://github.com/upex-galaxy/agentic-user-skills --skill mkdIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a browser-based interface for collecting user decisions and feedback. It runs a local loopback server and stores data in a dedicated directory in the user's home folder. Security measures include HTML escaping and SVG sanitization for rendered content. External dependencies and recommended setup steps involve well-known technology providers.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
MKD (mkd) — Make Decision
MKD renders a browser deck where the user works through items one screen at a time (Slack Catch-Up style): decisions with justified options, questions with controls, report sections to react to, answerable tables. The answers come back as a Result JSON, which is the execution contract: execute exactly what it says.
No install step: the AI runs bun "<skill-dir>/cli/index.ts" <specPath> [flags] from the skill directory (<repo>/.claude/skills/mkd or ~/.claude/skills/mkd). Output (decks, results, images) lands under ~/.mkd/, so a repo gets zero footprint. If Bun is missing, tell the user to install it (curl -fsSL https://bun.sh/install | bash); never substitute Node.
Use it when
| Situation | Use |
|---|---|
| 1-2 option pick, one yes/no, up to 3 simple decisions | the harness question tool |
| More than 3 decisions, or decisions needing context and written tradeoffs | MKD |
| A long report or plan to react to section by section | MKD (report items) |
| Row-by-row verdicts over a table | MKD (table item) |
| A reply anchored to exact phrases | MKD (highlight-to-quote) |
| No human at a browser (CI, non-interactive) | neither: emit plain output |
Writing a spec
Read references/examples.md (copy-pasteable specs) before writing the first one, and references/schema.md for every field, default and validation rule. A spec is a list of items, one screen each:
| Type | Screen | Answer captured |
|---|---|---|
decision | Problem (plain PM language), collapsible context balloons, options with written justification, optional custom option, note | chosen key (or "CUSTOM" + customText), wasRecommended, note |
question | Markdown content, single/multi/toggle control, free text | controlAnswer, text, quotes |
report | A report section to react to | text, quotes |
table | One answer per row (popover controls + text) | rows[] with controlAnswer/text/quotes, plus item note |
Deck chrome, always on: intro screen, progress rail, sticky Previous / Skip for now / Next bar (skip means decide later, never a rejection), keyboard keys (1-6 pick, Enter or right arrow next, S skip), summary screen, progress footer, dark default theme with a light toggle, localStorage persistence (closing the tab loses nothing). The user can also Shuffle the options and Hide recommended to decide without your nudge; both are display only.
Justified options (the point of the tool)
-
Every option carries a written
justification: what it buys and what it costs. The validator rejects an option without one (exit 2). -
At most one option is
recommended, and its justification says why it is the recommendation ("Recommended because ..."). -
The
problemis plain language for someone without the full technical context; jargon and codenames go insidecontextballoons that explain how things work today. -
Every real tradeoff the user should know about is written down: an unexplained option list is the failure this tool exists to remove.
-
Option count. Offer as many real alternatives as the question has: usually 2-3, up to 5 when the paths are genuinely distinct and viable, never padded. The custom option comes on top (6 slots).
-
Even-handed justifications. Give every option a justification of similar length (within about 20%), the same structure (value, then cost) and the same tone, so length and warmth do not reveal your pick. The recommendation lives only in the recommended option's own text and its
recommendedflag: theproblem, thecontextand the other options never name it or lean toward it. -
Refer to options by
label, never by letter: the user can Shuffle the options, and the letters then follow the screen position, not the speckey. The Result still carries your originalkeyinchosen.
Write title, problem, content and justifications in the user's language; the UI chrome is English.
Media
media is an array on the intro, any item and any decision option: image (alt required), video, embed (Loom or YouTube URL), link (a preview card; the CLI reads Open Graph at build time), diagram (format: "mermaid"), svg. Two or more entries make a carousel. Local files are inlined; videos become muted 480p WebM when ffmpeg exists (6 MB each). Fields, limits and errors: references/schema.md.
The claude.ai artifact viewer blocks frames and remote images, so in artifact mode embeds become poster cards that open in a new tab. A deck that leans on playable embeds goes through the Orca, copy or --wait flow (full HTML, embeds play).
Pick the flow
The CLI never picks artifact mode by itself (it cannot call the Artifact tools): you opt in with --artifact. Check your own tool list, not CLAUDECODE=1, which proves the harness and not the Artifact tool.
| Environment | Flow | Command |
|---|---|---|
Claude Code with Artifact, ArtifactData, ArtifactComments (signed in to claude.ai), main session | artifact mode | <spec> --artifact --title-prefix <session-name>, then publish and watch |
Inside Orca (ORCA_TERMINAL_HANDLE set or orca status --json reachable) | Orca flow: tab next to the terminal, blocks until Send, Result on stdout. Run it in the background | <spec> |
| Anything else, no answer needed in this turn | copy mode: opens the browser, exits; the user pastes the JSON | <spec> |
| Anything else, the next step needs the answer now | --wait: serves, blocks until submit, Result on stdout | <spec> --wait |
A subagent, a print session or Claude Code without the Artifact tool cannot hold a watch: use the Orca, copy or --wait rows. Other flags: --copy (force copy mode inside Orca), --no-open, --port <n>, --timeout <min>.
Before running any flow, read the matching section of references/flows.md: it holds the exact steps, the pending-deck rule for artifact mode, ports, exit codes and the open-artifact <url> subcommand.
Reading the Result
{ "session": "...", "submittedAt": "...",
"stats": { "total": 8, "answered": 6, "skipped": 1, "recFollowed": 4, "overridden": 1, "custom": 1 },
"items": [ { "id": "D1", "type": "decision", "status": "answered", "chosen": "A", "chosenLabel": "...", "wasRecommended": true, "customText": "", "note": "..." } ] }
status: "skipped"means decide later: re-ask later, never assume a rejection.chosen: "CUSTOM"means executecustomTextas stated; ask if it does not add up. Read every item'snote.controlAnswerdecodes by control:singleisstring|null,multiisstring[],toggleisboolean.quotesare exact phrases the user highlighted: weight them when interpretingtext.- Match
items[].idandrows[].idback to the ids you authored. Full shape:references/schema.md. - Artifact mode stores the same object as a JSON string in
results/<session>(fieldresult).
The page loads its display fonts from Google Fonts with system fallbacks; offline it degrades gracefully. The CLI uses Bun built-ins only (cli/README.md).
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/upex-galaxy/agentic-user-skills/mkd">View mkd on skillZs</a>