@iceinvein/agent-skills 0.1.19 → 0.1.21

package/skills/cover-letter-rewrite/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: cover-letter-rewrite
+description: >
+  Revise an existing cover letter by auditing it first, then applying targeted
+  fixes: humanize AI-sounding prose, align claims with the resume, tighten
+  structure, adjust tone to match an active persona, or improve job-description
+  coverage. Preserves the applicant's voice where it's already working. Supports
+  focused passes with --focus humanize|align|tighten|structure|tone. Produces
+  markdown, DOCX, and PDF outputs. Use when the user says "rewrite cover letter",
+  "improve cover letter", "humanize cover letter", "fix cover letter", "tighten
+  cover letter", "this cover letter sounds AI", "make this less generic", "make
+  this more specific", or shares a letter and asks for edits.
+argument-hint: "<letter-file> [--resume <file>] [--jd <file|url|text>] [--focus humanize|align|tighten|structure|tone] [--length short|standard|long] [--out <dir>]"
+---
+
+# Cover Letter Rewrite
+
+Revise an existing cover letter instead of starting over. The rewrite is
+audit-driven: run the audit first, then apply a minimum-change rewrite
+targeting the weakest category (or the user's --focus).
+
+## When to use rewrite vs write
+
+- **Rewrite**: user has a draft they like the bones of. Keep their voice,
+  fix specific issues.
+- **Write**: user has resume + JD and nothing else, or the existing letter is
+  so generic it would be easier to start fresh (audit score below 50 with
+  multiple critical issues).
+
+If the user asks to "improve" or "fix" a letter, default to rewrite. If the
+letter scores below 50 with fabrication or complete topic drift, suggest a
+fresh `/cover-letter write` instead.
+
+## Inputs
+
+Required:
+
+- **Letter**: file path (`.md`, `.mdx`, `.docx`, `.pdf`) or pasted text.
+
+Optional (but enable key checks):
+
+- **Resume** (`--resume <file>`): enables evidence-alignment fixes.
+- **Job description** (`--jd <file|url|text>`): enables coverage fixes.
+
+Flags:
+
+- `--focus <category>`: narrow the rewrite. See "Focus modes" below.
+- `--length short|standard|long` (180/300/420 target).
+- `--tone <persona-name>`: apply a persona for this run only.
+- `--out <dir>` (default `./cover-letters/`).
+- `--preserve-voice` (stricter; forbid changes outside the flagged issues).
+- `--diff` (emit a unified diff between original and rewrite alongside files).
+
+If resume or JD is missing and would be needed for the requested focus,
+either ask for it or proceed with a caveat (for example, `--focus humanize`
+does not need the resume, but `--focus align` does).
+
+## Workflow
+
+### Step 1: Parse inputs
+
+Extract the letter using the same tools as `cover-letter-write`
+(`pdftotext`, `pandoc`, direct read). Normalize to markdown for editing.
+
+### Step 2: Run the audit
+
+Invoke the audit rubric from `cover-letter-audit` on the letter plus optional
+resume and JD. Capture:
+
+- Overall score and category scores
+- Specific issues at each severity level
+- AI signals (burstiness, phrase list hits, TTR, em-dash count, passive %)
+- Evidence alignment gaps
+- JD coverage gaps
+
+Do not print the full audit report unless `--show-audit` is passed. A one-line
+score summary is enough.
+
+### Step 3: Pick the rewrite plan
+
+Without `--focus`, pick the lowest-scoring category as the primary focus and
+apply light fixes to the others. With `--focus`, restrict most changes to that
+category.
+
+Rewrite plan is a short internal list: "change X here, replace Y there, add
+sentence about Z". Keep it concrete. Prefer minimal edits.
+
+### Step 4: Apply the rewrite
+
+Edit the letter. Rules:
+
+1. **Preserve sentences that work.** If a sentence is specific, grounded, and
+   not on the AI phrase list, leave it alone.
+2. **Targeted replacements.** Rewrite only the sentences or paragraphs that
+   triggered the audit issues.
+3. **Do not add facts.** If the audit flagged missing JD coverage and the
+   resume has evidence for it, add a clause referencing that evidence. If the
+   resume does not have evidence, do not invent any; surface the gap to the
+   user instead.
+4. **Respect active persona.** Load `~/.config/cover-letter/active-persona`
+   and enforce its rules during the rewrite. The `--preserve-voice` flag
+   tightens this: changes outside flagged issues are forbidden.
+5. **Length.** Keep the rewritten letter within the target band. If the
+   original was over length, the rewrite should cut. If under, it should add
+   only where evidence supports it.
+
+### Step 5: Post-rewrite audit
+
+Re-run the audit on the new letter. Compare scores. If the rewrite scored
+lower than the original in any category (should be rare), revert to the
+original for that section or ask the user to review the regression.
+
+### Step 6: Emit outputs
+
+Write markdown first; then derive DOCX and PDF via pandoc (same engine
+fallback order as `cover-letter-write`).
+
+If `--diff` is set, also write a unified diff at
+`<out>/<slug>-rewrite.diff`.
+
+### Step 7: Report
+
+One terse summary:
+
+```
+Rewrite complete.
+- Files: acme-senior-fe-2026-04-24.md, .docx, .pdf
+- Score: 72 -> 87 (+15)
+- Focus: humanize
+- Changes:
+  - Replaced generic opener with specific hook about the offline-first blog post
+  - Cut 3 AI phrases ("proven track record", "passionate about", "team player")
+  - Raised burstiness by adding one short sentence per paragraph
+  - Tightened close from 4 sentences to 2
+```
+
+## Focus modes
+
+Each mode targets one category. The writer still performs a cleanup pass on
+the others, but most edits concentrate in the focus area.
+
+### humanize
+
+Goal: raise the Voice and Humanness category score.
+
+Actions:
+
+- Replace every AI phrase hit with plain language. "Proven track record of
+  delivering results" becomes "Shipped three products to production in the
+  last two years" (or similar; use real resume content).
+- Remove em-dashes; replace with period or comma or parentheses.
+- Add burstiness: introduce at least one short sentence (under 10 words) per
+  paragraph, and ensure at least one long sentence (over 20 words) per letter.
+- Raise TTR: replace repeated nouns and verbs with synonyms the applicant
+  would actually use.
+- Cut hedging and throat-clearing ("I would like to", "I believe", "it is
+  fair to say", "arguably").
+
+### align
+
+Goal: raise Content and Fit + Correctness by matching claims to resume.
+
+Actions:
+
+- For each unsupported claim, either replace it with a supported one from the
+  resume or cut it.
+- For each JD must-have not covered, add one clause referencing real resume
+  evidence. If no evidence exists, surface the gap to the user.
+- Remove vague claims ("strong backend skills") and replace with specifics
+  ("five years Go, two years Rust, shipped the payments gateway at Stripe").
+
+### tighten
+
+Goal: raise Structure + cut word count.
+
+Actions:
+
+- Cut redundant sentences.
+- Merge paragraphs if they cover the same subject.
+- Tighten wordy phrases ("in order to" becomes "to"; "due to the fact that"
+  becomes "because").
+- Bring to length target.
+- Remove filler sign-off lines.
+
+### structure
+
+Goal: raise Structure.
+
+Actions:
+
+- Reorder sections if motivation appears before evidence (put evidence
+  second; motivation usually lands better after the fit is established).
+- Rebuild opening if it is a generic greeting or filler opener.
+- Rewrite close to two sentences with a concrete next step, not "I hope to
+  hear from you soon".
+
+### tone
+
+Goal: match the active persona (or --tone override).
+
+Actions:
+
+- Adjust contraction frequency up or down per persona.
+- Adjust sentence length distribution toward the persona's mean/std.
+- Apply persona's do/don't rules.
+- Swap vocabulary tier (consumer vs professional vs technical) to match.
+
+## Examples
+
+### humanize focus
+
+**Before (AI-sounding):**
+
+> Dear Hiring Manager,
+>
+> I am writing to express my strong interest in the Senior Frontend Engineer
+> position at Acme Corp. With a proven track record of delivering cutting-edge
+> solutions in dynamic environments, I am passionate about joining your
+> world-class team and believe I would be a valuable asset.
+
+**After (humanized):**
+
+> Dear Hiring Team,
+>
+> Your post on offline-first editing in the Acme blog lined up with a problem
+> I spent eighteen months on at Notion: making a collaborative editor survive
+> a subway commute. I'd like to work on the rest of that problem with you.
+
+### align focus
+
+The JD lists "experience with Kafka" as a must-have. The original letter
+doesn't mention it. The resume lists "migrated order service to Kafka-backed
+event sourcing (2M events/day)". Rewrite adds a single clause:
+
+**Before:**
+
+> I have extensive backend experience and enjoy working on distributed
+> systems.
+
+**After:**
+
+> I spent a year moving our order service to Kafka-backed event sourcing at
+> Shopify; it now handles two million events a day.
+
+### tighten focus
+
+**Before (340 words, 4 paragraphs):**
+
+> [Original letter with redundancy and filler]
+
+**After (265 words, 3 paragraphs):**
+
+> [Same content, cut to essentials, merged redundant paragraphs]
+
+## Handling critical issues
+
+If the audit finds a critical issue (fabrication, contradiction with resume,
+or factual error about the company), do not auto-rewrite that section. Report
+it to the user and ask how to resolve it:
+
+```
+Critical issue: the letter claims "five years at Stripe" but the resume shows
+two years at Stripe (2022-2024). Options:
+1. Change the letter to match the resume (recommended)
+2. Change the resume (if the letter is correct)
+3. Drop the claim
+
+Which do you want?
+```
+
+Wait for the user's answer before completing the rewrite.
+
+## Preserve voice mode
+
+With `--preserve-voice`, the rewrite must not:
+
+- Change sentence structure outside flagged issues
+- Change vocabulary choices outside the AI phrase list
+- Reorder sections
+- Adjust tone dimensions
+
+It may only:
+
+- Replace flagged AI phrases with plain substitutes
+- Fix fabrications and contradictions
+- Add clauses for uncovered JD must-haves (if resume supports them)
+- Correct grammar and spelling
+
+Use this mode for letters the user mostly likes but where one or two specific
+problems need fixing.
+
+## What this skill does not do
+
+- Does not write a letter from scratch. Route to `cover-letter-write` if the
+  existing letter is too generic to save.
+- Does not score the letter without applying changes. Route to
+  `cover-letter-audit` for pure scoring.
+- Does not manage personas. Route to `cover-letter-persona`.

package/skills/cover-letter-write/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: cover-letter-write
+description: >
+  Generate a cover letter from a resume and a job description. Accepts resume and
+  JD as PDF, DOCX, markdown/MDX, URL, or pasted text. Produces markdown, DOCX, and
+  PDF outputs. Enforces human-sounding prose (varied sentence length, concrete
+  verbs, no filler openers), aligns every claim to a resume bullet, and covers the
+  top job-description requirements without keyword stuffing. Respects active
+  writing persona if one is set via /cover-letter persona use. Use when the user
+  says "write cover letter", "draft cover letter", "generate cover letter", "new
+  cover letter", "cover letter for <role>", or shares a resume and job description
+  together. Even if the user phrases it as "make me a cover letter" or "help me
+  apply to X", trigger this skill.
+argument-hint: "--resume <file> --jd <file|url|text> [--length short|standard|long] [--out <dir>]"
+---
+
+# Cover Letter Writer
+
+Produce a cover letter that reads like a human wrote it, fits the specific job,
+and only makes claims the resume actually supports.
+
+## Inputs
+
+Required:
+
+- **Resume**: `.pdf`, `.docx`, `.md`, `.mdx`, or `.txt`. Passed as `--resume <path>`
+  or as the first file attached to the conversation.
+- **Job description**: file (same formats), URL, or pasted text. Passed as
+  `--jd <path|url>` or pasted inline.
+
+Optional:
+
+- `--length short|standard|long` (180/300/420 words; default standard)
+- `--out <dir>` (default `./cover-letters/`)
+- `--tone <persona-name>` (override active persona for this run only)
+- `--focus <keyword,keyword>` (emphasize specific JD themes)
+- `--no-audit` (skip post-generation self-audit)
+
+If either required input is missing, ask for it before proceeding. Do not
+hallucinate resume content or JD requirements.
+
+## Workflow
+
+Run these steps in order. Report progress concisely after each.
+
+### Step 1: Extract inputs
+
+Resume parsing:
+
+| Format | Command |
+|--------|---------|
+| `.md`, `.mdx`, `.txt` | Read tool, direct |
+| `.pdf` | `pdftotext -layout <file> -` (poppler). Fall back to `pandoc <file> -t markdown` if not installed. |
+| `.docx` | `pandoc <file> -t markdown` |
+
+Job description parsing: same table. For URLs, use `WebFetch` and extract the
+visible posting text (skip navigation, footers, "similar jobs" blocks).
+
+If a required tool is missing, stop and report the install command
+(`brew install poppler pandoc` on macOS, `apt-get install poppler-utils pandoc`
+on Debian/Ubuntu).
+
+### Step 2: Build the fact sheet
+
+From the resume, extract:
+
+- Full name, email, phone, location, link(s)
+- Current role and company (if present)
+- All past roles with dates, companies, titles
+- Every bullet point, grouped by role
+- Skills, tools, languages, certifications
+- Education
+- Quantified outcomes (numbers, percentages, revenue, users, latency wins)
+
+From the job description, extract:
+
+- Company name, role title, team (if given), location, work mode
+- Company mission or product line (one sentence if the JD mentions it)
+- Must-have requirements (usually the "Requirements" section)
+- Nice-to-haves
+- Responsibilities
+- Tools, languages, frameworks, methodologies named
+- Tone signals: does the JD read formal, casual, mission-driven, technical-deep?
+
+Build an internal JSON scratchpad you can reason from. Do not show it to the
+user unless they ask. Example shape:
+
+```json
+{
+  "applicant": { "name": "...", "current_role": "...", "years": 7 },
+  "jd": { "company": "...", "role": "...", "tone": "casual-technical" },
+  "must_haves": ["Go", "distributed systems", "on-call"],
+  "evidence_map": {
+    "Go": "Payments team at Stripe, 3 years, refactored billing gateway in Go",
+    "distributed systems": "Led migration of order service to event-sourced architecture",
+    "on-call": null
+  },
+  "gaps": ["on-call"]
+}
+```
+
+### Step 3: Decide fit strategy
+
+From the evidence map, pick the top three to five matches where:
+
+1. The requirement is explicitly in the JD (must-have preferred over nice-to-have).
+2. The resume has a concrete, quantified bullet that maps to it.
+3. The bullets are not redundant with each other. Prefer breadth: infra +
+   leadership + product sense beats three infra bullets.
+
+For each gap (must-have with no resume evidence), decide:
+
+- If the gap is important and the user has shown interest in learning, include
+  one honest line showing how the applicant bridges it ("I have not shipped Go
+  in production, but my Rust work translates closely and I have been writing
+  Go for side projects for the last six months") ONLY if the user confirmed
+  this background elsewhere. Do not invent.
+- If unconfirmed, flag the gap to the user and ask how to handle it.
+
+### Step 4: Load persona
+
+Check `~/.config/cover-letter/active-persona`. If a persona is active and the
+user did not override with `--tone`, load that persona JSON.
+
+Without a persona, use these defaults:
+
+| Setting | Default |
+|---------|---------|
+| Tone dimensions | funny_serious 0.7, formal_casual 0.55, respectful_irreverent 0.2, enthusiastic_matter_of_fact 0.55 |
+| Sentence length mean | 16 |
+| Sentence length std dev | 8 |
+| Contraction frequency | 0.4 (moderate) |
+| Passive voice cap | 10% |
+| Readability | Flesch grade 8-10 |
+
+If the JD signals a clear tone (a startup posting that uses "ya'll" and
+emoji wants casual; a law firm posting that uses "the Firm" and
+"heretofore" wants formal), nudge the defaults one step toward that tone
+unless a persona explicitly locks them.
+
+### Step 5: Draft the letter
+
+Produce a single draft in markdown. Structure:
+
+```
+[Date]
+
+[Hiring Manager / Team name, if known; otherwise skip]
+[Company name]
+
+Dear [Name or "Hiring Team"],
+
+[Opening hook - 2 sentences]
+
+[Fit and evidence - 1 to 2 short paragraphs, 3 to 5 sentences]
+
+[Motivation - 2 to 4 sentences]
+
+[Close - 2 sentences + plain sign-off]
+
+Sincerely,
+[Applicant name]
+```
+
+Writing rules the draft must follow:
+
+- **No filler openers.** Do not start with "I am writing to...", "It is with
+  great enthusiasm that...", "Please accept this letter as...". Start with a
+  specific observation about the role, company, or problem.
+- **Evidence clause shape.** For each claim, pattern is `[specific outcome] at
+  [specific context]`. Example: "Cut p99 latency on the checkout API from
+  420ms to 95ms at Stripe by moving the pricing lookup into a Redis cache" not
+  "Strong backend performance experience".
+- **Burstiness target.** Sentence lengths should vary. At least one sentence
+  under 10 words per paragraph and at least one over 20.
+- **Concrete verbs.** Prefer shipped, cut, rewrote, owned, built, led, wrote,
+  scaled, debugged. Avoid leveraged, utilized, spearheaded, synergized,
+  orchestrated, empowered, facilitated, navigated.
+- **No hollow superlatives.** Avoid "world-class", "cutting-edge",
+  "game-changing", "next-generation" unless quoting the company back to itself
+  from the JD (and then only once).
+- **Do not repeat the resume.** The letter says what the resume cannot: why
+  these bullets matter for *this* role, and why the applicant wants it.
+- **One "I" density check.** Fewer than 40% of sentences should start with "I".
+
+### Step 6: Self-audit (unless --no-audit)
+
+Before writing files, run the audit checks inline:
+
+1. Word count within target band (default 250-400)
+2. No AI phrases from the list in `cover-letter-audit` (50+ phrases)
+3. Sentence length std dev >= 5 (burstiness proxy)
+4. Passive voice <= persona cap (default 10%)
+5. Every claim traceable to a resume bullet
+6. Top 5 JD must-haves are either covered or explicitly acknowledged as gaps
+7. Company name and role appear at least once each
+8. No filler opener
+
+If any check fails, revise the draft before emitting files. Report the
+revisions in one line.
+
+### Step 7: Emit outputs
+
+Write markdown first. Derive DOCX and PDF from it.
+
+```bash
+# from cwd or --out dir
+pandoc cover-letter.md -o cover-letter.docx
+pandoc cover-letter.md -o cover-letter.pdf --pdf-engine=weasyprint
+```
+
+PDF engine fallback order:
+
+1. `weasyprint` (best typography out of the box)
+2. `wkhtmltopdf`
+3. `xelatex` (if a LaTeX distribution is installed)
+4. Chromium headless (`google-chrome --headless --print-to-pdf=out.pdf input.html` after converting md to html with pandoc)
+
+If no engine is available, emit only markdown and DOCX, and tell the user which
+install (`brew install weasyprint` on macOS) would unlock the PDF.
+
+### Step 8: Report
+
+One terse summary: file paths, self-audit score, any acknowledged gaps. If the
+self-audit score is below 85, suggest `/cover-letter rewrite <file> --focus
+humanize` (or whichever category scored lowest).
+
+## Handling edge cases
+
+- **Resume has no quantified bullets.** Ask the user for one or two numbers
+  (team size, users served, revenue, latency, headcount). A bulletless letter
+  reads weak. If they cannot provide any, note it and write the letter with
+  qualitative evidence only.
+- **JD is vague.** If the JD lacks concrete requirements, shift the letter's
+  weight from evidence to motivation, and lean on the company's public
+  product/mission. Ask the user for a company URL if none is supplied.
+- **Multiple roles apply.** If the user has several target roles, produce one
+  letter per role; do not blend. Ask which one to start with.
+- **Referral or recruiter.** If the user mentions a referrer by name, work
+  that into the opening hook in one line, not a paragraph.
+- **Career change.** Lead with motivation and transferable evidence. The gap
+  acknowledgment rule applies more heavily here; do not paper over the change.
+
+## Example: good opening vs bad opening
+
+**Bad (filler, generic, AI-shaped):**
+
+> I am writing to express my enthusiastic interest in the Senior Frontend
+> Engineer position at Acme Corp. With over seven years of experience in the
+> industry, I believe I would be a great fit for your dynamic team.
+
+**Good (specific, grounded, human):**
+
+> Your post on offline-first editing in the Acme blog lined up with a problem
+> I spent eighteen months on at Notion: making a collaborative editor survive
+> a subway commute. I'd like to work on the rest of that problem with you.
+
+The first sentence in the good example mentions a specific company post, a
+specific technical problem, a specific prior employer, and a specific duration.
+The bad example says none of that. This difference is the whole point.
+
+## Output rendering note
+
+Cover letters should render well as PDF. Keep markdown simple: no tables, no
+code blocks, no HTML. Just paragraphs, a date header, and a sign-off. Headers
+and lists in a cover letter look wrong in most contexts, so avoid them unless
+the user explicitly asks.

package/skills/improve-my-codebase/CATALOGUE-FIELDS.md

@@ -0,0 +1,26 @@
+# Catalogue fields for improve-my-codebase
+
+The `improve-my-codebase` orchestrator reads `skills/index.json` and routes audits based on two fields:
+
+## `applies: string[]`
+
+Areas a skill is relevant to. The orchestrator runs an audit only when at least one of its `applies` values matches a detected stack signal (or `any`).
+
+| Value | Meaning | Detection signal |
+|-------|---------|------------------|
+| `any` | Always applicable | Always matches |
+| `ui` | Requires UI surface | `.tsx`/`.jsx`/`.vue`/`.svelte`/`.html`/`.css` files, or `react`/`vue`/`svelte`/`solid` in `package.json` deps |
+| `domain` | Requires domain layer | Directory named `domain/`, `entities/`, `aggregates/`, or domain-driven naming |
+| `integration` | Requires messaging/events | Directory named `events/`, `messaging/`, `queues/`, or deps `kafkajs`/`amqplib`/`bullmq` |
+| `architecture` | Cross-cutting structural | Always matches in projects with > 5 files |
+| `errors` | Error handling concerns | Always matches in any non-trivial codebase |
+| `legacy` | Modifying existing code | Only fires when invoked with `diff` mode |
+
+## `quick: boolean`
+
+Whether the audit qualifies for the `quick` mode. Quick audits should:
+- Be primarily structural or static (file structure, imports, naming).
+- Avoid deep semantic reasoning over function bodies.
+- Return findings within roughly 60 seconds on a medium repo.
+
+If unsure, mark `quick: false`. Better to miss in quick mode than to blow the latency budget.