mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-12 23:01:23 +00:00

feat(markdown-html): add v2.10.0 foundation — orchestrator + design-system

Operationalizes Shihipar's "Claude Code HTML output" essay (Medium, 2026):
markdown collapses past ~100 lines for agent-generated artifacts; HTML
restores density, clarity, shareability, and lightweight interaction.

This foundation PR ships 2 of 5 planned skills:

- markdown-html-orchestrator (context: fork): deterministic doctype
  classifier scoring filename hints + content signals across DOCUMENT /
  REVIEW / SLIDES; silent-routes above two-signal threshold; refuses
  inputs < 100 lines per Shihipar; refuses without design-system
  onboarding. 3 stdlib tools: doctype_classifier.py, route_explainer.py
  (the never-silently-chain enforcer + onboarding gate), and
  output_path_resolver.py (kebab slug + collision suffix).

- design-system: one-time onboarding wizard (10 questions for brand
  primary/accent HEX + heading + body Google Fonts + editorial/technical/
  minimal/playful style + default output dir + syntax theme + TOC
  behavior + optional logo/company). WCAG-AA-validated 12 CSS custom
  properties derived in HSL space; refuses to save if body-text or link
  contrast fails 4.5:1, or if the output dir is unwritable. Pattern
  lifted from research-ops/skills/clinical-research/scripts/ (onboard.py
  + config_loader.py shape) and marketing/landing/scripts/
  (brand_palette_validator.py WCAG + HSL math). Precedence: project >
  global > defaults; MARKDOWN_HTML_NO_CONFIG=1 bypasses.

Plus cs-markdown-html-orchestrator agent, 3 slash commands
(/cs:markdown-html router, /cs:grill-markdown-html 5-question grill,
/cs:design-system onboarding surface), 6 reference docs each citing 5-7
authoritative sources (Tufte, Shihipar, Bret Victor, Maggie Appleton,
Bartosz Ciechanowski, Amelia Wattenberger; WCAG 2.2, Ellen Lupton,
Adobe Spectrum, Sara Soueidan, Material Design 3), 1 JSON schema asset,
domain README + CLAUDE.md.

Converter sub-skills (md-document, md-review, md-slides) land in v2.10.1
follow-up PRs. All three will import design-system/scripts/config_loader.py
for shared brand tokens.

Repo-level updates: scripts/sync-codex-skills.py SKILL_DOMAINS adds
markdown-html → documentation category; .claude-plugin/marketplace.json
adds markdown-html-skills plugin entry (63 → 64 plugins, 16 → 17
domains); root CLAUDE.md gets nav-map row, structure-tree entry, and
v2.10.0 release-notes block.

Validation:
- check_plugin_json.py → OK
- sync-codex-skills.py --dry-run → 2 new symlinks, total 338 → 340
- skill_description_validator.py → PASS on both SKILL.md files
- skill_review_checklist_runner.py → 5/6 PASS (under-100-lines advisory
  fires; same as research-ops orchestrator)
- All 6 Python tools smoke-tested with --help and --sample
- End-to-end onboarding round-trip works (--defaults, --set, --reset)
- WCAG-fail hard refusal fires correctly on impossible color combos
- Classifier on the repo's own CLAUDE.md correctly returns
  needs-clarification (15 vs 13 — document signals tie with slides
  signals because of multiple --- HRs); orchestrator asks rather than
  silently chains.

Distinct from Anthropic's official Playground plugin (interactive
prompt-tuning controls with sliders/knobs/prompt-copy-back) and from
marketing/landing/ (landing-page generator from scratch).

https://claude.ai/code/session_01BK2KoQot1U7J5oSosrCQdc

2026-05-29 14:19:06 +00:00

3.5 KiB

Raw Permalink Blame History

description	argument-hint
Matt-Pocock-style forcing-question grill for markdown-html conversions. Walks 5 cited-canon questions (purpose, line-count threshold, design-system onboarding, output path, doctype confidence) one at a time with a recommended answer. Run before /cs:markdown-html when you want clarity about what the HTML is for, not just a route to the closest sub-skill.	<path to markdown file>

/cs:grill-markdown-html — Pre-conversion grill

Walk the user through 5 forcing questions before routing to the converter. One question per turn, with a recommended answer and a canon citation. The user must answer Q1 before Q2 is asked. Never bundle.

$ARGUMENTS

The 5 questions (Matt Pocock grill-with-docs pattern)

Q1/5 — Purpose

What decision does this HTML drive — is the reader skimming, deciding, or presenting?

Recommended: name it first; density follows from purpose.

Canon: Shihipar (Claude Code HTML output essay) — "match output format to consumption context"; Tufte, Visual Display of Quantitative Information, ch. 1.

If the user shrugs, ask once: "Skimming → minimal layout. Deciding → sticky TOC + search. Presenting → slide deck."

Q2/5 — Line count threshold

Is the input markdown ≥ 100 lines?

Recommended: yes — below that, keep it as markdown. Run wc -l <file>.md to confirm.

Canon: Shihipar — markdown still wins under 100 lines.

If under 100 lines, refuse the conversion. Do NOT proceed.

Q3/5 — Design-system onboarded?

Has the design-system been onboarded?

Recommended: yes, globally. Run python3 markdown-html/skills/design-system/scripts/onboard.py (or --defaults for zero-touch) if not.

Canon: research-ops onboarding pattern (research-ops/CLAUDE.md §8); WCAG 2.2 §1.4.3.

Check via:

python3 markdown-html/skills/design-system/scripts/config_loader.py --status

If setup_completed: false, surface onboarding. Do NOT proceed without it.

Q4/5 — Output path

Where does the output save, and will it overwrite anything?

Recommended: the configured default_output_dir with --on-collision suffix (the default, which generates -2, -3, … instead of overwriting).

Canon: Matt Pocock handoff skill — never silently overwrite a working artifact.

Resolve via:

python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_resolver.py \
    --input "$ARGUMENTS" --doctype <verdict>

Q5/5 — Doctype confidence

Document type confidence — silent-route, or one clarifying question?

Recommended: silent-route only when silent_route_allowed: true in the classifier output. Otherwise, ask one clarifying question and recommend the winner.

Canon: research-ops two-signal threshold (research-ops/skills/research-ops-skills/SKILL.md §"Routing logic").

Classify via:

python3 markdown-html/skills/markdown-html-orchestrator/scripts/doctype_classifier.py \
    --input "$ARGUMENTS" --output human

Discipline

One question per turn. Don't bundle Q1+Q2 in the same message. Wait for the answer.
Always recommend an answer. Never ask an open question.
Always cite the canon. The recommendation must reference the source.
Refuse, don't override. If Q2 or Q3 fails, the conversion does not proceed. The grill protects against silent-failure.
Walk depth-first. Finish all 5 questions for THIS conversion before starting a different one.

After Q5, hand off to /cs:markdown-html <path> to actually run the conversion with the confirmed answers in hand.

3.5 KiB Raw Permalink Blame History