refresh-skills

name

refresh-skills

description

Audit and update this repo's own .claude/skills against the current codebase, fixing drifted file paths, function signatures, texts.ts keys, route paths, and command names so the skills don't rot. Use whenever the user asks to refresh, audit, update, or check the skills, after a change that touches code the skills reference (a renamed helper, a changed signature, a moved route), or when a skill turns out to be inaccurate. Run it before relying on a skill you haven't used in a while.

refresh-skills

Skills encode real file paths, function signatures, texts.ts keys and commands — and the code moves underneath them. A stale skill is worse than none: it leads confidently to code that doesn't compile or, worse, silently breaks a guardrail (we have already shipped a skill with a wrong function signature). This skill treats the skills like code: extract their checkable claims, verify each against the current repo, and fix what drifted — without changing what a skill is for. (Concrete example: when trust moved from users.trusts[] to the trusts join collection, the filterTrustedItems helper was deleted — several skills still referenced it and had to be repointed at the view rules + $lib/server/trust.ts.)

1. Scope

Operate on every SKILL.md under .claude/skills/*/ in this repo (and, for a skill that explicitly references the other repo — e.g. schema-change citing allerleih-backend — verify those claims against that repo too). Don't touch skills in other repos otherwise.

2. Extract the checkable claims

For each SKILL.md, pull out every statement that can rot — these are facts, not prose:

• File/dir paths (src/lib/server/trust.ts, scripts/seed/scenarios/).
• Imported symbols + signatures (isTrusting(pb, trusterId, trusteeId), createNotification(pb, recipient, sender?, type, relatedId, body)).
• texts.ts keys (texts.errors.changesNotSaved, texts.notifications.pushTitle).
• Route paths / endpoints (/legal/accept, /api/contact/{id}).
• Commands & scripts (npx vitest run, npm test, npm run seed).
• Collection / field names and any line-number hints (~line 824).

3. Verify each against the code

Use Grep/Glob/Read — don't trust memory:

• Path → confirm it exists (Glob). If moved, find the new location.
• Signature → grep the export function/export const/export async function and Read it. Confirm arg names, order, count, and async/sync. This is the highest-value check — a wrong signature is the failure that bites hardest.
• texts.* key → grep the dotted path in src/lib/texts.ts; confirm it resolves to a real entry (watch for duplicate parent keys — e.g. two notifications: blocks).
• Command → confirm the script exists in package.json.
• Line-number hint → it's approximate; if the thing has moved far, update the "~line N".
• Embedded code snippet that's meant to compile → reconcile it against the real signatures it uses. Where cheap, sanity-check by type-checking (npm run check) a throwaway use of it.

4. Fix the drift — facts only

Edit each SKILL.md to match reality, preserving the skill's wording, structure, and intent:

• Correct the path / signature / key / command / line hint to the current truth.
• Keep the description's meaning and trigger boundary intact — fix a stale path inside it, but don't re-scope what the skill triggers on.
• A referenced symbol that was renamed → update to the new name. Removed with no replacement, or a behavioural change you can't confidently map → don't guess; flag it for the human in your report and leave a clear note rather than inventing an API.

5. Report

Output a compact drift table and the fixes you made:

skill            claim                                   status     action
new-route        filterTrustedItems(items,userId,...)    DRIFTED    → helper deleted; trust is view-rule enforced, use $lib/server/trust.ts
seed-scenario    npm run seed                             ok         —
add-notification texts.notifications.pushTitle            ok         —
schema-change    allerleih-backend/pb_migrations/         ok         —

Use four statuses: ok (matches reality), DRIFTED (wrong value that would mislead or break — fix it), IMPRECISE (points at the right thing but mis-describes it — e.g. an inline union called a named "type", or a paraphrased command/line-hint — fix the wording), GONE (API removed with no replacement — flag for the human, don't invent one).

End with anything you flagged for human judgement (GONE items, ambiguous renames). If nothing drifted, say so plainly — a clean audit is a valid result.

When to run

After merging changes that touch code a skill references, before leaning on a skill you haven't used recently, or periodically. This is the operational half of the CLAUDE.md "keep in sync" rule: that rule keeps docs aligned with code; this keeps the skills aligned too.