feat: improve skill review scores for 5 skills (+73% avg)

.github/workflows/skill-review.yml

@@ -0,0 +1,22 @@
+# Tessl Skill Review — runs on PRs that change any SKILL.md; posts scores as one PR comment.
+# Docs: https://github.com/tesslio/skill-review
+name: Tessl Skill Review
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "**/SKILL.md"
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: tesslio/skill-review@main
+      # Optional quality gate (off by default — do not enable unless user asked):
+      # with:
+      #   fail-threshold: 70

library/skills/content/write/SKILL.md

@@ -1,26 +1,63 @@
+---
+name: write
+description: "Generate content in the correct genre for a target receiver using the Signal Theory framework. Resolves all 5 signal dimensions (Mode, Genre, Type, Format, Structure), applies the matching genre skeleton, and adapts to the receiver's decoding capacity. Supports genres: brief, spec, plan, transcript, note, pitch, proposal, report, email, social-post, outline, changelog, ADR. Use when producing any structured written content for a specific audience."
+user-invocable: true
+triggers:
+  - write
+  - write content
+  - draft
+  - generate content
+  - write brief
+  - write spec
+  - write email
+  - write report
+---
+
 # /write
 
 > Generate content in the correct genre for the target receiver.
 
 ## Usage
-```
+
+```bash
 /write <genre> --for <person> [--topic "<topic>"] [--tone <tone>]
 ```
 
-## What It Does
-Produces content using the Signal Theory framework: resolves all 5 dimensions (Mode, Genre, Type, Format, Structure), applies the correct genre skeleton, and matches the receiver's decoding capacity. Looks up the person's preferred genre from the people registry.
+## Arguments
 
-## Implementation
-1. **Resolve receiver** -- look up person in people registry (CLAUDE.md or 10-team/context.md).
-2. **Select genre** -- use the specified genre or infer from receiver preference.
-3. **Load genre skeleton** -- apply the structured template (brief, spec, plan, pitch, etc.).
-4. **Assemble context** -- `/assemble` relevant topic context if needed.
-5. **Generate** -- produce content matching genre structure, receiver bandwidth, and tone.
-6. **Validate** -- check against the 6 encoding principles (mode-message alignment, entropy preservation, etc.).
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `<genre>` | enum | required | Content genre (brief, spec, plan, pitch, email, etc.) |
+| `--for` | string | required | Target receiver (role or name from people registry) |
+| `--topic` | string | — | Subject matter for the content |
+| `--tone` | string | `professional` | Tone override: `formal`, `casual`, `technical`, `persuasive` |
 
-Supported genres: brief, spec, plan, transcript, note, pitch, proposal, report, email, social-post, outline, changelog, ADR.
+## Workflow
+
+1. **Resolve receiver** — look up person in people registry (CLAUDE.md or 10-team/context.md). If not found, ask the user for the receiver's role and communication preferences.
+2. **Select genre** — use the specified genre or infer from receiver preference.
+3. **Load genre skeleton** — apply the structured template for the genre:
+   - **brief**: TL;DR → Key Points → Action Required (executive summary)
+   - **spec**: Overview → Requirements → Constraints → Interface → Edge Cases (technical)
+   - **plan**: Goal → Phases → Timeline → Risks → Success Criteria (strategic)
+   - **pitch**: Hook → Problem → Solution → Proof → Ask (persuasive)
+   - **email**: Subject → Context → Ask → Next Steps (direct)
+   - **report**: Summary → Data → Analysis → Recommendations (analytical)
+   - **ADR**: Status → Context → Decision → Consequences (architectural)
+   - Other genres (note, transcript, proposal, social-post, outline, changelog): follow standard structure for the format.
+4. **Assemble context** — run `/assemble` to gather relevant topic context if needed.
+5. **Generate** — produce content matching genre structure, receiver bandwidth, and tone.
+6. **Validate** — check output against the 6 encoding principles:
+   1. **Mode-message alignment** — written content reads well; verbal content speaks well
+   2. **Entropy preservation** — no critical information lost in compression
+   3. **Receiver bandwidth match** — complexity fits the receiver's expertise level
+   4. **Genre convention** — output follows the skeleton structure for the chosen genre
+   5. **Signal-to-noise ratio** — every sentence earns its place; no filler
+   6. **Actionability** — receiver knows exactly what to do after reading
+   If validation fails on any principle, revise the output before delivering.
 
 ## Examples
+
 ```bash
 # Write a brief for a salesperson
 /write brief --for "sales rep" --topic "Q2 pricing update"
@@ -31,3 +68,26 @@ Supported genres: brief, spec, plan, transcript, note, pitch, proposal, report,
 # Write a pitch for a client
 /write pitch --for "prospect" --topic "platform demo"
 ```
+
+## Output
+
+```markdown
+## Brief: Q2 Pricing Update
+
+**For**: Sales team
+**Genre**: Brief (executive summary format)
+**Signal dimensions**: Written → Brief → Informational → Bullet → Top-down
+
+### Key Changes
+- Enterprise tier increases 12% effective July 1
+- Existing contracts honored through renewal date
+- New "Startup" tier at $49/mo replaces free trial
+
+### Talking Points
+1. Frame as investment in reliability and support SLA
+2. Grandfather existing customers — emphasize loyalty value
+3. Startup tier opens new pipeline segment
+
+### Action Required
+Update pricing decks by June 15. Notify active prospects before announcement.
+```

library/skills/development/build/SKILL.md

@@ -1,22 +1,43 @@
+---
+name: build
+description: "Detect project type, compile, and report errors with actionable fixes. Auto-detects toolchain from config files (mix.exs, package.json, Cargo.toml, go.mod, Makefile), runs the appropriate build command, captures output, and returns structured diagnostics with suggested fixes. Handles monorepos by detecting and building each sub-project. Use when you need to compile a project, diagnose build failures, or verify a clean build before deploy."
+user-invocable: true
+triggers:
+  - build
+  - compile
+  - make
+  - build project
+  - clean build
+  - build errors
+---
+
 # /build
 
 > Detect project type, compile, and report errors with actionable fixes.
 
 ## Usage
-```
+
+```bash
 /build [path] [--clean] [--verbose] [--target <env>]
 ```
 
-## What It Does
-Scans the project root for config files (mix.exs, package.json, Cargo.toml, go.mod, Makefile), runs the appropriate build command, captures output, and reports errors with structured diagnostics. Handles monorepos by detecting and building each sub-project.
+## Arguments
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `path` | string | `.` | Project root or sub-project path |
+| `--clean` | flag | false | Remove build artifacts before building |
+| `--verbose` | flag | false | Show full build output for debugging |
+| `--target` | string | `dev` | Build environment: `dev`, `prod`, `test` |
+
+## Workflow
 
-## Implementation
 1. **Detect project type** from config files in priority order.
-2. **Check prerequisites** -- verify toolchain installed, deps fetched.
-3. **Clean** (if `--clean`) -- remove build artifacts.
-4. **Build** -- run the build command, capture stdout/stderr/exit code/duration.
-5. **Parse errors** -- extract file paths, line numbers, error types. Suggest fixes.
-6. **Report** -- structured build report with errors, warnings, artifacts.
+2. **Check prerequisites** — verify toolchain installed, deps fetched.
+3. **Clean** (if `--clean`) — remove build artifacts.
+4. **Build** — run the build command, capture stdout/stderr/exit code/duration.
+5. **Parse errors** — extract file paths, line numbers, error types. Suggest fixes.
+6. **Report** — structured build report with errors, warnings, artifacts.
 
 | Config File | Language | Build Command |
 |-------------|----------|---------------|
@@ -27,6 +48,7 @@ Scans the project root for config files (mix.exs, package.json, Cargo.toml, go.m
 | Makefile | Make | `make` |
 
 ## Examples
+
 ```bash
 # Build current project
 /build
@@ -40,3 +62,25 @@ Scans the project root for config files (mix.exs, package.json, Cargo.toml, go.m
 # Verbose output for debugging build issues
 /build --verbose --clean
 ```
+
+## Output
+
+```markdown
+## Build Report
+
+- **Project**: my-app (Elixir)
+- **Command**: `mix compile`
+- **Duration**: 4.2s
+- **Result**: FAILED (2 errors, 1 warning)
+
+### Errors
+1. `lib/parser.ex:42` — undefined function `String.trim_leading/2` → Use `String.trim_leading/1` with a trim pattern
+2. `lib/router.ex:18` — module `Plug.Router` is not available → Run `mix deps.get`
+
+### Warnings
+1. `lib/utils.ex:7` — variable `result` is unused
+
+### Suggested Fixes
+- Run `mix deps.get` to fetch missing dependencies
+- Fix function call at `lib/parser.ex:42`
+```

library/skills/security/harden/SKILL.md

@@ -1,28 +1,54 @@
+---
+name: harden
+description: "Apply security hardening to a project — headers, configs, dependencies, and best practices. Scans current security posture and applies measures: HSTS, CSP, X-Frame-Options headers; dependency CVE updates; auth strengthening; input validation; config tightening. Produces a before/after comparison. Use when preparing a project for production deploy or after a security audit flags issues."
+user-invocable: true
+triggers:
+  - harden
+  - security hardening
+  - secure project
+  - add security headers
+  - fix vulnerabilities
+  - harden server
+---
+
 # /harden
 
-> Apply security hardening to a project -- headers, configs, dependencies, and best practices.
+> Apply security hardening to a project — headers, configs, dependencies, and best practices.
 
 ## Usage
-```
+
+```bash
 /harden [path] [--focus <headers|deps|auth|all>] [--dry-run]
 ```
 
-## What It Does
-Analyzes the project's current security posture and applies hardening measures: security headers, dependency updates, authentication improvements, input validation, and configuration tightening. Produces a before/after comparison.
+## Arguments
 
-## Implementation
-1. **Assess current state** -- scan for security headers, dependency versions, auth config, input validation.
-2. **Generate hardening plan** -- prioritized list of improvements by impact.
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `path` | string | `.` | Project root to harden |
+| `--focus` | enum | `all` | Hardening scope: `headers`, `deps`, `auth`, `all` |
+| `--dry-run` | flag | false | Show hardening plan without applying changes |
+
+## Workflow
+
+1. **Assess current state** — detect project framework and scan each domain:
+   - **Headers**: grep response middleware/plugs for HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy.
+   - **Dependencies**: run `mix audit` (Elixir), `npm audit` (Node), `cargo audit` (Rust), or `pip-audit` (Python) to list known CVEs.
+   - **Auth**: check password hashing algorithm and rounds, session timeout settings, CSRF protection, token expiration.
+   - **Input**: check for validation on user-facing endpoints (Ecto changesets, Zod schemas, JSON Schema, etc.).
+   - **Config**: check for debug mode, exposed server headers, cookie flags (Secure, HttpOnly, SameSite).
+2. **Generate hardening plan** — prioritized list of improvements by severity (critical CVEs first, then missing headers, then config).
 3. **Apply changes** (unless `--dry-run`):
-   - **Headers**: add HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy.
-   - **Dependencies**: update packages with known CVEs.
-   - **Auth**: strengthen password policy, session config, token expiration.
-   - **Input**: add validation schemas where missing.
-   - **Config**: disable debug mode, hide server info, set secure cookie flags.
-4. **Verify** -- run security scan to confirm improvements.
-5. **Report** -- before/after security posture comparison.
+   - **Headers**: add missing security headers in the appropriate middleware layer.
+   - **Dependencies**: update vulnerable packages to patched versions; flag any that require major version bumps.
+   - **Auth**: strengthen hashing rounds, add session timeout, enable CSRF if missing.
+   - **Input**: add validation schemas on unvalidated endpoints.
+   - **Config**: disable debug mode, suppress server version header, set secure cookie flags.
+4. **Verify** — re-run the same audit commands from step 1. If issues remain, review and re-apply fixes.
+5. **Report** — before/after security posture comparison with specific changes listed.
 
 ## Examples
+
 ```bash
 # Full hardening
 /harden
@@ -36,3 +62,26 @@ Analyzes the project's current security posture and applies hardening measures:
 # Focus on dependency updates
 /harden --focus deps
 ```
+
+## Output
+
+```markdown
+## Security Hardening Report
+
+- **Project**: my-app (Phoenix + SvelteKit)
+- **Mode**: Applied (not dry-run)
+
+### Before/After
+
+| Category | Before | After | Changes |
+|----------|--------|-------|---------|
+| Headers | 1/6 | 6/6 | +HSTS, +CSP, +X-Frame, +X-Content-Type, +Referrer-Policy |
+| Dependencies | 3 CVEs | 0 CVEs | Updated plug_cowboy, phoenix_html, jose |
+| Auth | Weak | Strong | Session timeout 30min, bcrypt rounds 12→14, CSRF enabled |
+| Config | Debug on | Hardened | Debug off, server header hidden, secure cookies |
+
+### Critical Fixes Applied
+1. **CVE-2025-1234** in `plug_cowboy` 2.6.0 → 2.7.1 (request smuggling)
+2. **Missing CSP header** → Added strict policy blocking inline scripts
+3. **Session cookie** missing `Secure` and `SameSite=Strict` flags
+```

library/skills/strategy/brainstorm/SKILL.md

@@ -1,23 +1,44 @@
+---
+name: brainstorm
+description: "Generate 3–5 distinct approaches to a problem with pros, cons, effort estimates, and a reasoned recommendation. Forces structured divergent thinking before jumping to implementation. Use when facing a technical decision, architecture choice, or strategic tradeoff where multiple viable paths exist."
+user-invocable: true
+triggers:
+  - brainstorm
+  - brainstorm ideas
+  - explore options
+  - compare approaches
+  - tradeoff analysis
+  - decision matrix
+---
+
 # /brainstorm
 
-> Generate 3-5 approaches with pros, cons, and a reasoned recommendation.
+> Generate 3–5 approaches with pros, cons, and a reasoned recommendation.
 
 ## Usage
-```
+
+```bash
 /brainstorm "<problem>" [--options <n>] [--constraint "<constraint>"]
 ```
 
-## What It Does
-Takes a problem or decision, generates multiple distinct approaches, evaluates each on pros/cons/effort, and provides a reasoned recommendation. Forces structured thinking before jumping to implementation.
+## Arguments
 
-## Implementation
-1. **Clarify** -- restate the problem as a clear question.
-2. **Explore** -- generate N approaches (default: 3, max: 5). Each must be genuinely different, not variations of the same idea.
-3. **Evaluate** -- for each approach, list pros, cons, effort estimate, risk level.
-4. **Decide** -- recommend the best approach with clear reasoning.
-5. **Plan** -- break the recommended approach into concrete next steps.
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `"<problem>"` | string | required | The problem or decision to brainstorm |
+| `--options` | int | `3` | Number of approaches to generate (max 5) |
+| `--constraint` | string | — | Constraint to apply across all approaches |
+
+## Workflow
+
+1. **Clarify** — restate the problem as a clear question.
+2. **Explore** — generate N approaches (default: 3, max: 5). Each must be genuinely different, not variations of the same idea.
+3. **Evaluate** — for each approach, list pros, cons, effort estimate, risk level.
+4. **Decide** — recommend the best approach with clear reasoning.
+5. **Plan** — break the recommended approach into concrete next steps.
 
 ## Examples
+
 ```bash
 # Brainstorm a technical decision
 /brainstorm "How should we handle auth in the platform?"
@@ -28,3 +49,32 @@ Takes a problem or decision, generates multiple distinct approaches, evaluates e
 # Brainstorm with constraints
 /brainstorm "Hiring a frontend dev" --constraint "budget under $8K/mo"
 ```
+
+## Output
+
+```markdown
+## Brainstorm: How should we handle auth in the platform?
+
+### Approach 1: Session-based auth with Phoenix.Token
+- **Pros**: Simple, built-in, no external deps
+- **Cons**: Harder to scale across services, sticky sessions
+- **Effort**: 1 week | **Risk**: Low
+
+### Approach 2: JWT with refresh tokens
+- **Pros**: Stateless, works across services, mobile-friendly
+- **Cons**: Token revocation complexity, larger payload
+- **Effort**: 2 weeks | **Risk**: Medium
+
+### Approach 3: OAuth2 with third-party provider (Auth0/Clerk)
+- **Pros**: Battle-tested, social login, MFA out of the box
+- **Cons**: Vendor lock-in, monthly cost, latency
+- **Effort**: 1 week | **Risk**: Low
+
+### ✅ Recommendation: Approach 2 (JWT)
+Stateless auth fits the multi-service architecture. Implement short-lived access tokens (15 min) with rotating refresh tokens to mitigate revocation concerns.
+
+### Next Steps
+1. Define token payload schema
+2. Implement refresh token rotation in the auth service
+3. Add middleware to Phoenix and SvelteKit
+```