@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/enhance-skill-prompts/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: enhance-skill-prompts
+description: >
+  Upgrade how an existing SKILL.md instructs, not what it does: freedom, a
+  classification contract, one worked example, an evidence rubric, effort. Use
+  when "enhance this skill's prompts", "upgrade skill authoring", or "apply
+  the prompt playbook".
+license: MIT
+effort: high
+---
+
+# enhance-skill-prompts — Upgrade HOW a skill instructs, never WHAT it does
+
+**Degree of freedom: LOW-to-MEDIUM.** This is a fragile transformation. A
+well-meant rewrite can change behavior. Follow the phases in order. Preserve
+intent, scope, and family semantics exactly. If a change would alter
+behavior, scope, or read-only / plan-only / apply-now stance, stop and flag
+it instead.
+
+Grounded in [docs/PROMPT-ENHANCEMENT-PLAYBOOK.md](../../docs/PROMPT-ENHANCEMENT-PLAYBOOK.md)
+and the annotated exemplar
+[references/exemplar-audit-auth-flows.md](references/exemplar-audit-auth-flows.md).
+Live reference after the exemplar was applied:
+`skills/audit-auth-flows/SKILL.md`. New skill from scratch →
+`meta-skill-creator`.
+
+## Phase 0 — Classify the skill  [HIGH freedom]
+
+Read the target SKILL.md and determine:
+
+- **Family & register:** audit/plan (interpretive → mostly HIGH) vs
+  housekeep/deploy/migration (fragile sequences → LOW where a step must be
+  exact).
+- **Judgment points:** triage, severity, root cause, winner-selection → T2/T3.
+- **Fragile steps:** probes, baseline capture, destructive ops → T1 LOW.
+- **Existing example:** is the `## Worked example` a real few-shot (chain plus output shape on a concrete case) or a placeholder?
+- **Effort tier (T7):** which family the skill belongs to, and therefore which `effort:` it declares.
+
+State the classification before editing. It decides which techniques apply.
+
+## Phase 1 — Apply T1–T8 (only where they fit)  [HIGH freedom]
+
+Apply in this order. Skip any technique that does not fit and record why.
+
+**T1 — Declare degrees of freedom.** Short register line under the H1.
+Where mixed, tag fragile phases `[LOW freedom — run exactly]` and
+interpretive ones `[HIGH freedom]`. Do not over-constrain interpretive
+audits or under-constrain fragile sequences.
+
+**T2 — One named-stage judgment frame.** The stages a conclusion must
+pass through (audits: Observe → Interpret → Classify → Severity; plans:
+Propose → Risk → Keep-working → Phase). Place it ONCE near the top and
+reference it. It defines what a finding must contain, not how to think:
+reasoning depth comes from `effort:` (T7), and generic "think step by
+step" or "double-check" prose is dead weight on Opus 5.5.
+
+**T3 — Exactly one worked example.** The chain AND the output shape on a
+realistic case, labeled illustrative. Put it right after the T2 frame.
+
+**T4 — Self-critique rubric before output.** Explicit, answerable checks
+(evidenced-not-assumed, reproducible, severity-justified, right-owner,
+no-false-safety). Plan skills: run this before presenting the burndown.
+Opus 5.5 self-verifies unprompted, so each rubric line must name the
+evidence it is checked against (a tool result, a rendered rect, a header,
+a CI run); a line that is a generic re-check ("verify your work",
+"double-check") is cut. Principle-based ("constitutional-style") checking
+belongs here as a rubric, not a label.
+
+**T5 — Terminology consistency.** One term per concept. Unify
+gate/check/guard, finding/issue/problem, user/caller/client to the skill's
+dominant term.
+
+**T6 — Conciseness.** Cut restated context the agent already has. Never
+trim a fragile step's exactness. Net tokens should usually drop even after
+T2+T3.
+
+**T7 — Effort routing.** Declare `effort:` in frontmatter by family:
+audit / plan / judge / security / architecture → `high` (`xhigh` only for
+the hardest planning, with a measured reason); mechanical, read-only,
+formatting, handoff, inventory → `low`; ordinary implementation → omit
+(Opus 5.5 defaults to `medium`, which matches Opus 5 at high). A read-only
+inventory skill may add `context: fork` + `agent: Explore` to keep the main
+context clean. Cursor ignores the key; `validate:skills` checks its value.
+Effort is the only thinking control on Opus 5.5 — never steer depth with
+prose ("think harder", "don't overthink", "double-check").
+
+**T8 — Volume, shape, and communication.** Each rule once, at normal
+volume, with its reason — drop MUST / NEVER / CRITICAL markers, "be
+thorough", and update suppressors ("no preamble", "don't narrate"): Opus
+5.5 follows instructions literally, so emphasis over-triggers and
+suppressors leave the user blind between tool calls. State the success
+condition instead of a prohibition list. Exception: frontend design
+direction works best as *named* default patterns to avoid (cream
+background, italic accent word in headlines, "01 / 02 / 03" section
+labels, monospace labels, pill buttons, Inter / Roboto, purple gradients,
+three equal cards) — "avoid a generic AI look" swaps one default for
+another. Numbered steps only for fragile sequences (destructive ops, auth,
+migrations, baseline capture); judgment phases get outcomes, constraints,
+and how to verify. The always-on verification rule already asks for an
+intent line, load-bearing notes and a standalone recap; do not repeat it
+per skill and never suppress it ("no preamble", "hold findings"). Skills
+that run unattended add one line saying when the turn may end.
+
+## How to reason
+
+1. **Observe** — existing H1 register, phases, examples, body length
+2. **Interpret** — which of T1–T8 are missing vs already present as headings or keys
+3. **Classify** — apply / skip-with-reason / stop (would change behavior)
+4. **Severity** — a trigger or stance change is an invalid edit
+
+## Worked example
+
+> **Observe:** `meta-skill-creator` has T1 and a technique table; no `## Worked example`.
+> **Interpret:** the table mention is not T3; the agent still has no few-shot.
+> **Classify:** add one `## Worked example` + `## Self-critique` after the table; do not rewrite Anatomy or frontmatter.
+> **Invariant:** description triggers unchanged; still "create a pack SKILL.md".
+
+## Self-critique before reporting
+
+- **Headings exist** — T3 is `## Worked example`, T4 is `## Self-critique…`, not a table cell
+- **Behavior same** — no phase-order, stance, or trigger change
+- **One example** — not a second tutorial
+- **Right owner** — new skill from scratch → `meta-skill-creator`
+
+## Phase 2 — Preserve invariants  [LOW freedom — run exactly]
+
+The edit is invalid if any of these break:
+
+- Same **name, description triggers, and scope** — routing must not change.
+- Same **behavior and stance** — read-only stays read-only; apply-now stays
+  apply-now; plan-only stays plan-only; phase order and Definition-of-Done
+  coverage unchanged in substance.
+- **House limits** — description ≤320 chars (same folding as
+  `scripts/validate-skills.mjs`), body <500 lines, name matches dir.
+- **Frontmatter:** `name` and `description` untouched unless a within-budget
+  description change is explicitly requested. Adding or adjusting `effort:`
+  (T7) is allowed and is not a routing change.
+- Cross-references use live skill names; the responsive skill is `audit-responsive`.
+- Strip `<!-- TECHNIQUE -->` comments from live SKILL.md (they belong only
+  in the exemplar).
+
+If any invariant would break, revert that change and note it.
+
+## Phase 3 — Report the diff  [LOW freedom — do not skip]
+
+Do not silently rewrite. Present, per skill:
+
+1. **Classification** — family | register | judgment points | fragile steps | has-example?
+2. **Technique table** — technique | applied? | where | why-skipped-if-not
+3. **Section diffs** — before/after for each change
+4. **Invariant check** — each invariant | holds?
+
+Apply on approval. For a batch, finish one skill as reference, get
+sign-off, then proceed.
+
+## Definition of Done
+
+- [ ] Skill classified before editing
+- [ ] T1–T8 applied or skipped with a reason
+- [ ] Invariants verified; frontmatter triggers unchanged
+- [ ] Diff reported; applied only on approval
+
+## Related
+
+- `meta-skill-creator` — new SKILL.md from scratch
+- `audit-skill-conflicts` — routing / coherence after a batch
+- `validate:skills` — per-file spec after edits

package/skills/enhance-skill-prompts/references/exemplar-audit-auth-flows.md

@@ -0,0 +1,311 @@
+> Teaching copy of `audit-auth-flows` with technique annotations (`<!-- TECHNIQUE -->`).
+> Live shipped file (comments stripped; pack frontmatter unchanged):
+> `skills/audit-auth-flows/SKILL.md`.
+
+---
+name: audit-auth-flows
+description: >
+  Read-only audit of app-layer auth: route×gate matrix, session lifecycle,
+  OAuth, provider traps (getSession vs getUser, middleware-only gates,
+  CVE-2025-29927). Use when "audit our auth" or "check middleware protection".
+  RLS → plan-rls-audit.
+license: MIT
+effort: high
+---
+
+<!-- TECHNIQUE: effort routing. A security audit is judgment work, so the
+frontmatter declares `effort: high`; the model default is medium. Claude Code
+honors the key, Cursor ignores it. Mechanical fixed-sequence skills declare
+`effort: low`. Read-only does not mean low: audits are read-only and high. -->
+
+# audit-auth-flows — Middleware is edge routing, not a security boundary
+
+## Degree of freedom: MIXED — declared per phase
+
+<!-- TECHNIQUE: T1 degree-of-freedom declaration (Anthropic official). The
+skill states its register up front and per phase, so the agent knows where
+to reason freely and where to follow exact steps. It pairs with the `effort:`
+key above: the register line says where to reason freely; the effort key says
+how deep. This header is the single most important addition. -->
+
+- Phases 0–4 (discovery, judgment): **[HIGH freedom]** — reason about what
+  you find; checklists prompt investigation, they are not tick-scripts.
+- Phase 5 (live probes) and the getSession grep: **[LOW freedom — run
+  exactly]** — a skipped probe is an unproven claim, not a saved step.
+
+Read-only. Map the auth surface and prove, route by route, that identity is
+verified where it matters. Then stop. Hand fixes to a follow-up session.
+
+**2026 consensus (official, post CVE-2025-29927):** Next.js middleware
+runs before cache and routing. Vercel: *"We do not recommend Middleware
+to be the sole method of protecting routes in your application."* An
+audit that only reads `middleware.ts` and declares the app safe has
+missed the point. Defense in depth: edge + route handler / server action
++ data layer. Each layer covers a different part of the request path.
+
+## How to reason in this audit
+
+<!-- TECHNIQUE: T2 named-stage chain (not "think step by step"). Thinking is
+always on for the model and `effort` in frontmatter sets its depth, so this
+is not a reasoning script: it is the record shape every finding carries, so
+no finding can be written without its evidence, its meaning, its bucket, and
+a justified severity. Placed once, referenced by each phase. -->
+
+Every finding is recorded in this shape, in this order:
+
+1. **Observe** — what does the code/probe actually show? (quote the line or the response)
+2. **Interpret** — what does that mean for who can reach what? (don't assume intent)
+3. **Classify** — real exposure / defense-in-depth-gap / correct-as-is / needs-a-probe
+4. **Severity** — by blast radius: unauth data access & auth bypass = critical;
+   everything else justified against what an attacker actually gains.
+
+If you cannot complete Interpret from static code, it is a **needs-a-probe**
+item for Phase 5, not a conclusion.
+
+## Worked example
+
+<!-- TECHNIQUE: T3 one worked example, shown in the chain's order AND the
+finding-row shape. Examples pin format — the model matches their length and
+structure — so label it illustrative, keep it realistic, and add a second only
+where it varies the judgment (a different Classify outcome), not a second
+tutorial. The output-format section carries the rest. -->
+
+> **Observe:** `middleware.ts` matcher is `['/dashboard/:path*']`. The route
+> `/api/orders/[id]` has no check in the handler.
+> **Interpret:** API routes are not under the matcher, so middleware never
+> runs on them; the order endpoint is reachable without auth. Layout-level
+> checks don't cover direct API calls.
+> **Classify:** real exposure (not merely a defense-in-depth gap — data is
+> actually reachable).
+> **Severity:** critical — unauthenticated data access.
+> **Finding row:** `/api/orders/[id]` | edge+route | critical | matcher
+> excludes /api; handler has no `getUser()` check | probe P5-a confirmed
+> 200 while logged out.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **audit-auth-flows** (this) | Session lifecycle, route×gate matrix, OAuth, provider traps |
+| `audit-security` | OWASP checklist (injection, headers, deps) — may fix inline |
+| `plan-security-audit` | Plan-only hardening burndown |
+| `plan-rls-audit` | Data-layer who-can-read-which-rows |
+| `plan-secrets-audit` | Where `service_role` / keys live |
+| `plan-privacy-compliance` | Consent / policy vs collection — not session gates |
+| `backend-patterns` | Building the middleware / guard fixes after this audit |
+| `test-exploratory` | Live guest vs logged-in probe (runtime complement to this static matrix) |
+
+---
+
+## Phase 0 — Detect the auth stack  [HIGH freedom]
+
+Identify: provider (Supabase Auth / NextAuth / Clerk / Auth0 / custom),
+framework protection (Next.js middleware + `matcher`, route guards,
+server-action checks), session transport (cookie vs `localStorage` vs
+`Authorization` header), token model (JWT vs server session). Enumerate
+pages, API routes, server actions, edge functions, admin areas. Record
+the pinned framework version — auth CVEs are version-gated.
+
+---
+
+## Phase 1 — Route × gate coverage matrix  [HIGH freedom — the centerpiece]
+
+Every protected route / action, one row. Apply the reasoning chain per row.
+
+| route/action | intended access | gate that protects it | verified server-side? | data-layer backstop? |
+
+Hunt the gaps this exposes:
+
+- **Matcher holes** — `config.matcher` misses a protected path. API
+  routes and server actions often bypass page middleware — each needs
+  its own check.
+- **Layout-only protection** — a layout/wrapper is a client-side
+  illusion. It does not gate data fetches or direct API/action calls.
+- **Middleware-as-only-gate** — the CVE-2025-29927 class. Any route
+  where middleware is the *sole* authorization layer is a finding
+  **regardless of framework version or host**. Patching the CVE is not
+  defense in depth.
+- **Server action exposure** — Next.js server actions are POST
+  endpoints callable directly. Each mutating action must check identity
+  itself.
+- **Unlisted routes** — grep the router; do not trust the matcher list.
+
+---
+
+## Phase 2 — Provider and framework traps  [HIGH freedom, except the grep = LOW]
+
+**Supabase (check first on this stack):**
+
+- **[LOW freedom — run exactly]** `grep -rn "getSession(" <server-code-paths>`.
+  <!-- TECHNIQUE: T1 applied to the fragile bit. Promoted from advisory
+  prose to an explicit "run exactly" step so the agent cannot reason past
+  the grep. -->
+  Treat every server-side hit as a finding until proven client-side-only.
+  Official JS docs: cookie/storage values *may not be authentic*;
+  `getSession()` is strongly advised against for authorization.
+  `getUser()` performs a network request to the Auth server and *can* be
+  used to base authorization rules. Newer SSR guides also use
+  `getClaims()` to *refresh* cookies — that is not a substitute for
+  verifying identity at the handler.
+- Service-role key on any client-exposed path → `plan-secrets-audit`.
+  RLS assumed but not enforcing → `plan-rls-audit` (data-layer
+  backstop; this skill is the app layer above it).
+- `autoRefreshToken` disabled without manual refresh; JWT expiry
+  absurdly short (<300s) hammering refresh.
+
+**Next.js CVE-2025-29927** (GHSA-f82v-jwr5-mffw, critical): bypass
+authorization if the check occurs only in middleware, via the internal
+`x-middleware-subrequest` header. **Patched:** 12.3.5 / 13.5.9 /
+14.2.25 / 15.2.3. **Impacted:** self-hosted `next start` and
+`output: 'standalone'`. Vercel-hosted apps were incidentally
+protected; Netlify and Cloudflare Workers were not affected. Workaround
+if unpatched: drop `x-middleware-subrequest` before it hits Next.
+If below the fix → P0 *and* a defense-in-depth finding. Also sweep
+later Next.js auth CVEs (do not treat 29927 as the only one).
+
+**General rule:** any "the framework enforces auth at the edge"
+assumption is a finding, whatever the framework.
+
+**NextAuth / Clerk / Auth0** — session strategy (JWT vs database),
+callback / redirect validation, and whether `auth()` / session checks
+actually run server-side per protected operation.
+
+---
+
+## Phase 3 — Session lifecycle  [HIGH freedom]
+
+**Cookies** — `HttpOnly`, `Secure`, `SameSite` (Lax min, Strict for
+sensitive); scoped path/domain; not readable by JS. Token in
+`localStorage` is XSS-exfiltratable — flag it; CSRF-vs-XSS must be a
+deliberate choice.
+
+**Logout that actually logs out** — a stateless JWT stays valid until
+expiry if logout only clears the client. Confirm server-side
+invalidation (Supabase `signOut` revokes the refresh token). Probe it
+(Phase 5). Official sessions FAQ: access tokens can still be presented
+after sign-out unless the app also checks revocation / uses
+`getUser()`.
+
+**Rotation & timeouts** — rotate on privilege change (login, role
+elevation) to kill fixation; idle timeout and absolute-max lifetime
+both present. Current norm: short access tokens, longer **rotated**
+refresh tokens with reuse detection, capped absolute session.
+
+**Refresh-token rotation + reuse detection** — official Supabase
+sessions docs: a refresh token is single-use, with two exceptions
+(default **10s reuse interval** — do not widen; parent-token retry for
+lost responses). Outside those exceptions the **whole session family
+is revoked**. Disabling that in Advanced Settings is "generally not
+recommended" — flag if widened or disabled.
+
+---
+
+## Phase 4 — Credentials, OAuth, authorization  [HIGH freedom]
+
+**OAuth / OIDC** — `state` (CSRF on the callback), PKCE for public
+clients, redirect-URI allowlist exact-match, provider `email_verified`
+checked before trust, account-linking collisions handled.
+
+**Credential flows** — reset tokens single-use + expiring + not leaked
+in URL/referrer; **user enumeration** via differing error text or
+timing on login/reset/signup; rate limiting on auth endpoints
+specifically; MFA state cannot be skipped mid-flow.
+
+**Authorization above the data layer** — not just "is logged in" but
+"is allowed"; IDOR on API params (`/api/orders/:id` scoped to caller?);
+admin routes gated by role server-side. Name which layer each control
+lives in. `plan-rls-audit` owns the data-layer half.
+
+---
+
+## Phase 5 — Live probes  [LOW freedom — run each, in order, non-prod]
+
+<!-- TECHNIQUE: T1 low-freedom exact steps for the fragile part. These are
+not suggestions; each is a labeled probe whose result is evidence. The
+reasoning chain's "needs-a-probe" items resolve here. -->
+
+Force the failures rather than only reading code. Log each as
+`P5-x | expected | actual | evidence`:
+
+- **P5-a** Hit each protected route / API / action **unauthenticated** →
+  expect deny (not a redirect that still returns data).
+- **P5-b** Replay a **logged-out** session token → expect reject.
+- **P5-c** Tamper the session cookie / swap another user's identifier →
+  reject.
+- **P5-d** IDOR: as user A, request user B's object by id → deny.
+- **P5-e** If Next.js is version-vulnerable or self-hosted: send
+  `x-middleware-subrequest` and confirm WAF/edge *and* a route-handler
+  check still stop it.
+- **P5-f** User-enumeration: compare wrong-password vs nonexistent-user
+  (text + timing).
+
+Do not run these against production. Do not write exploit PoCs into
+the repo.
+
+---
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+<!-- TECHNIQUE: T4 evidence check before output. Opus 5.5 self-verifies
+without being told, so this is not a "double-check your work" step — every
+item names a specific piece of evidence (quote, probe, layer) a finding must
+carry, and findings without it are dropped or downgraded. Add items that
+name evidence; never generic "verify" lines. -->
+
+Challenge every finding against this rubric; drop or downgrade any that fail:
+
+1. **Evidenced, not assumed** — quoted line or probe result? If it rests on
+   "the code probably…", mark unconfirmed or run the probe.
+2. **Reproducible** — did the probe succeed twice, or once? Flaky ≠ finding.
+3. **Severity justified** — "critical" requires actual unauth access or
+   bypass, not theoretical risk.
+4. **Right layer** — app-layer (yours) or data-layer (→ `plan-rls-audit`)?
+5. **No false safety** — did you confirm a gate *works*, or only that it
+   *exists*? A check a probe bypassed is critical, not a pass.
+
+---
+
+## Definition of Done
+
+- [ ] Auth stack + framework version recorded
+- [ ] Degree-of-freedom respected: Phase 5 probes and the getSession grep
+      run exactly, in order
+- [ ] Route×gate matrix complete; every row reasoned
+      Observe→Interpret→Classify→Severity
+- [ ] Matcher holes, layout-only, middleware-as-sole-gate, unprotected
+      server actions surfaced
+- [ ] `getSession()`-for-authz grepped; `getUser()` confirmed on every
+      server gate
+- [ ] CVE-2025-29927 (and later auth CVEs) checked against the pinned version
+- [ ] Cookie flags, localStorage exposure, CSRF pairing assessed
+- [ ] Server-side logout invalidation confirmed by probe; rotation +
+      idle/absolute timeouts present
+- [ ] Refresh reuse interval not widened; family revocation not disabled
+- [ ] OAuth state / PKCE / redirect-allowlist / email_verified checked
+- [ ] User-enumeration, reset tokens, auth-endpoint rate limits, MFA-skip
+      checked
+- [ ] App-layer authorization (roles, IDOR, admin) split from the RLS half
+- [ ] Live probes run non-prod; each logged pass/fail
+- [ ] Self-critique rubric applied; unevidenced/flaky findings dropped or
+      downgraded
+- [ ] Read-only — findings presented, not patched
+
+## Output format
+
+1. **Route × gate matrix** — the table, gaps highlighted
+2. **Findings** — issue | layer (edge/route/data) | severity (critical =
+   unauth access / auth bypass) | file:line or probe | fix shape — each
+   finding in the worked-example shape
+3. **Provider-trap list** — exact call to change (`getSession` →
+   `getUser`, etc.)
+4. **Probe log** — P5-x | expected | actual | evidence
+5. **Fix plan** — auth-bypass and getSession-authz first, then session
+   lifecycle, then enumeration/OAuth. Handoffs: `plan-rls-audit`,
+   `plan-secrets-audit`, `plan-security-audit`, `backend-patterns`.
+   Present and stop.
+
+<!-- TECHNIQUE: T5 terminology — this file uses finding (not issue/problem),
+gate (not check/guard) for the auth layer, and probe for live evidence.
+T6 conciseness — neighbor table kept (routing), official CVE/getSession/
+getClaims/10s facts kept (not restated twice). Teaching comments live only
+in this exemplar; strip them from the live SKILL.md. -->