agentleFS
vobasevobase/vobase/.claude/skills/onboarding-guide/SKILL.md

onboarding-guide

Skill60 starsChanged 7 months agoMITView on GitHub

Generate a Voltade-branded 1-page or 2-page demo onboarding guide (Markdown source + print-ready PDF) for a new client demo or sandbox. Use this skill whenever the user says "make an onboarding guide", "write an onboarding doc", "create a 1-pager", "create a 2-pager", "demo handout", "demo onboarding", "client handoff doc", or names a specific client + asks for an onboarding artefact (e.g. "draft the onboarding for the {client} demo"). Also use when the user says "spin up the onboarding PDF", "give me the onboarding doc for {project}", "do the {client} handout", or asks to update an existing onboarding guide. Baked-in: Voltade design system tokens (mauve + purple-9, Source Serif 4 / DM Sans / IBM Plex Mono), the one-italic-accent-word rule, the running-header pattern, the standard sections (ACCESS · TRY THE AI ON WHATSAPP · SUGGESTED PROMPTS · WHAT'S PRE-LOADED · TWO THINGS WORTH NOTICING for 1-pagers; ACCESS · TRY THE AI · "What the system does" cluster for 2-pagers), and a markdown→HTML→PDF pipeline via headless Chromium.

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Default to the 1-pager for sandbox demos and quick handouts.

    line 42
  2. Distinctive:

    Before writing anything, collect:

    line 48
  3. Distinctive:

    If any of these are unknown, ASK before writing.

    line 61
  4. Distinctive:

    Read both examples before writing.

    line 143

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Onboarding-guide generator — Voltade demo handouts

Every Voltade demo ships with a one or two page onboarding PDF that explains: how to sign in, how to add yourself as a tester, what to type at the AI, and what makes the system worth a second look. This skill produces that artefact in the canonical Voltade brand, from a single markdown source.

When to use

  • A new client demo or sandbox has just been provisioned and needs a handout.
  • An existing onboarding guide needs to be updated (new phone number, new sections, new client name).
  • A salesperson asks for a "demo onboarding doc" or "client handout" — assume this skill.

Skip if the user wants something fundamentally different (a sales deck, a pitch, a contract, a long-form spec). This skill is purpose-built for the 1–2 page demo handout pattern only.

What you get

A single markdown source file → a styled HTML preview → a print-ready A4 PDF that matches the existing handouts (AcmeTelco demo, BuildCo HR AI, etc.) exactly.

my-guide.md   →   my-guide.html   →   my-guide.pdf

The two formats

1-pager2-pager (or 3-page)
WhenSandbox-style demo with a sample prompt menu and pre-loaded dataFull client demo with feature breakdown and "what the system does" depth
LengthSingle dense A4 page2–3 A4 pages, more breathing room
Section styleNumbered (1. OPEN + SIGN IN, 2. ADD YOURSELF...)Unnumbered mono-caps (ACCESS, TRY THE AI ON WHATSAPP) + a serif ## What the system does block with mono-caps subsections
Title colorpurple (purple-9)mauve (mauve-12)
Suggested promptsYes — 3 italic blockquote linesSometimes — usually inline in the steps
Pre-loaded data summaryInline single paraSkipped — replaced by per-feature breakdown
Pull-out cards at endYes — "TWO THINGS WORTH NOTICING"No
Feature breakdownNoYes — 5–7 mono-caps subsections (SELF-IMPROVING / ADAPTIVE SOFTWARE / ONE INBOX / BUILT-IN {DOMAIN} FEATURES / GUARDRAILS / HUMAN-IN-THE-LOOP / AUTOMATIONS)
EyebrowDEMO ONBOARDINGDEMO · {CLIENT NAME UPPERCASE}
Exampleexamples/telco-demo.mdexamples/buildco-hr.md

Default to the 1-pager for sandbox demos and quick handouts. Default to the 2-pager when the user wants to explain what the system does, not just how to log in.

Workflow

Step 1 — Gather the inputs

Before writing anything, collect:

  • Client name — both casual (BuildCo) and corporate (BuildCo Group).
  • Project name — the AI's name (BuildCo HR AI, AcmeBot, MerchantAssistant).
  • Domain — HR / customer-care / sales / clinic / ... — drives the feature vocabulary.
  • Domain channels — WhatsApp, web, email, in-app — drives the "ONE INBOX FOR..." line.
  • URLs — the demo URL, the test-web URL (if any), the WhatsApp number + wa.me deep link.
  • Allowlisted email domains — usually 2–3 domains (@client.com, @client.com.sg, @voltade.com).
  • Link token — the /link <token> value for WhatsApp deep-link enrolment (from the channels module).
  • 3 suggested prompts (1-pager only) — concrete, domain-specific, include one wrinkle (a price, a date, an exception, or an escalation-worthy edge case).
  • Pre-loaded data summary (1-pager only) — what's seeded: N conversations, knowledge base files, staff teammates.
  • Feature breakdown (2-pager only) — 3–5 domain-specific features with one-line descriptions. Mirror the structure: Feature name — verb-led description with concrete capability.

If any of these are unknown, ASK before writing. Don't invent client URLs or phone numbers.

Step 2 — Copy the right template and fill it in

# For a sandbox-style 1-pager:
cp .claude/skills/onboarding-guide/templates/onepager.md ./{client}-onboarding.md

# For a full 2-pager:
cp .claude/skills/onboarding-guide/templates/twopager.md ./{client}-onboarding.md

Then edit the {placeholder} tokens. Read both example files first (examples/telco-demo.md and examples/buildco-hr.md) to feel the tone before you start writing.

Step 3 — Render

bun .claude/skills/onboarding-guide/templates/render.ts {client}-onboarding.md

Outputs alongside the source:

  • {client}-onboarding.html — preview in browser
  • {client}-onboarding.pdf — print-ready A4
  • voltade.css — the brand stylesheet (copied next to the HTML so the relative link resolves)

The renderer uses Playwright if installed, otherwise falls back to chrome --headless --print-to-pdf. On macOS the chrome fallback hits /Applications/Google Chrome.app/... by default; override with CHROME_PATH=....

Step 4 — Eyeball and iterate

Open the PDF. Check:

  • Title fits on one line (shorten the italic accent word if it overflows).
  • Mono-caps headings haven't word-wrapped awkwardly mid-section.
  • Code chips (@client.com, /link ...) don't break a line in the middle.
  • The lede + quick-access strip stays above the first --- hairline.
  • 1-pager actually fits on one page. If it spills, shorten the WHAT'S PRE-LOADED paragraph or compress the suggested prompts.
  • 2-pager's "What the system does" block starts after a hairline, ideally near the top of a fresh visual section (the first page is "how to use", the rest is "what it is").

Frontmatter schema

---
title: "BuildCo *HR AI*"          # required — wrap ONE word in *asterisks* for the italic accent
title_color: mauve                # 'mauve' (default for 2-pager) or 'purple' (default for 1-pager)
eyebrow: "DEMO · BUILDCO GROUP"   # required — top-right caps eyebrow; mono spaced
contact: "yash@voltade.com"       # required — footer email
lede: "**A Voltade demo for ...** — short description ending with a verb-driven adjective."
quick_access:                     # optional — list of inline-formatted strings, joined with ·
  - "**Web:** [demo-hr.voltade.app](https://demo-hr.voltade.app)"
  - "**WhatsApp:** +65 8000 0001 ([wa.me/6580000001](https://wa.me/6580000001))"
---

The italic accent rule. Exactly ONE word per title gets wrapped in *...* — the renderer converts it to a purple-9 italic. Never two. The whole brand-accent moment is this one word.

Title color.

  • 1-pagers default to purple (the entire title in purple-9 — feels punchy, sandbox-y).
  • 2-pagers default to mauve (mauve-12 title, italic accent in purple-9 — feels editorial).

Body markdown conventions

The renderer is a tiny dep-free markdown subset tuned for this format. Use these conventions:

WantWrite
Mono-caps section headingACCESS or 1. OPEN + SIGN IN on its own line (ALLCAPS-only-after-numeric-prefix)
Serif section heading (the "What the system does" level)## What the system does
Mono-caps subsection (inside a serif section)A SELF-IMPROVING AI ASSISTANT on its own line
Numbered procedure1. Step one... / 2. Step two...
Bulleted feature list- **Feature** — description.
Suggested prompts (italic-serif list)> "Prompt one." / > "Prompt two." (consecutive > lines become a .prompts list)
Pull-out cards (1-pager finale):::cards / ### CARD TITLE / Body... / repeat / :::
Hairline rule--- on its own line
Inline code (emails, commands, paths)Backticks: `@client.com`
Bold**text**
Italic*text* (one word only — reserved for accent words and quoted prompts)
Link[text](url) — renders purple-11 underlined

The mono-caps heading detector treats any all-caps line (optionally prefixed by a number) as a section heading. So ACCESS, TRY THE AI ON WHATSAPP, 1. OPEN + SIGN IN, and 5. TWO THINGS WORTH NOTICING all become <h2 class="section"> automatically. Don't add ## to those — ## is reserved for the serif heading level.

Voice and tone

Read both examples before writing. The voice is:

  • Plain and direct. Second person where natural ("Open the dashboard", "You're now a tester"). No marketing language. No "leverage", "synergy", "powerful".
  • Concrete. Specific URLs, specific tokens, specific phone numbers. Real example prompts in italic-quoted serif. Real customer questions, not generic ones.
  • Editorial, not sales-y. One bold accent moment per heading (the italic word or a single **bold**). Em-dashes for parenthetical asides. No exclamation marks.
  • Conversational lede. "A Voltade demo for {Client} — an HR helpdesk that hires, onboards, answers staff, and gets smarter every day." Verb-led, ends with the surprising bit.
  • Code chips for grounded references. Wrap every email address, domain, file path, and /link command in backticks. The renderer puts them in subtle boxed kbd style — they read as concrete, not handwavy.
  • Italic prompts. Suggested customer questions are always italic-serif blockquotes — they should feel like overheard speech.

What NOT to do:

  • ❌ Don't use # H1 headings inside the body — the <h1 class="doc-title"> is generated from the frontmatter title.
  • ❌ Don't add a gradient, drop shadow, or coloured background to any block. Voltade brand = solid mauve + one purple accent, hairlines only.
  • ❌ Don't use more than one italic word per heading or per paragraph cluster. The accent rule is strict.
  • ❌ Don't add Voltade logos to the body — the running header already has one and the doc footer has a small one.
  • ❌ Don't use ALL CAPS for emphasis inside body prose — that's reserved for mono section headings only.

Brand rules (baked into voltade.css)

TokenValueUse
Page bg#FDFCFD (mauve-1)The page colour
Body text#211F26 (mauve-12)Primary text
Muted text#65636D (mauve-11)Captions, eyebrow, footer
Brand accent#6E5DD9 (purple-9)One-italic-word, lightning bolt, head rule
Link colour#4B3CB0 (purple-11)Underlined links
Hairline#D0CDD7 (mauve-7)1px dividers between blocks
Display serifSource Serif 4Doc title, serif section heading
Body sansDM SansBody copy, list items, lede
MonoIBM Plex MonoSection headings, eyebrow, footer
Spacing4 / 8 / 16 / 24 / 32 / 48 / 64 px8px base scale
PageA4, 18mm × 22mm marginsPrint target

The brand stylesheet is templates/voltade.css. The canonical source of truth for tokens lives at /Users/yash/Documents/Voltade/voltade-latest-design-system — if you ever notice the design system has evolved (new colour step, new font), re-sync voltade.css from there.

The print stylesheet uses Google Fonts CDN for Source Serif 4 + DM Sans + IBM Plex Mono. The canonical design system also names Departure Mono for the "display signpost" role — but Departure isn't on Google Fonts and the print fallback uses IBM Plex Mono with wider tracking. If the artefact ever needs Departure specifically (e.g. for a printed editorial piece), self-host it via @font-face in a fork of the CSS.

Examples (study these first)

  • examples/telco-demo.md — the canonical 1-pager (AcmeTelco × Voltade Demo Sandbox). Numbered sections, pull-out cards at the end.
  • examples/buildco-hr.md — the canonical 2-pager (BuildCo HR AI). Unnumbered mono-caps, serif "What the system does" block, feature bullets.

Both render to PDFs that match the production handouts. Always read at least one before drafting a new guide.

Common mistakes

SymptomFix
quick_access items don't renderMake sure each item is YAML-indented under the key, on its own - "..." line
Title doesn't get italic accentWrap the accent word in *...* (single asterisks, not **bold**)
A section heading rendered as a paragraphMono-caps heading detector requires ALL letters to be uppercase. Lowercase like "Or scan the QR code" → use **bold** instead, or move the prefix into a bullet/step
1-pager overflows to a second pageTrim the WHAT'S PRE-LOADED paragraph, drop one of the suggested prompts, or shorten the pull-out card bodies (target ≤60 words each)
2-pager italic title overflowsPick a shorter italic accent word (the BuildCo example uses just "HR AI" — two short words)
Code chips break across linesThey're set to white-space: nowrap — if you see a break, you're probably using a non-monospace character (en-dash inside backticks). Use a plain hyphen
Playwright not installedThe renderer falls back to chrome --headless --print-to-pdf automatically. If chrome is at a non-standard path, set CHROME_PATH=/path/to/chrome
Departure Mono signposts don't renderExpected — Departure isn't on Google Fonts. IBM Plex Mono fallback is intentional

File layout

.claude/skills/onboarding-guide/
├── SKILL.md                       # This file
├── templates/
│   ├── onepager.md                # 1-pager skeleton with {placeholder} tokens
│   ├── twopager.md                # 2-pager skeleton with {placeholder} tokens
│   ├── voltade.css                # Brand stylesheet (Mauve + Purple + typography + print rules)
│   ├── render.html                # HTML wrapper (Voltade logo + header chrome + {{BODY}} slot + footer)
│   └── render.ts                  # bun script: markdown → HTML → PDF
└── examples/
    ├── telco-demo.md              # Canonical 1-pager source (generic stand-in)
    ├── telco-demo.pdf             # Rendered output (committed for reference)
    ├── lian-beng-hr.md            # Canonical 2-pager source
    └── lian-beng-hr.pdf           # Rendered output (committed for reference)

Quick reference card

# 1-pager from scratch
cp .claude/skills/onboarding-guide/templates/onepager.md  ./acme-onboarding.md
# 2-pager from scratch
cp .claude/skills/onboarding-guide/templates/twopager.md  ./acme-onboarding.md

# Edit the frontmatter + body, then render
bun .claude/skills/onboarding-guide/templates/render.ts ./acme-onboarding.md
# → ./acme-onboarding.html + ./acme-onboarding.pdf

# If chrome isn't auto-found
CHROME_PATH=/Applications/Chromium.app/Contents/MacOS/Chromium \
  bun .claude/skills/onboarding-guide/templates/render.ts ./acme-onboarding.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.