Skill note guide

Definition

The rules for writing and designing every skill note in LeorWiki: language, structure, copy and looks. One guide, so every skill reads and looks the same.

Applicable to
  • Everyone who writes, edits or designs a skill note, Claude included
  • Every skill note made from SKILL00

1. Where the rules live

What Holds Rule
This guide All rules for copy and design The single source. Change a rule here first.
SKILL00 The empty note with short reminders Points to this guide. Never holds a rule that is not here.
skill-page.css The looks Writers never style by hand. Only the callout names below.
Model notes Onboarding 101 (Steps), Role growth 101 (Steps with a picture) Must follow this guide. Add a Topics model when the first one is done.

When a rule changes: update this guide, then SKILL00, then the CSS if needed, then the model notes. Never only one of them.

2. Language and level

Readers: Leor staff in every role. For most, English is a second language. They read on a tablet, often between clients, and some use the Hindi or Marathi translate button.

Level: CEFR B1, about school grade 6. Plain, but professional, never childish.

Topic Rule Example
Sentence length One idea per sentence. Average 12 words or less, never more than 20. The Definition may have 25. ✓ Get everything ready before day one.
Words Common words. One word for one thing, every time. ✓ check ✗ verify, validate, ascertain
Hard terms Allowed when staff use them at work. Explain them in Words to know, or link the note. Training Passport, FIFO, Zenoti
Voice and tense Active voice, present tense. ✓ The trainer signs off. ✗ It will be signed off.
Idioms None. They break in Google Translate. ✗ on the same page, hit the ground running
Abbreviations Only Leor ones staff know: SOP, JD, KPI, PnL. No "etc.", "i.e.", "e.g." on the page. ✓ for example
Numbers Always digits. Units in words. ✓ 2 weeks, 5 minutes, 30-day review
Spelling British and Indian spelling. Leor words stay as they are. organise, colour, sterilise; center
Capitals Sentence case for headings and names. Role names with capitals, exactly as on the Org Chart. Center Manager, Floor Manager, Trainer, Buddy
People client (not customer or patient), employee, team.
Punctuation Never a long dash or a short dash between words. Colon to start a list. Full stop after a sentence, none after a point or a name. No exclamation marks, no ALL CAPS. ✓ Logins ready: email, Zenoti
Tone Calm, direct, respectful. Say what to do, not what to avoid. No blame. Never framed around leaving or firing. ✓ Make questions welcome.
Emphasis Bold only for the first words of a tile, tip or term, and for the labels Done when: and Ask yourself:. Italics only for owners. Highlight only for VERIFY.

Test before Review: read the page aloud; check the longest sentence; open it with the Hindi translate button and check that it still makes sense.

3. Page structure

Every skill note has these sections, in this order. Each heading is followed by a "---" line.

Section Needed Block Limits
Scope Always [!info] Definition + [!abstract] Applicable to Definition: 1 sentence. Applicable to: 2 lines, who and where.
Why it matters Always [!sk-why] Exactly 3 tiles
How it works Always [!sk-steps] or [!sk-steps|topics] See part 4
Never Optional [!sk-rule] 1 to 3 lines
Best practices Always [!sk-tips] 4 to 6 lines
Mastery Always [!sk-levels] The 4 fixed levels
Watch Optional Video 1 to 2 minutes
Session deck Optional PDF in Attachments/Decks: ![[<Skill name> - deck.pdf]] Group trainings only. Made from the note, never the other way round. No live embeds.
Words to know Optional, always last [!sk-words]- Show the words (n) 2 to 8 words

Not used in skill notes: quiz, sign-off, Related, Do and Don't tables.

4. How it works: rules for every skill

How it works is the main section. It holds everything staff need to know to do the skill. The heading is always "How it works", whatever the content.

4.1 Choose the layout

Question Layout Block Examples
Does the order matter? Steps > [!sk-steps] Onboarding, Role growth, 5S
No fixed order: parts, rules or areas? Topics > [!sk-steps|topics] Hospitality, Communication
  • One layout per note. Both use the same [!sk-stage] blocks, so writers learn one block.
  • 2 to 7 blocks. More than 7: group them, or split the skill.

4.2 Parts of a block

Part Steps Topics Rule
Name ✓ ✓ 1 to 3 words, no full stop. Steps: start with a verb ("Set the goals") or a time ("Day one"), one style per note. Topics: a noun ("Tone of voice").
Line ✓ ✓ 1 sentence of 12 words or less. Steps: the goal, as an instruction ("Get everything ready before day one."). Topics: the main idea ("Calm, warm and clear.").
Points Optional Optional Fold-out titled "Points to cover (n)", 2 to 7 points.
Closing line Done when: Ask yourself: Done when: the visible result that ends the step. Ask yourself: one question staff can check alone.
Owner When roles share the work Rarely Role name in italics at the end of the point. Leave out when everyone does it.

Writing a point: one result you can tick, written as the thing first and then the done word. No full stop.

  • ✓ Buddy named, first 2 weeks on the roster Floor Manager
  • ✗ The Floor Manager should name a buddy

4.3 Around the blocks

  • Intro line: optional, 1 sentence, before the blocks. Only when it helps ("Always in this order.").
  • Picture: optional, 1 only, before the blocks. Shows the whole skill: a flow diagram or the standard setup photo.
  • Table: optional, 1 only, after the blocks. Only to compare, for example "Without 5S / With 5S". Up to 4 columns.
  • Links: to SOPs, policies and other skills, at the first mention only. Never copy their content.

4.4 What does not go in How it works

Content Goes to
A rule that can never be broken Never
A tip on doing it well Best practices
What a word means Words to know
What a learner can do at each level Mastery
Steps of one fixed task An SOP, linked from here

5. Copy rules for the other sections

Section How to write it Example
Definition Skill name + verb + result. No steps. Onboarding takes a new employee from a signed offer to working on their own.
Applicable to Line 1: who uses the skill. Line 2: where or when. Every employee, every role, every center
Why it matters Bold claim of 2 to 4 words with a full stop, then 1 sentence. Cover 3 different reasons: people, clients, business or safety. Clients feel it. New staff keep the Leor experience the same.
Never Start with the action. The heading already says "Never". Start a new employee without a signed contract.
Best practices Bold action of 3 to 5 words with a full stop, then how to do it at Leor in 1 or 2 sentences. Based on what research shows works, but no sources on the page. Never a repeat of How it works. Positive: what it builds. Make questions welcome. Tell them that asking is expected, and who to ask for what.
Mastery Always Observe, Assist, Supervised, Independent. One line each, starting with a verb: what the learner does that others can see. Assist Prepares day one, with a manager checking.
Words to know "Term: plain meaning." 1 or 2 sentences. Link the note if there is one. Buddy: an experienced colleague in the same role.

6. Design rules

  • Looks come only from skill-page.css. No HTML, colours or font sizes in notes.
  • One shape. Every box has the same corner radius and padding as the SOP callouts.
  • Colours have one meaning each. Blue: Leor structure (numbers, fold-outs). Orange: Never. Green: Best practices. No other colours.
  • Icons: line icons in the CSS only. No emoji in body text.
  • Fold-outs are hidden until opened and do not print. Never put a critical rule only inside a fold-out.
  • Must work on: tablet first, then desktop, phone (blocks stack), dark mode and print.
  • Tables: an empty line directly above every table (inside a callout: an empty ">" line). Up to 4 columns, so they fit a tablet.
  • Pictures: explain, never decorate. No stock photos. No words inside the picture that staff need (translate cannot read them). Files in Attachments/Illustrations, named skill-name-what, for example skill-5s-steps.svg.
  • New component: only when the same need shows up in 3 or more skills. Then update this guide, SKILL00 and the CSS together.

7. Ready for Review

  • All needed sections, in the right order
  • How it works uses the layout that fits (Steps or Topics)
  • No VERIFY and no %% comments left
  • Longest sentence 20 words or less, read aloud once
  • No dashes; role names match the Org Chart
  • Every table has an empty line above it
  • Checked on a tablet, in dark mode and in print preview
  • Still makes sense after the Hindi translate button