src/skills-refresh.ts

Functions

Imports

It imports src/agents-schema.ts, src/agents.ts, src/encoding.ts, src/env.ts, src/jobs.ts. Imported by src/index.ts.

Source

1// The weekly skills refresh. It fetches each model's prompting guide, and when one
2// moved it posts a job: the driver runs the `model-refresh` skill in
3// DrDustinEdwards/claude-skills and opens a pull request. Nothing applies without
4// the merge. A cron, not a tool (CLAUDE.md, tool surface rule).
5//
6// It may propose edits to .claude/** because it scores nothing: it proposes to a
7// separate repo as a gated job, and a human merges.
8
9import type { Env } from "./env";
10import type { Agent } from "./agents";
11import { postJob } from "./jobs";
12import { bytesToHex } from "./encoding";
13import { noFlags } from "./agents-schema";
14
15const DOCS = "https://platform.claude.com/docs/en";
16const OVERVIEW = `${DOCS}/about-claude/models/overview.md`;
17const guideUrl = (slug: string) => `${DOCS}/build-with-claude/prompt-engineering/prompting-claude-${slug}.md`;
18
19export const SKILLS_NAMESPACE = "claude-skills";
20export const SKILLS_REFRESH_ACTOR = "agent:skills-refresh";
21export const SCHEDULE_KEY = "skills:refresh:schedule";
22export const guideKey = (slug: string) => `skills:guides:${slug}`;
23
24// Monday. The cron fires daily and this decides whether today is the day, so
25// changing the day is a KV edit rather than a redeploy.
26export const DEFAULT_DAY_UTC = 1;
27
28// test/skills-refresh.test.ts asserts this matches scripts/model-guides.mjs in the
29// claude-skills repo.
30const MODEL_ID = /\bclaude-(fable|mythos|opus|sonnet|haiku)-\d[a-z0-9-]*/g;
31const DATED_SUFFIX = /-\d{8}$/;
32
33export function discoverModels(overview: string): string[] {
34  const ids = new Set<string>();
35  for (const m of overview.matchAll(MODEL_ID)) ids.add(m[0]);
36  return [...new Set([...ids].map((id) => id.replace(/^claude-/, "").replace(DATED_SUFFIX, "")))].sort();
37}
38
39export async function sha256Hex(text: string): Promise<string> {
40  return bytesToHex(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
41}
42
43export interface Schedule {
44  enabled: boolean;
45  dayUtc: number;
46  reason: string | null;
47}
48
49// Unset takes the default and runs; a KV error disables. Unlike readMode's
50// fail-to-off, because a wrong run here posts one gated job (a duplicate is refused
51// while one is open), not branches to five repos.
52export async function readSchedule(kv: KVNamespace): Promise<Schedule> {
53  let raw: string | null;
54  try {
55    raw = await kv.get(SCHEDULE_KEY);
56  } catch (err) {
57    return {
58      enabled: false,
59      dayUtc: DEFAULT_DAY_UTC,
60      reason: `could not read ${SCHEDULE_KEY}: ${err instanceof Error ? err.message : String(err)}`,
61    };
62  }
63  if (raw === null) return { enabled: true, dayUtc: DEFAULT_DAY_UTC, reason: `${SCHEDULE_KEY} is unset; using the default` };
64  let parsed: unknown;
65  try {
66    parsed = JSON.parse(raw);
67  } catch {
68    return { enabled: false, dayUtc: DEFAULT_DAY_UTC, reason: `${SCHEDULE_KEY} does not hold JSON` };
69  }
70  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
71    return { enabled: false, dayUtc: DEFAULT_DAY_UTC, reason: `${SCHEDULE_KEY} does not hold an object` };
72  }
73  const value = parsed as { enabled?: unknown; dayUtc?: unknown };
74  const enabled = value.enabled === undefined ? true : value.enabled === true;
75  const day = value.dayUtc;
76  if (day !== undefined && (typeof day !== "number" || !Number.isInteger(day) || day < 0 || day > 6)) {
77    return { enabled: false, dayUtc: DEFAULT_DAY_UTC, reason: `${SCHEDULE_KEY} holds a dayUtc that is not an integer 0-6` };
78  }
79  return { enabled, dayUtc: day === undefined ? DEFAULT_DAY_UTC : day, reason: null };
80}
81
82async function fetchGuide(url: string): Promise<{ status: number; text: string | null }> {
83  const res = await fetch(url, { headers: { "user-agent": "capsid skills-refresh" } });
84  if (res.status === 404) return { status: 404, text: null };
85  if (!res.ok) throw new Error(`${url} returned ${res.status}`);
86  return { status: res.status, text: await res.text() };
87}
88
89// A narrowly scoped synthetic caller. It may post a job to one namespace and
90// nothing else, so a bug here cannot reach another namespace or a repo.
91export function skillsRefreshAgent(): Agent {
92  return {
93    id: SKILLS_REFRESH_ACTOR,
94    name: "skills-refresh",
95    kind: "cron",
96    actor: SKILLS_REFRESH_ACTOR,
97    scopes: {
98      namespaces: [SKILLS_NAMESPACE],
99      repos: [],
100      tools: ["capsid_work_jobs"],
101      grants: ["write"],
102      // Derived, so a new flag cannot be missed.
103      flags: noFlags(),
104    },
105    admin: false,
106    row: null,
107  };
108}
109
110export interface RefreshOutcome {
111  ran: boolean;
112  skipped: string | null;
113  checked: number;
114  changed: string[];
115  posted: string[];
116  refused: { slug: string; reason: string }[];
117}
118
119function jobBody(slug: string, url: string): string {
120  return [
121    `Run the model-refresh skill against the ${slug} prompting guide.`,
122    "",
123    `The guide moved since the last check. Fetch it with \`npm run guides\` in`,
124    `DrDustinEdwards/claude-skills, read \`guides/${slug}.md\` in full, then follow`,
125    "`skills/model-refresh/SKILL.md` exactly.",
126    "",
127    `Source: ${url}`,
128    "",
129    "Rewrite ONLY model-facing calibration, and ask the skill's three questions",
130    "before every edit. A gate, a shipped-artifact rule, or a ruling is refused,",
131    "and the refusals belong in the summary. Every changed line carries its",
132    "citation comment.",
133    "",
134    "Open one pull request and BLOCK with its link. Never merge: the merge is the",
135    "human gate and it is the only thing that applies any of this.",
136  ].join("\n");
137}
138
139// How a skip on any day but the configured one begins: the cron fires daily, so that
140// skip is not a run, and the run ledger (src/index.ts) leaves it out.
141export const NOT_ITS_DAY = "today is UTC day";
142
143export async function runSkillsRefresh(env: Env, now: Date): Promise<RefreshOutcome> {
144  const empty: RefreshOutcome = { ran: false, skipped: null, checked: 0, changed: [], posted: [], refused: [] };
145
146  const schedule = await readSchedule(env.APP_KV);
147  if (!schedule.enabled) return { ...empty, skipped: schedule.reason ?? "disabled" };
148  if (now.getUTCDay() !== schedule.dayUtc) {
149    return { ...empty, skipped: `${NOT_ITS_DAY} ${now.getUTCDay()}, not ${schedule.dayUtc}` };
150  }
151
152  const overview = await fetchGuide(OVERVIEW);
153  if (!overview.text) throw new Error(`models overview not found at ${OVERVIEW}`);
154  const slugs = discoverModels(overview.text);
155  // Fail closed on a shape change. Reporting "nothing changed" against zero
156  // parsed models would quietly retire this cron and say nothing.
157  if (slugs.length === 0) throw new Error(`discovered 0 models in ${OVERVIEW}; the page shape changed`);
158
159  const changed: string[] = [];
160  const posted: string[] = [];
161  const refused: { slug: string; reason: string }[] = [];
162  const agent = skillsRefreshAgent();
163
164  for (const slug of slugs) {
165    const url = guideUrl(slug);
166    const guide = await fetchGuide(url);
167    const prior = await env.APP_KV.get(guideKey(slug));
168    if (guide.status === 404) continue;
169
170    const hash = await sha256Hex(guide.text ?? "");
171    if (prior === hash) continue;
172    changed.push(slug);
173
174    // The hash is stored only after the job is queued, or a failed post would mark
175    // the guide seen and never refresh it.
176    const result = await postJob(env, agent, now, {
177      namespace: SKILLS_NAMESPACE,
178      title: `skills: refresh for ${slug}`,
179      body: jobBody(slug, url),
180      priority: 3,
181      gate_required: true,
182    });
183    if (result.ok) {
184      posted.push(slug);
185      await env.APP_KV.put(guideKey(slug), hash);
186    } else {
187      // A duplicate open job means last week's refresh is unfinished. Record the hash
188      // so the next real change is what re-posts.
189      const reason = result.refusal ?? "refused";
190      refused.push({ slug, reason });
191      if (/already has an open job/i.test(reason)) await env.APP_KV.put(guideKey(slug), hash);
192    }
193  }
194
195  return { ran: true, skipped: null, checked: slugs.length, changed, posted, refused };
196}