@iceinvein/agent-skills 0.1.36 → 0.1.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Install agent skills into AI coding tools",
   "author": "iceinvein",
   "license": "MIT",

package/skills/bounded-context-auditor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bounded-context-auditor
-description: Use when the same domain term means different things in different parts of the codebase, when a God Model has grown to serve multiple subsystems with conflicting needs, when teams step on each other modifying shared domain objects, or when deciding where service/module boundaries should be. Trigger on "should this be one service or two?", "why does the User class have 40 fields?", or when a change to one feature breaks an unrelated feature through a shared model. NOT for code-level coupling within a single context, import direction problems, or event payload design within a known context.
+description: Use when the same domain term means different things in different parts of the codebase, when a God Model serves multiple subsystems with conflicting needs, or when deciding where service/module boundaries should be. Trigger on "should this be one service or two?", "why does the User class have 40 fields?", or when a change to one feature breaks an unrelated one through a shared model. NOT for code-level coupling within a single context, import direction, or event payload design.
 ---
 
 # Bounded Context Auditor
@@ -46,7 +46,13 @@ Language is the first signal that boundaries exist. Look for three patterns:
 
 ### 2. Draw the Context Map
 
-For each distinct bounded context discovered, document its position in the system using Evans' relationship types:
+For each distinct bounded context discovered, document its position in the system using the context-mapping relationship types (Evans 2003 plus his later context-mapping set):
+
+**Partnership**
+- Two contexts (and teams) succeed or fail together; they plan and release in coordination
+- Example: Ordering and Payments ship a combined checkout initiative; neither can deliver alone
+- Distinct from Shared Kernel: the teams coordinate closely but each still owns its own model
+- Risk: coordination cost; use when the mutual dependency is real, not just convenient
 
 **Shared Kernel**
 - Two contexts own the same model together; changes require coordination
@@ -70,7 +76,7 @@ For each distinct bounded context discovered, document its position in the syste
 - Downstream translates upstream's model to its own language
 - Example: Fulfillment receives Order from Sales but translates to internal ShippableItem; changes to Order don't touch Fulfillment
 - Goal: isolation. Downstream only knows upstream's public interface, not internals
-- Bidirectional data flow, but translation is one-way
+- The ACL is owned by and protects the downstream; it may translate in both directions, but its loyalty is to the downstream model
 
 **Open Host Service**
 - Upstream publishes a protocol/API specifically for downstreams
@@ -78,6 +84,12 @@ For each distinct bounded context discovered, document its position in the syste
 - Upside: clear contract, versioning, planned deprecation
 - Downside: upstream must maintain backward compatibility
 
+**Published Language**
+- Contexts exchange information via a well-documented shared language (schema, standard format), often paired with Open Host Service
+- Example: contexts integrate through a versioned Avro/JSON schema registry rather than each other's internal models
+- Upside: no context exposes internals; evolution is managed at the schema level
+- Risk: the shared language itself needs governance
+
 **Separate Ways**
 - No integration between contexts; they genuinely don't interact
 - Example: Marketing analytics and Warehouse inventory have no integration

package/skills/bounded-context-auditor/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "bounded-context-auditor",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Evans-inspired bounded context analysis: detect linguistic fractures, draw context maps, identify leaking language and shared model pollution",
   "author": "iceinvein",
   "type": "prompt",

package/skills/codebase-architecture/SKILL.md

@@ -18,7 +18,7 @@ Design architecture for new projects or review existing codebases. Covers both m
 - "Map the dependencies in this project"
 - Codebase feels tangled, coupled, or inconsistent
 
-**Not for:** Reviewing design documents (use `design-integrity-review`), bug hunting (use `find-bugs`), performance optimization.
+**Not for:** Reviewing design documents (use `design-review`), bug hunting, performance optimization.
 
 ## Mode Selection
 
@@ -70,7 +70,7 @@ These drivers determine which patterns are appropriate. A 500-line CLI does not
 
 ### Phase 3: Select Architectural Patterns
 
-Using Phase 2 drivers, recommend macro-level patterns from `patterns-reference.md`:
+Using Phase 2 drivers, recommend macro-level patterns from the patterns reference installed alongside this skill (`patterns-reference.md`; on cursor/gemini installs it is named `codebase-architecture-patterns.*`; on codex installs it is not bundled, so name patterns from general knowledge instead):
 - Overall structure (layered, hexagonal, event-driven, etc.)
 - Communication style (sync, async, event sourcing)
 - Data strategy (single DB, CQRS, shared-nothing)
@@ -83,7 +83,7 @@ The most important phase:
 - Each module gets a clear responsibility (one sentence)
 - Define interfaces between modules
 - **Establish dependency direction** — which modules know about which? Dependencies should point toward stable abstractions, not toward volatile details.
-- **Name the design patterns** that apply within each module (e.g., "plugin system uses Strategy", "event bus uses Observer"). Refer to `patterns-reference.md`.
+- **Name the design patterns** that apply within each module (e.g., "plugin system uses Strategy", "event bus uses Observer"). Refer to the patterns reference (see Phase 3 for its per-install filename).
 
 ### Phase 5: Produce Architecture Spec
 
@@ -144,7 +144,7 @@ Save to `docs/architecture/architecture-review-YYYY-MM-DD.md`:
 
 For each smell or weakness:
 - What to change and why
-- Which pattern to apply (reference `patterns-reference.md`)
+- Which pattern to apply (from the patterns reference; see Phase 3 for its per-install filename)
 - Impact estimate (how much code changes, risk of breakage)
 - Priority (high / medium / low) with rationale
 

package/skills/codebase-architecture/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-architecture",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Architecture review for existing codebases or structured design for new projects, with patterns reference",
   "author": "iceinvein",
   "type": "prompt",

package/skills/cognitive-load-auditor/SKILL.md

@@ -19,19 +19,19 @@ A UI evaluation framework based on Jeff Johnson's *Designing with the Mind in Mi
 - "This is overwhelming" / "Too many choices" / "Where do I start?"
 - Navigation with many paths or deep nesting
 
-**Not for:** Visual styling (use Rams' Design Audit), color and typography choices (use Gestalt Reviewer for grouping), accessibility compliance (WCAG), or performance optimization.
+**Not for:** Visual styling and decoration (use `rams-design-audit`), spacing and visual grouping (use `gestalt-reviewer`), accessibility compliance (WCAG), or performance optimization. The three compose on a full UI review.
 
 ## The Process
 
 ### 1. Apply the Cognitive Laws
 
 **Miller's Law — Working memory holds 7±2 items (practically 3-4 groups)**
-- Count the number of independent items/options/controls visible at once
-- If > 7 items in a flat list, the interface is exceeding working memory
-- Fix: chunk into 3-5 labeled groups. The groups themselves become the memory items, and users expand into detail as needed.
-- Practical target: aim for 3-4 groups on any single screen. Within each group, 3-5 items.
+- Working memory limits apply to what the user must HOLD IN MIND (items to compare, codes to remember across screens, steps to track), not to what is merely visible: a visible list is externalized and scanned, not memorized (Johnson's own point).
+- Count what the user must actually keep in their head across an interaction; flag flows that require remembering more than 3-4 things (e.g. comparing options that aren't side by side, multi-screen wizards that reference earlier answers).
+- Ungrouped long lists are still a problem, but via scanning cost and decision time (see Hick's Law), not a working-memory violation.
+- Fix: chunk into 3-5 labeled groups so the user scans group labels first, and keep anything that must be remembered visible instead.
 
-**Hick's Law — Decision time = b × log₂(n + 1)**
+**Hick's Law — Decision time = a + b × log₂(n + 1)**
 - Count the number of choices the user must evaluate before acting
 - More choices = longer decision time = higher abandonment
 - Fix: reduce visible choices through progressive disclosure, smart defaults, or recommended options
@@ -93,7 +93,7 @@ Example:
 ```
 COGNITIVE LOAD: Project settings page
   Items visible:     23 settings in a flat list, no grouping
-  Chunking:          none — all 23 items presented equally. Exceeds Miller's Law by 3x.
+  Chunking:          none — all 23 items presented equally; scanning cost and per-item decisions pile up (Hick's Law)
   Decision points:   each setting is an independent choice — 23 decisions on one page
   Memory demands:    user must scroll up to see project name while editing deploy settings at bottom
   Primary action:    Save button at bottom — not visible without scrolling
@@ -105,13 +105,15 @@ COGNITIVE LOAD: Project settings page
 
 Decision engine. After generating UI code, the agent audits its own output for cognitive overload. The report identifies specific violations and concrete fixes. The human sees the audit alongside the component.
 
+**Acquiring the UI when auditing something the agent didn't just write:** prefer a rendered view (user screenshot, or a browser/screenshot tool if available); otherwise count items, choices, and flows from the component source and routing, and say the audit ran source-only (item counts and flow steps survive that mode; target sizes and visual salience don't).
+
 For complex interfaces where high information density is unavoidable (dashboards, admin panels, IDE-like tools), the agent acknowledges that intrinsic load is high and focuses on eliminating extraneous load rather than demanding everything be simple.
 
 ## Common Violations
 
 | Violation | Law broken | Fix |
 |-----------|-----------|-----|
-| 20+ items in a flat list | Miller's Law | Chunk into 3-5 labeled groups |
+| 20+ items in a flat list | Hick's Law (scanning/decision cost) | Chunk into 3-5 labeled groups |
 | 10+ navigation items at same level | Hick's Law | Progressive disclosure, group into categories |
 | Small, closely-spaced action buttons | Fitts's Law | Increase size, increase spacing, primary action larger |
 | "Type your account ID" (no autocomplete) | Recognition > recall | Provide selection or autocomplete |
@@ -137,7 +139,7 @@ For complex interfaces where high information density is unavoidable (dashboards
 | Law | Formula/Rule | Practical Implication |
 |-----|-------------|----------------------|
 | **Miller's Law** | Working memory: 7±2 items (practically 3-4 groups) | Chunk information; aim for 3-5 groups per screen |
-| **Hick's Law** | Decision time = b × log₂(n + 1) | Fewer choices → faster decisions. Use defaults. |
+| **Hick's Law** | Decision time = a + b × log₂(n + 1) | Fewer choices → faster decisions. Use defaults. |
 | **Fitts's Law** | Time = a + b × log₂(1 + D/W) | Big close targets for primary actions, small distant for destructive |
 | **Von Restorff Effect** | Distinct items are remembered better | Make the important thing visually different |
 | **Serial Position Effect** | First and last items remembered best | Put critical info at top and bottom, not buried in middle |

package/skills/cognitive-load-auditor/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-load-auditor",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Jeff Johnson-inspired cognitive load analysis: evaluate UI against Miller's Law, Hick's Law, Fitts's Law, and working memory limits",
   "author": "iceinvein",
   "type": "prompt",

package/skills/cohesion-analyzer/SKILL.md

@@ -115,7 +115,7 @@ COHESION: UserService (src/users/service.ts)
 
 ## Interaction Model
 
-Decision engine. The agent analyzes cohesion in modules it reviews or refactors, producing the cohesion report. When reviewing existing code, it identifies the lowest-cohesion modules (coincidental and logical first) and recommends targeted extractions. The agent targets the largest, most-changed files first—they're the best signal of cohesion problems. It doesn't aim for every module to reach functional cohesion; it balances practicality (some temporal/procedural cohesion is acceptable in init/shutdown) with clarity (modules should be nameable, testable, and reasonably sized).
+Decision engine. The agent analyzes cohesion in modules it reviews or refactors, producing the cohesion report. When reviewing existing code, it identifies the lowest-cohesion modules (coincidental and logical first) and recommends targeted extractions. The agent targets the largest, most-changed files first—they're the best signal of cohesion problems (rank them with `git log --since="6 months ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20`, cross-checked against line counts). It doesn't aim for every module to reach functional cohesion; it balances practicality (some temporal/procedural cohesion is acceptable in init/shutdown) with clarity (modules should be nameable, testable, and reasonably sized).
 
 ## Cohesion vs. Coupling
 

package/skills/cohesion-analyzer/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "cohesion-analyzer",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Constantine & Yourdon-inspired cohesion analysis: classify module focus on the 7-level spectrum, find split lines, reduce mixed responsibilities",
   "author": "iceinvein",
   "type": "prompt",

package/skills/composability-auditor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: composability-auditor
-description: Use when functions or modules are hard to reuse because they do too much or assume too much about their environment, when building a new feature requires modifying existing code instead of combining existing units, when functions have hardcoded dependencies on specific data sources or output formats, or when testing requires elaborate setup because the unit manages its own I/O. Trigger on "I need exactly what this does but with slightly different output", "why can't I reuse this?", or when adding a feature means adding a flag to an existing function. NOT for top-level orchestration code, performance-critical paths, or one-off scripts.
+description: Use when functions or modules are hard to reuse because they do too much or assume too much about their environment, when a new feature means modifying existing code instead of combining units, or when testing needs elaborate setup because the unit manages its own I/O. Trigger on "I need exactly what this does but with different output", or when adding a feature means adding a flag. NOT for top-level orchestration code, performance-critical paths, or one-off scripts.
 ---
 
 # Composability Auditor
@@ -145,7 +145,7 @@ Decomposed into three units:
 ```typescript
 // Unit 1: Fetch data — takes connection as parameter
 function fetchOrderReport(db: Database, orderId: string): Report {
-  const orders = db.query(`SELECT * FROM orders WHERE id = ${orderId}`);
+  const orders = db.query("SELECT * FROM orders WHERE id = ?", [orderId]);
   return formatReport(orders);
 }
 
@@ -163,8 +163,8 @@ function sendEmail(service: EmailService, message: EmailMessage): Promise<void>
   return service.send(message);
 }
 
-// Composition — caller orchestrates
-async function processReport(orderId: string, config: Config) {
+// Composition — caller orchestrates; every dependency arrives as a parameter
+async function processReport(orderId: string, config: Config, emailService: EmailService) {
   const db = createConnection(config.databaseUrl);  // Config passed in
   const report = fetchOrderReport(db, orderId);
   const email = prepareReportEmail(report, config.recipientEmail);
@@ -185,7 +185,7 @@ Decision engine. The agent analyzes units in code it writes or reviews, producin
 
 ## The Unix Philosophy Reference
 
-McIlroy, Pike, and Thompson articulated four principles (1978):
+McIlroy, Pinson, and Tague articulated four principles in the 1978 Bell System Technical Journal foreword (Pike and Kernighan's *The UNIX Programming Environment*, 1984, later popularized the philosophy):
 
 1. **Make each program do one thing well.** Concentrate all efforts on that one thing. Don't clutter the program with unrelated features.
 2. **Expect the output of every program to become the input of another, yet unknown, program.** Don't insist on interactive input; don't produce extraneous information.

package/skills/composability-auditor/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "composability-auditor",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Unix Philosophy-inspired composability analysis: identify reuse blockers, decompose self-sufficient units into composable pieces with standard interfaces",
   "author": "iceinvein",
   "type": "prompt",

package/skills/contract-enforcer/SKILL.md

@@ -15,9 +15,9 @@ A structured correctness framework based on Bertrand Meyer's *Design by Contract
 - Functions that handle external input, state transitions, or cross-module boundaries
 - "Is this function correct?" / "What are the edge cases?"
 - "What does this function guarantee?"
-- Reviewing boundary behavior or error handling
+- Reviewing boundary behavior (what a function requires and guarantees)
 
-**Not for:** Trivial getters, simple property access, configuration code, pure mappings with obvious behavior.
+**Not for:** Trivial getters, simple property access, configuration code, pure mappings with obvious behavior. For what happens after valid input enters the system — try/catch strategy, error classification, recovery boundaries — use `error-strategist` (which routes precondition/validation design back here).
 
 ## The Process
 
@@ -132,8 +132,8 @@ These are design decisions, not implementation details. The human owns them.
 
 ## The Meyer Principles (Reference)
 
-1. **Separate commands from queries.** Functions that return values should not have side effects. Functions with side effects should not return values. When you must violate this, document it in the contract.
-2. **Demand no more, promise no less.** Preconditions should be as weak as possible (accept the widest reasonable input). Postconditions should be as strong as possible (guarantee the most specific output).
-3. **The client is responsible for preconditions.** The function does not need to "handle" invalid input gracefully — it needs to fail clearly and immediately when preconditions are violated.
+1. **Separate commands from queries.** Functions that return values should not have side effects, and vice versa (the dedicated `cqs-auditor` skill covers this in full). When you must violate it, document that in the contract.
+2. **Demand only what you need, and demand it explicitly.** Require nothing beyond what the implementation truly relies on, but state every requirement precisely; postconditions should guarantee the most specific output you can honestly promise. Meyer's style is demanding: a strong, explicit precondition beats tolerant code that silently accepts anything.
+3. **The client is responsible for preconditions.** The function does not need to "handle" invalid input gracefully — it needs to fail clearly and immediately when preconditions are violated. Enforce preconditions at trust boundaries (external input, public APIs); internally, assert rather than handle.
 4. **Inheritance respects contracts.** Subtypes may weaken preconditions (accept more) and strengthen postconditions (guarantee more), but never the reverse.
 5. **Contracts are documentation that compiles.** The best contracts are checked at runtime (assertions, type narrowing, validation) — not just written in comments.

package/skills/contract-enforcer/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-enforcer",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Meyer-inspired Design by Contract: preconditions, postconditions, invariants, and failure contracts for non-trivial functions",
   "author": "iceinvein",
   "type": "prompt",

package/skills/coupling-auditor/SKILL.md

@@ -113,7 +113,7 @@ Coupling is about *between* modules. Cohesion is about *within* a module. They'r
 - **Low coupling + low cohesion** = modules are independent but internally disorganized. Fix the cohesion.
 - **Low coupling + high cohesion** = the goal. Modules are internally focused and externally independent.
 
-This skill addresses coupling only. If a module has cohesion problems (doing too many unrelated things), that's a signal for the Module Secret Auditor skill.
+This skill addresses coupling only. If a module has cohesion problems (doing too many unrelated things), that's a signal for the `cohesion-analyzer` skill.
 
 ## Guard Rails
 
@@ -131,7 +131,7 @@ This skill addresses coupling only. If a module has cohesion problems (doing too
 2. **Maximize cohesion within modules.** A module that does one thing well has fewer reasons to couple with others.
 3. **Coupling type matters more than coupling count.** One content coupling is worse than five data couplings.
 4. **Coupling is directional.** A depends on B ≠ B depends on A. Map the direction.
-5. **The Law of Demeter operationalizes coupling.** "Don't talk to strangers" — a module should only call methods on its direct dependencies, not on objects returned by those dependencies.
+5. **The Law of Demeter operationalizes coupling.** Later work (Lieberherr's Law of Demeter, 1987, not Constantine & Yourdon) turned this into the "don't talk to strangers" rule: a module should only call methods on its direct dependencies. See the `demeter-enforcer` skill.
 
 ## Common Mistakes
 

package/skills/coupling-auditor/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "coupling-auditor",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Constantine & Yourdon-inspired coupling analysis: classify, measure, and reduce interdependence between modules",
   "author": "iceinvein",
   "type": "prompt",

package/skills/cover-letter/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: cover-letter
 description: >
-  Full-lifecycle cover letter suite. Generates, audits, and rewrites cover letters
-  from a resume and job description. Produces markdown, DOCX, and PDF outputs.
-  Optimizes for human-sounding prose, evidence alignment with the resume, and
-  coverage of the job description's key requirements. Also scores letters for
-  AI-generated-content risk, structure, correctness, and tone. Use when the user
-  says "cover letter", "write cover letter", "draft cover letter", "audit cover
-  letter", "rewrite cover letter", "optimize cover letter", "check cover letter",
-  or shares a resume and job description together. Route to the right subcommand:
-  write, audit, rewrite, or persona.
+  Use for generic or ambiguous cover-letter requests: the user says "cover
+  letter" or "help me apply" without a clear write/audit/rewrite verb, invokes
+  /cover-letter, or asks what the suite can do. Routes to the subcommand
+  skills and holds the suite's shared conventions (file I/O, naming, state
+  directory, writing principles). When the phrasing already names the action
+  (write/draft, audit/score, rewrite/fix, persona/voice), trigger that
+  subcommand skill directly instead.
 argument-hint: "[write|audit|rewrite|persona] [...args]"
 ---
 
@@ -25,7 +23,7 @@ a human wrote them, fit the job, and match the resume.
 | `/cover-letter write` | Generate a letter from resume + job description | `cover-letter-write` |
 | `/cover-letter audit <file>` | Score a letter on content, structure, AI-ness, correctness | `cover-letter-audit` |
 | `/cover-letter rewrite <file>` | Humanize and realign an existing letter | `cover-letter-rewrite` |
-| `/cover-letter persona [create\|list\|use\|show]` | Manage writing voice/tone profiles | `cover-letter-persona` |
+| `/cover-letter persona [create\|list\|use\|show\|delete]` | Manage writing voice/tone profiles | `cover-letter-persona` |
 
 When invoked without arguments, list these subcommands and ask which one the
 user wants.
@@ -65,7 +63,7 @@ Letters are emitted as three sibling files by default:
 
 - `<out>/<company>-<role>-<YYYY-MM-DD>.md` (canonical source)
 - `<out>/<company>-<role>-<YYYY-MM-DD>.docx` (via `pandoc`)
-- `<out>/<company>-<role>-<YYYY-MM-DD>.pdf` (via `pandoc` with `--pdf-engine=weasyprint` or `wkhtmltopdf`; fall back to chromium headless if neither is present)
+- `<out>/<company>-<role>-<YYYY-MM-DD>.pdf` (via `pandoc`; the PDF engine fallback chain is defined once, in cover-letter-write's emit step)
 
 Default output directory: `./cover-letters/`. Override with `--out <dir>`.
 
@@ -80,7 +78,7 @@ Personas and session state live at `~/.config/cover-letter/`:
 ~/.config/cover-letter/
 ├── personas/           # one JSON per persona
 ├── active-persona      # plain text, contains active persona name
-└── last-run.json       # last write inputs (for fast rewrite/audit)
+└── last-run.json       # written by cover-letter-write step 7; read by audit/rewrite when the user gives no paths
 ```
 
 Create the directory on first write. Never touch anything outside it when
@@ -111,13 +109,13 @@ and rewrite skills enforce them; the audit skill scores against them.
    "I hope this message finds you well". Every one of these is an AI tell and
    a wasted first sentence.
 7. **No sentimental cliches.** A cover letter is not a Hallmark card. Avoid
-   "hit close to home", "struck a chord", "resonated with me", "spoke to me",
-   "dream come true", "right up my alley", "a perfect fit", "meant to be",
-   "the stars aligned", "at the end of the day", "wearing my heart on my
-   sleeve". These are corny; they signal either AI prose or a writer reaching
-   for warmth they have not earned with specificity. Replace with a concrete
-   reason the thing connects: which paragraph of the post, which past project
-   of yours, which shared problem.
+   the likes of "hit close to home", "struck a chord", "resonated with me";
+   the canonical list lives in cover-letter-audit's AI phrase list, which the
+   audit scores against (do not maintain a second copy here). These are corny;
+   they signal either AI prose or a writer reaching for warmth they have not
+   earned with specificity. Replace with a concrete reason the thing connects:
+   which paragraph of the post, which past project of yours, which shared
+   problem.
 8. **Human closing.** Skip "Please do not hesitate to contact me". A plain
    sign-off works better.
 9. **Length.** 250 to 400 words by default. Shorter is almost always better.
@@ -155,7 +153,7 @@ A typical end-to-end flow:
 1. `/cover-letter persona create` (one-time, or skip for default professional voice)
 2. `/cover-letter persona use <name>` (optional)
 3. `/cover-letter write --resume <resume> --jd <jd>` produces the letter plus a self-audit score
-4. If score below 85 or user unhappy, `/cover-letter rewrite <file>` with optional `--focus humanize|tighten|align`
+4. If the score lands below Strong (under 80 per cover-letter-audit's rating table) or the user is unhappy, `/cover-letter rewrite <file>` with optional `--focus humanize|tighten|align`
 5. `/cover-letter audit <file>` for a final independent score
 
 Each subcommand skill details its own workflow, inputs, and outputs.

package/skills/cover-letter/skill.json

@@ -1,10 +1,15 @@
 {
   "name": "cover-letter",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Cover letter suite router. Dispatches to write, audit, rewrite, or persona subcommands and shares file I/O (PDF, DOCX, MD/MDX, URL), output formats, and writing conventions across the suite",
   "author": "iceinvein",
   "type": "prompt",
-  "tools": ["claude", "cursor", "codex", "gemini"],
+  "tools": [
+    "claude",
+    "cursor",
+    "codex",
+    "gemini"
+  ],
   "files": {
     "prompt": "SKILL.md"
   },

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

@@ -1,24 +1,22 @@
 ---
 name: cover-letter-audit
 description: >
-  Score a cover letter on a 100-point scale across four categories: content and
-  fit (35), structure (20), voice and humanness (25), correctness (20). Detects
-  AI-generated-content signals (burstiness, known AI phrase list, vocabulary
-  diversity, em-dash count), checks that every claim aligns with the resume,
-  validates job-description coverage without keyword stuffing, flags filler
-  openers, and produces a prioritized fix list. Works with markdown, DOCX, PDF,
-  or pasted letter text. Use when the user says "audit cover letter", "score
-  cover letter", "review cover letter", "check cover letter for AI", "does this
-  cover letter sound human", "rate my cover letter", "is this cover letter any
-  good", or shares a finished letter and asks for feedback.
+  Use when the user asks to audit, score, rate, or review an existing cover
+  letter ("audit cover letter", "does this sound AI", "rate my cover letter",
+  "is this any good"), or shares a finished letter asking for feedback.
+  Scores 100 points across content/fit, structure, voice/humanness, and
+  correctness, detects AI-content signals, and returns a prioritized fix
+  list. Accepts markdown, DOCX, PDF, or pasted text. NOT for writing a letter
+  (cover-letter-write) or applying edits (cover-letter-rewrite).
 argument-hint: "<letter-file-or-text> [--resume <file>] [--jd <file|url|text>] [--format md|json|table]"
 ---
 
 # Cover Letter Auditor
 
 Score a cover letter and return prioritized fixes. The score combines four
-categories to 100 points. A letter at 85+ is publishable; below 75 needs
-targeted rework; below 60 should be rewritten.
+categories to 100 points. The Rating table below maps score bands to actions
+and is the single source of truth for thresholds across the cover-letter
+suite; other skills cite it rather than restating numbers.
 
 ## Inputs
 
@@ -41,7 +39,9 @@ Flags:
 ## Parsing
 
 Same extraction tools as `cover-letter-write`. If the letter is a DOCX or PDF,
-convert to markdown first via pandoc or pdftotext.
+convert to markdown first via pandoc or pdftotext. If no letter path is given,
+check `~/.config/cover-letter/last-run.json` for the most recent write output
+before asking.
 
 ## Scoring rubric
 
@@ -67,9 +67,9 @@ coverage points: 3 to specificity, 3 to motivation.
 | Check | Points | Pass criteria |
 |-------|--------|--------------|
 | Sections present | 5 | Opening hook, fit/evidence, motivation, close all identifiable |
-| Opening | 5 | First sentence is specific and not on the filler-opener list. Generic opener costs all 5 points. |
+| Opening | 5 | First sentence is specific and not a filler opener (the "I am writing to express..." family, items 1-4 of the AI phrase list below). Generic opener costs all 5 points. |
 | Close | 3 | Two sentences max, no "do not hesitate to contact me", plain sign-off |
-| Length | 4 | Word count within target band (default 250-400, or persona band) |
+| Length | 4 | Word count within the declared target band: default 250-400, or the `--length short|standard|long` band from cover-letter-write (150-220 / 250-400 / 380-460) when one was declared or recorded in last-run.json |
 | Formatting | 3 | No stray markdown headings, no bullet lists, no tables, no code blocks. Letter reads as prose. |
 
 ### 3. Voice and Humanness (25)
@@ -78,15 +78,15 @@ coverage points: 3 to specificity, 3 to motivation.
 |-------|--------|--------------|
 | Burstiness | 7 | Sentence length standard deviation >= 5 words; at least one sentence under 10 words and one over 20 per paragraph |
 | AI phrase count | 6 | Zero phrases from the AI phrase list below. Minus 1 per phrase, down to 0. |
-| Vocabulary diversity (TTR) | 4 | Type-Token Ratio >= 0.5 for letters over 200 words. Below 0.4 earns 0. |
-| Contraction/formality match | 3 | Contraction frequency within persona band (default 0.3-0.6). If no persona, accept 0.2-0.7. |
+| Vocabulary diversity (TTR) | 4 | Type-Token Ratio >= 0.5 for letters over 200 words earns 4; 0.40-0.49 earns 2; below 0.4 earns 0. |
+| Contraction/formality match | 3 | Contraction frequency within ±0.15 of the persona's `contraction_frequency` scalar (default persona 0.4 → accept 0.25-0.55). If no persona, accept 0.2-0.7. |
 | Em-dash count | 2 | Zero em-dashes. Em-dashes are a strong AI-output signal; each one costs both points. |
-| Passive voice | 3 | At most 10% of clauses in passive voice (or persona cap) |
+| Passive voice | 3 | At most 10% of sentences in passive voice (or persona cap) |
 
 #### AI phrase list
 
-Flag any occurrence of these, case-insensitive. Extends the blog-analyze list
-with cover-letter-specific killers:
+Flag any occurrence of these, case-insensitive. This is the canonical list for
+the whole cover-letter suite (write and rewrite reference it):
 
 Cover-letter specific:
 

package/skills/cover-letter-audit/skill.json

@@ -1,10 +1,15 @@
 {
   "name": "cover-letter-audit",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Scores a cover letter on 100 points across content/fit, structure, voice/humanness, and correctness; detects AI-generated-content signals and produces a prioritized fix list",
   "author": "iceinvein",
   "type": "prompt",
-  "tools": ["claude", "cursor", "codex", "gemini"],
+  "tools": [
+    "claude",
+    "cursor",
+    "codex",
+    "gemini"
+  ],
   "files": {
     "prompt": "SKILL.md"
   },

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

@@ -1,14 +1,13 @@
 ---
 name: cover-letter-persona
 description: >
-  Create and manage writing personas for cover letters using the NNGroup 4-dimension
-  tone framework (funny-serious, formal-casual, respectful-irreverent, enthusiastic-
-  matter-of-fact) adapted for professional correspondence. Personas define readability
-  target, sentence length distribution, contraction frequency, passive voice cap, and
-  do/don't lists. Used by cover-letter-write and cover-letter-rewrite to enforce a
-  consistent voice across all applications. Use when the user says "persona",
-  "voice", "tone", "writing style", "make it sound more formal", "more casual",
-  "create persona", "use persona", or asks how to tune the voice of their letters.
+  Use when the user wants to tune the voice of their cover letters: "persona",
+  "voice", "tone", "writing style", "make it sound more formal/casual",
+  "create persona", "use persona". Manages reusable writing personas on the
+  NNGroup 4-dimension tone framework; personas set readability, sentence
+  lengths, contraction frequency, passive-voice cap, and do/don't lists,
+  consumed by cover-letter-write and cover-letter-rewrite. NOT for one-off
+  edits to a letter (cover-letter-rewrite).
 argument-hint: "[create|list|use|show|delete] [persona-name]"
 ---
 
@@ -36,7 +35,7 @@ Create the directory on first run. Use kebab-case filenames (e.g.,
 |---------|---------|
 | `/cover-letter persona create [name]` | Interactive interview; writes a new persona file |
 | `/cover-letter persona list` | Show all saved personas |
-| `/cover-letter persona use <name>` | Set the active persona for this session |
+| `/cover-letter persona use <name>` | Set the active persona (persists until changed) |
 | `/cover-letter persona show <name>` | Print full persona profile |
 | `/cover-letter persona delete <name>` | Remove a persona file (ask to confirm) |
 
@@ -173,10 +172,11 @@ should I go with?"
 
 ## List command
 
-Glob `~/.config/cover-letter/personas/*.json` and render:
+Glob `~/.config/cover-letter/personas/*.json` and render ("Updated" is the
+persona file's modification time; no schema field needed):
 
-| Persona | Stage | Tone hint | Last used |
-|---------|-------|-----------|-----------|
+| Persona | Stage | Tone hint | Updated |
+|---------|-------|-----------|---------|
 | senior-eng-default | senior | serious, mid-formal | 2026-04-20 |
 | casual-startup | senior | serious, casual | 2026-04-24 |
 
@@ -189,7 +189,7 @@ Read the named persona JSON. Write its name to
 
 ```
 Active persona: senior-eng-default
-- Tone: serious (0.75), mid-formal (0.45), respectful (0.25), matter-of-fact (0.45)
+- Tone: serious (0.75), mid-formal (0.45), respectful (0.25), mid-enthusiastic (0.45)
 - Sentence length target: 17 words ± 8
 - Contractions: 40%; passive cap: 10%
 - Signature: "Best,\nAlex Chen\nalex@example.com | portfolio.example.com"

package/skills/cover-letter-persona/skill.json

@@ -1,10 +1,15 @@
 {
   "name": "cover-letter-persona",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Reusable writing personas built on the NNGroup 4-dimension tone framework, adapted for professional correspondence and used by cover-letter-write and cover-letter-rewrite",
   "author": "iceinvein",
   "type": "prompt",
-  "tools": ["claude", "cursor", "codex", "gemini"],
+  "tools": [
+    "claude",
+    "cursor",
+    "codex",
+    "gemini"
+  ],
   "files": {
     "prompt": "SKILL.md"
   },