@arkone_ai/offer-letter 1.0.0

package/README.md

@@ -0,0 +1,29 @@
+# @arkone_ai/offer-letter
+
+A [Claude Code](https://claude.ai/code) skill that generates branded offer letters as PDF/DOCX and optionally emails them to candidates.
+
+## Install
+
+```bash
+npm install -g @arkone_ai/offer-letter
+```
+
+## Usage
+
+In any Claude Code session:
+
+```
+/offer-letter
+```
+
+## What it does
+
+- Generates a professional offer letter from candidate details (name, role, comp, start date)
+- Applies company branding — logo, colors, fonts — from a brand config file or reference document
+- Supports regional templates (US, EU, APAC) and employment types (FTE, contractor)
+- Converts to PDF via Puppeteer/wkhtmltopdf or saves as DOCX
+- Optionally emails the offer to the candidate via SendGrid, Resend, or SES
+
+## 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: 'offer-letter.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 /offer-letter in any supported AI session.');

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@arkone_ai/offer-letter",
+  "version": "1.0.0",
+  "description": "Claude Code skill: generate branded offer letters as PDF/DOCX and optionally email them to candidates",
+  "type": "module",
+  "scripts": {
+    "postinstall": "node install/install.js"
+  },
+  "bin": {
+    "offer-letter": "install/install.js"
+  },
+  "files": [
+    "skill.md",
+    "install/"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "arkone",
+    "hr-ops",
+    "offer-letter"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill.md

@@ -0,0 +1,183 @@
+---
+name: offer-letter
+description: "Generate a branded offer letter as PDF/DOCX and optionally email it to the candidate. Use this skill when: 'create offer letter', 'generate offer', 'send offer to candidate', 'draft offer letter', 'make an offer'. Also trigger for: 'employment offer', 'offer package', 'job offer document'."
+license: MIT
+compatibility: Designed for Claude Code
+---
+
+# Skill: offer-letter
+
+Generate a professional, branded offer letter and optionally send it to the candidate via email.
+
+## When to use
+
+- User wants to create an offer letter for a candidate
+- User wants to send an offer letter via email
+- User wants to generate offer letters in batch
+
+## Step 1: Gather inputs
+
+Ask the user for any missing required fields. Use sensible defaults where possible.
+
+### Required fields
+
+| Field | Example |
+|---|---|
+| Candidate full name | Jane Smith |
+| Role / job title | Senior Software Engineer |
+| Department | Engineering |
+| Start date | 2026-04-15 |
+| Base salary | $180,000/year |
+| Currency | USD |
+
+### Optional fields
+
+| Field | Default |
+|---|---|
+| Signing bonus | — |
+| Equity / stock options | — |
+| Annual bonus target | — |
+| Benefits summary | Standard company benefits |
+| Employment type | Full-time |
+| Location / remote status | — |
+| Reporting manager | — |
+| Offer expiry date | 7 days from generation |
+| Candidate email | — (needed only if sending) |
+
+### Brand assets (optional)
+
+| Asset | How to provide |
+|---|---|
+| Company logo | File path to PNG/SVG |
+| Brand colors | Hex codes (primary, secondary) or reference doc |
+| Company name | Text |
+| Reference document | Path to an existing offer letter PDF/DOCX to match style |
+| Brand config | Path to JSON/YAML with all brand settings |
+
+Check for a brand config file at these locations (in order):
+1. Path provided by user
+2. `./brand-config.json` in current directory
+3. `~/.claude/hr-brand.json` global config
+
+Brand config format:
+```json
+{
+  "company_name": "Acme Corp",
+  "logo_path": "/path/to/logo.png",
+  "primary_color": "#1a73e8",
+  "secondary_color": "#174ea6",
+  "accent_color": "#34a853",
+  "font": "Inter",
+  "footer_text": "Confidential — Acme Corp"
+}
+```
+
+## Step 2: Choose template
+
+Based on inputs, select the appropriate template variant:
+
+| Variant | When to use |
+|---|---|
+| US Full-time | Default for US-based FTE roles |
+| US Contractor | When employment type is contractor/1099 |
+| EU Full-time | When location is EU — include GDPR notice, probation period |
+| APAC Full-time | When location is APAC — adjust for local norms |
+| Remote | When fully remote — include remote work terms |
+
+If a reference document was provided, extract its layout, tone, section order, and formatting to match instead of using a default template.
+
+## Step 3: Generate the document
+
+### HTML → PDF approach (default)
+
+1. Create an HTML file with inline CSS for the offer letter
+2. Apply brand assets:
+   - Logo in header (right-aligned or centered based on reference doc)
+   - Primary color for headings and horizontal rules
+   - Secondary color for subheadings
+   - Company name in header and footer
+   - Footer with confidentiality notice and page numbers
+3. Structure the letter with these sections:
+   - **Header** — company logo + name + date
+   - **Greeting** — personalized to candidate
+   - **Position details** — role, department, reporting line, start date, location
+   - **Compensation** — base salary, bonus, equity (formatted as a clean table)
+   - **Benefits summary** — bullet list of key benefits
+   - **Terms** — employment type, at-will notice (US), probation (EU), offer expiry
+   - **Signature block** — hiring manager + candidate signature lines with date fields
+   - **Footer** — confidentiality notice
+4. Convert to PDF using one of these methods (try in order):
+   - `npx puppeteer` — headless Chrome HTML→PDF
+   - `wkhtmltopdf` — if installed
+   - `prince` — if installed
+   - Fall back to saving as HTML and tell the user to print to PDF
+
+### DOCX approach (if user requests)
+
+1. Use `python-docx` or a Node DOCX library (`docx` npm package)
+2. Apply same structure and branding as above
+3. Save as .docx
+
+### Output file
+
+Save to: `./offer-letter-<candidate-last-name>-<date>.pdf` (or `.docx`)
+
+## Step 4: Send via email (optional)
+
+Only if the user provides a candidate email or asks to send.
+
+### Check for email config
+
+Look for email API keys in this order:
+1. Environment variable: `SENDGRID_API_KEY`, `RESEND_API_KEY`, or `SES_ACCESS_KEY`
+2. Config file: `~/.claude/hr-email.json`
+
+Email config format:
+```json
+{
+  "provider": "sendgrid",
+  "api_key": "SG.xxxx",
+  "from_email": "hr@company.com",
+  "from_name": "HR Team",
+  "reply_to": "hiring-manager@company.com"
+}
+```
+
+### Send the email
+
+1. Compose email:
+   - **To**: candidate email
+   - **Subject**: `Offer Letter — <Role> at <Company>`
+   - **Body**: brief, warm message congratulating the candidate, noting the attached offer, and asking them to review and sign by the expiry date
+   - **Attachment**: the generated PDF/DOCX
+2. Send via the configured provider using `curl` or a Node/Python script
+3. Report success or failure to the user
+
+If no email config is found, skip sending and tell the user:
+> "Offer letter generated. To enable email delivery, set `SENDGRID_API_KEY` or create `~/.claude/hr-email.json`."
+
+## Step 5: Output summary
+
+After generation (and optional sending), show:
+
+```
+✅ Offer Letter Generated
+━━━━━━━━━━━━━━━━━━━━━━━━
+Candidate:  Jane Smith
+Role:       Senior Software Engineer
+Comp:       $180,000 base + $30,000 signing
+Start:      2026-04-15
+Expires:    2026-04-22
+File:       ./offer-letter-smith-2026-03-23.pdf
+Email:      ✓ Sent to jane@email.com (or ✗ Not configured)
+```
+
+## Error handling
+
+| Issue | What to do |
+|---|---|
+| Missing required field | Ask the user before proceeding |
+| No PDF tool available | Save as HTML, instruct user to `npm i -g puppeteer` |
+| Logo file not found | Generate without logo, warn user |
+| Email send fails | Show error, save the letter locally, suggest manual send |
+| Reference doc unreadable | Fall back to default template, warn user |