@arkone_ai/handbook-section 1.0.0

package/README.md

@@ -0,0 +1,29 @@
+# @arkone_ai/handbook-section
+
+A [Claude Code](https://claude.ai/code) skill that writes or rewrites employee handbook sections in plain, approachable language.
+
+## Install
+
+```bash
+npm install -g @arkone_ai/handbook-section
+```
+
+## Usage
+
+In any Claude Code session:
+
+```
+/handbook-section
+```
+
+## What it does
+
+- Writes a new handbook section or rewrites an existing one for clarity
+- Matches the tone and style of your existing handbook if you provide a reference
+- Uses plain language with TL;DR boxes, examples, and scannable formatting
+- Flags compliance-sensitive content for legal review
+- Outputs as PDF, DOCX, or Markdown
+
+## License
+
+MIT

package/install/install.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { copyFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const root = join(import.meta.dirname, '..');
+const home = homedir();
+
+const agents = [
+  { name: 'Claude Code', dir: join(home, '.claude', 'skills') },
+  { name: 'Codex',       dir: join(home, '.codex',  'skills') },
+  { name: 'Kiro',        dir: join(home, '.kiro',   'skills') },
+];
+
+const files = [
+  { src: join(root, 'skill.md'), dest: 'handbook-section.md' },
+];
+
+let installed = 0;
+for (const agent of agents) {
+  if (!existsSync(agent.dir)) continue;
+  for (const file of files) {
+    copyFileSync(file.src, join(agent.dir, file.dest));
+  }
+  console.log(`✓ ${agent.name}: ${agent.dir}`);
+  installed++;
+}
+
+if (installed === 0) {
+  mkdirSync(agents[0].dir, { recursive: true });
+  for (const file of files) {
+    copyFileSync(file.src, join(agents[0].dir, file.dest));
+  }
+  console.log(`✓ Claude Code: ${agents[0].dir}`);
+}
+
+console.log('\nUse /handbook-section in any supported AI session.');

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@arkone_ai/handbook-section",
+  "version": "1.0.0",
+  "description": "Claude Code skill: write or rewrite employee handbook sections in plain language",
+  "type": "module",
+  "scripts": {
+    "postinstall": "node install/install.js"
+  },
+  "bin": {
+    "handbook-section": "install/install.js"
+  },
+  "files": [
+    "skill.md",
+    "install/"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "arkone",
+    "hr-ops",
+    "handbook-section"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill.md

@@ -0,0 +1,213 @@
+---
+name: handbook-section
+description: "Write or rewrite an employee handbook section in plain language, output as branded PDF/DOCX. Use this skill when: 'write handbook section', 'update handbook', 'rewrite handbook chapter', 'add to employee handbook', 'handbook entry'. Also trigger for: 'employee guide section', 'staff handbook', 'company handbook'."
+license: MIT
+compatibility: Designed for Claude Code
+---
+
+# Skill: handbook-section
+
+Write or rewrite an employee handbook section in plain, approachable language. Matches existing handbook style if a reference is provided.
+
+## When to use
+
+- User wants to write a new section for their employee handbook
+- User wants to rewrite an existing section to be clearer or more current
+- User provides a topic and wants handbook-ready content
+
+## Step 1: Gather inputs
+
+### Required
+
+| Field | Example |
+|---|---|
+| Section topic | Welcome & Company Overview, Benefits, Time Off, Workplace Conduct, Safety, IT & Security, etc. |
+| Company specifics | Key facts, rules, or details unique to this company for this topic |
+
+### Optional
+
+| Field | Default | Purpose |
+|---|---|---|
+| Company name | Ask user | Used in content and branding |
+| Existing handbook | — | Path to current handbook PDF/DOCX — used to match tone, style, formatting |
+| Existing section | — | Path or text of the section being rewritten |
+| Target audience | All employees | New hires, managers, contractors, specific department |
+| Tone | Friendly-professional | `friendly` (conversational, warm), `professional` (balanced), `formal` (corporate) |
+| Handbook style | — | E.g., "We use 'you' not 'employees'", "Include icons", "Each section has a TL;DR" |
+| Jurisdiction | US (general) | For compliance-sensitive sections |
+| Output format | PDF | `pdf`, `docx`, `md` |
+
+### Brand assets (optional)
+
+Check for brand config at these locations (in order):
+1. Path provided by user
+2. `./brand-config.json` in current directory
+3. `~/.claude/hr-brand.json` global config
+
+## Step 2: Determine the section type
+
+Handbooks cover a wide range of topics. Identify which category the requested section falls into and use the appropriate structure.
+
+### Common handbook sections and their structure
+
+| Section | Typical content | Key elements |
+|---|---|---|
+| **Welcome / About Us** | Company mission, values, history, culture | Warm tone, storytelling, no legalese |
+| **Employment Basics** | At-will notice, employment types, equal opportunity | Legal disclaimers required |
+| **Workplace Conduct** | Expected behavior, dress code, attendance, substance policy | Clear dos and don'ts, examples |
+| **Anti-Harassment & Discrimination** | Protected classes, reporting, investigation | Must include legal notices, reporting channels |
+| **Compensation & Pay** | Pay schedule, overtime, deductions, direct deposit | Compliance with FLSA, state wage laws |
+| **Benefits** | Health, dental, vision, 401k, life insurance, perks | Eligibility, enrollment, summary of plans |
+| **Time Off & Leave** | PTO, sick leave, holidays, parental leave, bereavement | Accrual, request process, carryover |
+| **Remote & Hybrid Work** | Eligibility, expectations, equipment, communication | Practical guidance, not just rules |
+| **IT & Security** | Acceptable use, passwords, devices, data handling | Clear rules, consequences |
+| **Safety & Emergency** | Workplace safety, emergency procedures, incident reporting | OSHA requirements, evacuation plan |
+| **Performance & Growth** | Review cycle, feedback, promotions, training | Encouraging tone, growth-oriented |
+| **Leaving the Company** | Resignation, termination, exit process, final pay | Legal requirements, practical steps |
+
+## Step 3: Analyze existing handbook (if provided)
+
+If the user provides their current handbook or a reference:
+
+1. **Read the document** — extract text from PDF/DOCX
+2. **Identify the style**:
+   - Person: "you" vs "employees" vs "team members"
+   - Tone: casual, friendly-professional, formal, legal
+   - Structure: paragraphs vs bullets vs numbered lists
+   - Special elements: TL;DR boxes, icons, callouts, FAQ format
+   - Length: brief (1 page) vs detailed (3-5 pages)
+3. **Match the style** in the new/rewritten section
+4. **Check for cross-references** — if other sections reference this one, maintain consistency
+
+If rewriting an existing section:
+1. Read the current version
+2. Identify what's outdated, unclear, or missing
+3. Preserve any company-specific details that are still accurate
+4. Note changes in the output summary
+
+## Step 4: Write the section
+
+### Writing rules
+
+1. **Write for the reader, not the lawyer** — employees should understand this without a law degree
+2. **Use "you" and "we"** — unless the existing handbook uses a different convention
+3. **Lead with the takeaway** — what does the employee need to know? Say it first.
+4. **Keep sentences short** — aim for 15-20 words per sentence
+5. **One idea per paragraph** — if a paragraph covers two topics, split it
+6. **Use headers liberally** — employees scan, they don't read cover-to-cover
+7. **Include practical examples** — "For example, if you need to take a sick day..."
+8. **Add a TL;DR or key points box** at the top of longer sections
+9. **Avoid double negatives** — "You may not refuse to..." → "You must..."
+10. **Be honest about ambiguity** — "Talk to your manager" is better than a vague rule
+
+### Section structure
+
+Every handbook section should follow this pattern:
+
+```
+[Section Title]
+
+[TL;DR / Key Points box — 3-5 bullet summary]
+
+[Overview — 1-2 paragraphs: what this section covers and why it matters]
+
+[Main content — organized by subtopic with clear headers]
+  - Rules and expectations
+  - How-to / procedures
+  - Examples where helpful
+  - FAQs if the topic is commonly misunderstood
+
+[Where to go for help — who to contact, links, resources]
+```
+
+### Compliance check
+
+For compliance-sensitive sections:
+- Include required legal notices appropriate to the jurisdiction
+- Add "where local law provides greater benefits, local law applies" where relevant
+- Flag any content that should be reviewed by legal counsel with: `⚠️ LEGAL REVIEW: [reason]`
+- Never present the handbook as a contract — include appropriate disclaimers
+
+### Tone calibration
+
+| Tone setting | Characteristics | Example |
+|---|---|---|
+| `friendly` | Conversational, uses contractions, warm, may use humor | "We get it — life happens. Here's how time off works." |
+| `professional` | Clear and approachable but not casual, balanced | "Our time off policy is designed to support work-life balance." |
+| `formal` | Corporate, no contractions, structured | "The Company provides paid time off to eligible employees." |
+
+## Step 5: Generate the document
+
+### PDF (default)
+
+1. Create HTML with inline CSS
+2. Apply brand assets:
+   - Logo in header
+   - Primary color for section headings
+   - Secondary color for subheadings and callout boxes
+   - TL;DR boxes with accent color background
+   - Footer with company name and page numbers
+3. Style to look like a handbook page (not a policy document — warmer, more readable)
+4. Convert via `npx puppeteer`, `wkhtmltopdf`, or `prince`
+
+### DOCX (if requested)
+
+1. Use `python-docx` or Node `docx` package
+2. Apply Heading 1/2/3 styles for easy TOC integration
+3. Include callout boxes as shaded text blocks
+
+### Markdown (if requested)
+
+1. Output as `.md`
+2. Use blockquotes for TL;DR boxes
+3. Standard heading hierarchy
+
+### Output file
+
+Save to: `./handbook-<topic-slug>-<date>.pdf` (or `.docx` / `.md`)
+
+## Step 6: Output summary
+
+```
+✅ Handbook Section Generated
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Topic:       Time Off & Leave
+Company:     Acme Corp
+Tone:        Friendly-professional
+Mode:        New section (or: Rewrite of existing)
+Length:      ~3 pages
+Style match: Matched existing handbook tone ✓ (or: No reference provided)
+Legal flags: 2 items flagged for review
+File:        ./handbook-time-off-2026-03-23.pdf
+
+⚠️ Legal review recommended:
+  - Section 3.2: FMLA eligibility criteria — verify with counsel
+  - Section 5.1: State-specific leave requirements — confirm for CA, NY, WA
+```
+
+## Rewrite mode
+
+When the user provides an existing section to rewrite:
+
+1. Show a brief diff summary of what changed:
+```
+Changes made:
+  ✏️ Rewrote opening paragraph for clarity
+  ➕ Added TL;DR box (was missing)
+  ✏️ Simplified legalese in section 2.3
+  ➕ Added 3 practical examples
+  🗑️ Removed outdated reference to 2019 policy
+  ⚠️ Flagged FMLA section for legal review
+```
+
+2. Preserve all company-specific details (names, numbers, dates) unless the user explicitly asked to change them
+
+## Error handling
+
+| Issue | What to do |
+|---|---|
+| Topic is vague | Ask: "Which handbook section? E.g., Benefits, Time Off, Workplace Conduct..." |
+| No company specifics provided | Draft with placeholders: `[COMPANY NAME]`, `[X DAYS]`, `[CONTACT]` — mark clearly |
+| Existing handbook unreadable | Fall back to default tone and structure, warn user |
+| Section conflicts with another section | Flag the conflict, suggest how to resolve |
+| User wants full handbook | Explain this skill does one section at a time; offer to do them sequentially |