@namzu/sdk 45.0.0 → 46.0.0

package/src/schedules/spec.ts

@@ -0,0 +1,210 @@
+/**
+ * The words an operator or a model types for a schedule, turned into a spec.
+ *
+ * | Input | Spec |
+ * |---|---|
+ * | `at 2026-09-24T09:00`, `at 2026-09-24 09:00`, `at 09:00`, `in 30m` | `at` |
+ * | an ISO instant with `Z` or an offset, with or without `at` | `at` |
+ * | `every 30m`, `every 2h`, `every 1d`, `every 90m` | `every` |
+ * | five-field cron, `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly` | `cron` |
+ *
+ * A local time is read in `tz`. Nothing is rounded silently: `every 30s` is
+ * refused and the refusal names the nearest interval that is allowed.
+ */
+
+import { parseCronExpression } from './cron.js'
+import { ScheduleValidationError } from './errors.js'
+import { assertSpecFires, nextFireTime } from './next-fire.js'
+import type { ScheduleSpec } from './types.js'
+import { civil, hostTimeZone, instantsForWall, validateTimeZone, wallOf } from './tz.js'
+
+const MINUTE = 60_000
+const UNIT_MS: Readonly<Record<string, number>> = {
+	s: 1_000,
+	sec: 1_000,
+	secs: 1_000,
+	second: 1_000,
+	seconds: 1_000,
+	m: MINUTE,
+	min: MINUTE,
+	mins: MINUTE,
+	minute: MINUTE,
+	minutes: MINUTE,
+	h: 60 * MINUTE,
+	hr: 60 * MINUTE,
+	hrs: 60 * MINUTE,
+	hour: 60 * MINUTE,
+	hours: 60 * MINUTE,
+	d: 24 * 60 * MINUTE,
+	day: 24 * 60 * MINUTE,
+	days: 24 * 60 * MINUTE,
+	w: 7 * 24 * 60 * MINUTE,
+	week: 7 * 24 * 60 * MINUTE,
+	weeks: 7 * 24 * 60 * MINUTE,
+}
+
+export interface ParseScheduleOptions {
+	/** "Now", for `in …`, `at HH:MM` and the anchor of `every`. Default: the clock. */
+	readonly now?: Date
+	/** Zone a local time and a cron expression are read in. Default: the host's. */
+	readonly tz?: string
+}
+
+/** `90m` → 5 400 000. Throws on anything else. */
+export function parseDuration(text: string): number {
+	const match = /^(\d+)\s*([a-z]+)$/i.exec(text.trim())
+	const unit = match ? UNIT_MS[(match[2] ?? '').toLowerCase()] : undefined
+	if (!match || unit === undefined) {
+		throw new ScheduleValidationError(
+			`"${text}" is not a duration (write it like 30m, 2h, 1d)`,
+			text,
+		)
+	}
+	return Number(match[1]) * unit
+}
+
+function formatInterval(ms: number): string {
+	if (ms % (24 * 60 * MINUTE) === 0) return `${ms / (24 * 60 * MINUTE)}d`
+	if (ms % (60 * MINUTE) === 0) return `${ms / (60 * MINUTE)}h`
+	return `${ms / MINUTE}m`
+}
+
+function everySpec(text: string, now: Date): ScheduleSpec {
+	const ms = parseDuration(text)
+	if (ms < MINUTE) {
+		throw new ScheduleValidationError(
+			`every ${text} is shorter than the minimum interval; the nearest allowed is every 1m`,
+			text,
+		)
+	}
+	if (ms % MINUTE !== 0) {
+		const down = Math.floor(ms / MINUTE) * MINUTE
+		const up = down + MINUTE
+		throw new ScheduleValidationError(
+			`every ${text} is not a whole number of minutes; the nearest allowed are every ${formatInterval(down)} and every ${formatInterval(up)}`,
+			text,
+		)
+	}
+	const anchor = new Date(Math.floor(now.getTime() / MINUTE) * MINUTE)
+	return { kind: 'every', everyMs: ms, anchorAt: anchor.toISOString() }
+}
+
+/** Resolve a local `YYYY-MM-DD HH:MM` in `tz` to one instant (the earlier of two). */
+function localToInstant(
+	y: number,
+	mo: number,
+	d: number,
+	h: number,
+	mi: number,
+	tz: string,
+	token: string,
+): number {
+	const wall = Date.UTC(y, mo - 1, d, h, mi)
+	const c = civil(wall)
+	if (c.year !== y || c.month !== mo || c.day !== d || h > 23 || mi > 59) {
+		throw new ScheduleValidationError(`"${token}" is not a real date and time`, token)
+	}
+	const instants = instantsForWall(wall, tz)
+	if (instants.length === 0) {
+		throw new ScheduleValidationError(
+			`"${token}" does not exist in ${tz} (the clocks skip it); pick a time outside the change`,
+			token,
+		)
+	}
+	return instants[0] as number
+}
+
+function atSpec(text: string, now: Date, tz: string): ScheduleSpec {
+	const t = text.trim()
+	// An instant with its own offset: taken as written.
+	if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})$/i.test(t)) {
+		const at = Date.parse(t)
+		if (!Number.isFinite(at)) throw new ScheduleValidationError(`"${t}" is not a date`, t)
+		return { kind: 'at', at: new Date(at).toISOString() }
+	}
+	const full = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{1,2}):(\d{2})$/.exec(t)
+	if (full) {
+		const [, y, mo, d, h, mi] = full.map(Number) as number[]
+		const at = localToInstant(
+			y as number,
+			mo as number,
+			d as number,
+			h as number,
+			mi as number,
+			tz,
+			t,
+		)
+		return { kind: 'at', at: new Date(at).toISOString() }
+	}
+	const clock = /^(\d{1,2}):(\d{2})$/.exec(t)
+	if (clock) {
+		const h = Number(clock[1])
+		const mi = Number(clock[2])
+		if (h > 23 || mi > 59) throw new ScheduleValidationError(`"${t}" is not a time of day`, t)
+		// The next time the wall clock reads HH:MM, today or tomorrow.
+		const today = civil(wallOf(now.getTime(), tz))
+		for (let add = 0; add < 3; add++) {
+			const day = new Date(Date.UTC(today.year, today.month - 1, today.day + add))
+			const instants = instantsForWall(
+				Date.UTC(day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate(), h, mi),
+				tz,
+			)
+			const first = instants.find((i) => i > now.getTime())
+			if (first !== undefined) return { kind: 'at', at: new Date(first).toISOString() }
+		}
+		throw new ScheduleValidationError(`"${t}" does not occur in ${tz} in the next two days`, t)
+	}
+	throw new ScheduleValidationError(
+		`"${t}" is not a time (write 2026-09-24 09:00, 09:00, or an ISO instant)`,
+		t,
+	)
+}
+
+/**
+ * Parse schedule words into a spec, validated: the zone exists, the
+ * expression parses, and the spec fires at least once after `now`.
+ */
+export function parseScheduleSpec(input: string, options: ParseScheduleOptions = {}): ScheduleSpec {
+	const now = options.now ?? new Date()
+	const tz = validateTimeZone(options.tz ?? hostTimeZone())
+	const text = input.trim()
+	if (text === '') throw new ScheduleValidationError('a schedule is required', '')
+	let spec: ScheduleSpec
+	const lower = text.toLowerCase()
+	if (lower.startsWith('every ')) {
+		spec = everySpec(text.slice(6).trim(), now)
+	} else if (lower.startsWith('in ')) {
+		const ms = parseDuration(text.slice(3).trim())
+		if (ms < MINUTE) {
+			throw new ScheduleValidationError(
+				`in ${text.slice(3).trim()} is less than a minute away; the nearest allowed is in 1m`,
+				text.slice(3).trim(),
+			)
+		}
+		spec = { kind: 'at', at: new Date(now.getTime() + ms).toISOString() }
+	} else if (lower.startsWith('at ')) {
+		spec = atSpec(text.slice(3), now, tz)
+	} else if (/^\d{4}-\d{2}-\d{2}T/i.test(text)) {
+		spec = atSpec(text, now, tz)
+	} else if (lower === '@reboot') {
+		throw new ScheduleValidationError('@reboot is not supported: a job runs on a schedule', text)
+	} else {
+		const expr = parseCronExpression(text)
+		spec = { kind: 'cron', expr: expr.source, tz }
+	}
+	assertSpecFires(spec, now)
+	return spec
+}
+
+/** The next `count` fire times after `after`. */
+export function upcomingFireTimes(spec: ScheduleSpec, after: Date, count = 3): Date[] {
+	const out: Date[] = []
+	let cursor = after
+	for (let i = 0; i < count; i++) {
+		const next = nextFireTime(spec, cursor)
+		if (!next) break
+		out.push(next)
+		cursor = next
+	}
+	return out
+}

package/src/schedules/types.ts

@@ -0,0 +1,163 @@
+/**
+ * Types of the schedule time engine and evaluator.
+ *
+ * The SDK owns WHEN something is due and nothing about how a host stores a
+ * job or runs it: the CLI keeps its job files, claims and history records to
+ * itself, so its on-disk format is not SDK API. The unions exported here
+ * (`ScheduleDecision`, `ScheduleSkipReason`, `ScheduleMissedReason`) may grow
+ * in a minor release; switch over them with a `default:` branch.
+ */
+
+/** A single instant (ISO-8601 UTC). */
+export interface ScheduleAtSpec {
+	readonly kind: 'at'
+	readonly at: string
+}
+
+/**
+ * Elapsed time from an anchor: `anchorAt + k * everyMs` for k ≥ 1. Pure UTC
+ * arithmetic, so `every 24h` drifts against the wall clock across a DST
+ * change; a cron spec is the way to say "every day at 09:00".
+ */
+export interface ScheduleEverySpec {
+	readonly kind: 'every'
+	/** At least one minute, and a whole number of minutes. */
+	readonly everyMs: number
+	readonly anchorAt: string
+}
+
+/** Five-field cron, evaluated in an IANA time zone the spec carries. */
+export interface ScheduleCronSpec {
+	readonly kind: 'cron'
+	/** Normalised five-field text; macros are expanded. */
+	readonly expr: string
+	readonly tz: string
+}
+
+export type ScheduleSpec = ScheduleAtSpec | ScheduleEverySpec | ScheduleCronSpec
+
+/** A parsed cron expression: each field as the sorted set of values it allows. */
+export interface CronExpression {
+	readonly source: string
+	readonly minutes: readonly number[]
+	readonly hours: readonly number[]
+	readonly daysOfMonth: readonly number[]
+	readonly months: readonly number[]
+	/** 0-6, Sunday = 0 (a written 7 is folded into 0). */
+	readonly daysOfWeek: readonly number[]
+	/** The day-of-month field does not start with `*`. */
+	readonly domRestricted: boolean
+	/** The day-of-week field does not start with `*`. */
+	readonly dowRestricted: boolean
+	/**
+	 * Minute and hour are single values or lists with no `*` or step. Decides
+	 * the DST rule (cronie's): a fixed-time job fires once per day across a
+	 * DST change, a wildcard job fires at every instant whose wall time
+	 * matches.
+	 */
+	readonly fixedTime: boolean
+}
+
+/** Why an occurrence did not run. May grow in a minor release. */
+export type ScheduleSkipReason =
+	| 'previous-run-active'
+	| 'previous-run-awaiting-approval'
+	| 'paused'
+	| 'awaiting-confirmation'
+	| 'beyond-catch-up-window'
+	| 'one-shot-expired'
+	| 'quota-hold'
+
+/** Why occurrences were missed. Best effort; may grow in a minor release. */
+export type ScheduleMissedReason = 'daemon-not-running' | 'machine-asleep' | 'clock-jumped-forward'
+
+/** The lifecycle a job is in, as far as the evaluator cares. */
+export type ScheduleJobLifecycle =
+	| 'pending-confirmation'
+	| 'active'
+	| 'paused'
+	| 'completed'
+	| 'expired'
+
+/** The evaluator's structural view of a job: what it needs and nothing else. */
+export interface ScheduleEvaluationJob {
+	readonly spec: ScheduleSpec
+	readonly state: ScheduleJobLifecycle
+	/** Catch-up window; default {@link SCHEDULE_CATCH_UP_WINDOW_MS}. */
+	readonly catchUp?: { readonly windowMs: number }
+	readonly createdAt: string
+	readonly updatedAt: string
+	/** Bumped on every definition change. */
+	readonly revision: number
+}
+
+/** What the host remembers between evaluations of one job. */
+export interface ScheduleEvaluationState {
+	/** Everything up to and including this instant has been decided. */
+	readonly lastEvaluatedAt?: string
+	/** The job revision `lastEvaluatedAt` was computed under. */
+	readonly jobRevision?: number
+	/** A run of this job that has not finished (or a fire queued but not started). */
+	readonly activeRun?: { readonly status: 'queued' | 'running' | 'awaiting-approval' }
+	/** Provider asked to be left alone until this instant. */
+	readonly quotaHoldUntil?: string
+}
+
+export interface ScheduleObservedGap {
+	readonly from: Date
+	readonly to: Date
+	readonly kind: 'asleep' | 'clock-forward' | 'clock-backward'
+}
+
+export interface ScheduleEvaluationInput {
+	readonly job: ScheduleEvaluationJob
+	readonly state: ScheduleEvaluationState
+	readonly now: Date
+	/** When this daemon instance started, and a gap it observed itself. */
+	readonly daemon: { readonly startedAt: Date; readonly observedGap?: ScheduleObservedGap }
+	/** How late a fire may be and still count as on time; default {@link SCHEDULE_LATE_GRACE_MS}. */
+	readonly lateGraceMs?: number
+	/** Whether an occurrence key was already started (claimed) by someone. */
+	readonly isClaimed?: (key: string) => boolean
+}
+
+export type ScheduleFireTrigger = 'scheduled' | 'late' | 'catch-up'
+
+/** What to do about one job now. May grow in a minor release. */
+export interface ScheduleDecision {
+	readonly fire?: {
+		/** Occurrence key: the scheduled instant in epoch milliseconds. */
+		readonly key: string
+		readonly scheduledFor: Date
+		readonly trigger: ScheduleFireTrigger
+	}
+	/** Occurrences that will not run, collapsed: one entry per reason. */
+	readonly skip: readonly {
+		readonly scheduledFor: Date
+		readonly reason: ScheduleSkipReason
+		readonly count: number
+	}[]
+	readonly missed?: {
+		readonly from: Date
+		readonly to: Date
+		readonly count: number
+		/** The count stopped at the cap; the real number is at least `count`. */
+		readonly capped: boolean
+		readonly reason: ScheduleMissedReason
+	}
+	readonly jobTransition?: 'completed' | 'expired'
+	readonly nextState: {
+		readonly lastEvaluatedAt: Date
+		readonly nextFireAt?: Date
+		readonly jobRevision: number
+	}
+}
+
+/** How occurrences in a window were counted. */
+export interface OccurrenceCount {
+	readonly count: number
+	/** The count stopped at the cap. */
+	readonly capped: boolean
+	readonly first?: Date
+	readonly latest?: Date
+}

package/src/schedules/tz.ts

@@ -0,0 +1,155 @@
+/**
+ * Time-zone arithmetic over `Intl` alone.
+ *
+ * The SDK carries no time-zone database of its own: the runtime's ICU data is
+ * the source, read through `Intl.DateTimeFormat#formatToParts`. Everything in
+ * this file is expressed in "wall" milliseconds — a local date and time
+ * written as if it were UTC (`Date.UTC(y, m - 1, d, h, min)`) — so local
+ * arithmetic is plain integer arithmetic and only the conversions touch Intl.
+ */
+
+import { ScheduleValidationError } from './errors.js'
+
+const MINUTE = 60_000
+const HOUR = 60 * MINUTE
+
+const formatters = new Map<string, Intl.DateTimeFormat>()
+
+function formatterFor(tz: string): Intl.DateTimeFormat {
+	let f = formatters.get(tz)
+	if (!f) {
+		f = new Intl.DateTimeFormat('en-US', {
+			timeZone: tz,
+			hourCycle: 'h23',
+			year: 'numeric',
+			month: 'numeric',
+			day: 'numeric',
+			hour: 'numeric',
+			minute: 'numeric',
+			second: 'numeric',
+		})
+		formatters.set(tz, f)
+	}
+	return f
+}
+
+/**
+ * Throw unless `tz` is an IANA zone this runtime knows. Returns the zone as
+ * the runtime spells it (`europe/istanbul` → `Europe/Istanbul`).
+ */
+export function validateTimeZone(tz: string): string {
+	if (typeof tz !== 'string' || tz.trim() === '') {
+		throw new ScheduleValidationError('a time zone is required', String(tz))
+	}
+	try {
+		return new Intl.DateTimeFormat('en-US', { timeZone: tz.trim() }).resolvedOptions().timeZone
+	} catch {
+		throw new ScheduleValidationError(`unknown time zone "${tz}"`, tz)
+	}
+}
+
+/** The zone this host is in, as the runtime reports it. */
+export function hostTimeZone(): string {
+	return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'
+}
+
+/** The wall clock of `instant` in `tz`, as wall milliseconds (seconds dropped). */
+export function wallOf(instant: number, tz: string): number {
+	const parts = formatterFor(tz).formatToParts(new Date(instant))
+	let year = 0
+	let month = 1
+	let day = 1
+	let hour = 0
+	let minute = 0
+	for (const part of parts) {
+		switch (part.type) {
+			case 'year':
+				year = Number(part.value)
+				break
+			case 'month':
+				month = Number(part.value)
+				break
+			case 'day':
+				day = Number(part.value)
+				break
+			case 'hour':
+				hour = Number(part.value) % 24
+				break
+			case 'minute':
+				minute = Number(part.value)
+				break
+		}
+	}
+	return Date.UTC(year, month - 1, day, hour, minute)
+}
+
+/** `tz`'s offset from UTC at `instant`, in milliseconds, minute precision. */
+export function offsetAt(instant: number, tz: string): number {
+	const floored = Math.floor(instant / MINUTE) * MINUTE
+	return wallOf(floored, tz) - floored
+}
+
+/**
+ * Every instant whose wall clock in `tz` reads `wall`.
+ *
+ * One instant normally, two in the hour a fall-back repeats (earliest first),
+ * none in the hour a spring-forward skips.
+ */
+export function instantsForWall(wall: number, tz: string): number[] {
+	const offsets = new Set<number>([
+		offsetAt(wall - 26 * HOUR, tz),
+		offsetAt(wall, tz),
+		offsetAt(wall + 26 * HOUR, tz),
+	])
+	const found = new Set<number>()
+	for (const offset of offsets) {
+		const candidate = wall - offset
+		if (wallOf(candidate, tz) === wall) found.add(candidate)
+	}
+	return [...found].sort((a, b) => a - b)
+}
+
+/**
+ * The first instant whose wall clock is later than `wall`, for a `wall` that
+ * falls inside a spring-forward gap: the moment the clocks jumped.
+ */
+export function firstInstantAfterGap(wall: number, tz: string): number {
+	const a = offsetAt(wall - 26 * HOUR, tz)
+	const b = offsetAt(wall + 26 * HOUR, tz)
+	let lo = Math.floor((wall - Math.max(a, b)) / MINUTE)
+	let hi = Math.ceil((wall - Math.min(a, b)) / MINUTE)
+	// Smallest minute m in [lo, hi] with wallOf(m) > wall.
+	while (lo < hi) {
+		const mid = Math.floor((lo + hi) / 2)
+		if (wallOf(mid * MINUTE, tz) > wall) hi = mid
+		else lo = mid + 1
+	}
+	return lo * MINUTE
+}
+
+/** Civil date parts of a wall value. */
+export function civil(wall: number): {
+	year: number
+	month: number
+	day: number
+	hour: number
+	minute: number
+	weekday: number
+} {
+	const d = new Date(wall)
+	return {
+		year: d.getUTCFullYear(),
+		month: d.getUTCMonth() + 1,
+		day: d.getUTCDate(),
+		hour: d.getUTCHours(),
+		minute: d.getUTCMinutes(),
+		weekday: d.getUTCDay(),
+	}
+}
+
+/** `YYYY-MM-DD HH:MM` for an instant in `tz`. */
+export function formatWall(instant: number, tz: string): string {
+	const c = civil(wallOf(instant, tz))
+	const p = (n: number) => String(n).padStart(2, '0')
+	return `${c.year}-${p(c.month)}-${p(c.day)} ${p(c.hour)}:${p(c.minute)}`
+}

package/src/skills/index.ts

@@ -1,2 +1,2 @@
-export { loadSkill, discoverSkills } from './loader.js'
+export { SKILL_FRONTMATTER_KEYS, loadSkill, discoverSkills } from './loader.js'
 export { SkillRegistry, resolveSkillChain } from './registry.js'

package/src/skills/loader.ts

@@ -13,11 +13,38 @@ import { type Logger, resolveLogger } from '../utils/logger.js'
 export const SKILL_FILENAME = 'SKILL.md'
 
 /**
- * `allowed-tools` may be a YAML list. The Agent Skills format writes it
- * space-separated, comma-separated or as a list, and all three must mean the
- * same grant; the reader joins a list into the comma form.
+ * The frontmatter keys this loader reads.
+ *
+ * Every other key is skipped whole, whatever YAML it is written in, so a
+ * skill written for another agent — `argument-hint: [file]`, a `hooks:`
+ * block, `user-invocable: false` — loads here with those fields ignored
+ * instead of being refused over syntax in a field nothing reads. The keys
+ * listed are still parsed strictly: a value this loader USES is never read
+ * wrongly.
+ */
+export const SKILL_FRONTMATTER_KEYS: readonly string[] = Object.freeze([
+	'name',
+	'description',
+	'license',
+	'compatibility',
+	'allowed-tools',
+	'invocation',
+	'disable-model-invocation',
+	'metadata',
+])
+
+const READS_SKILL_KEY = (key: string): boolean => SKILL_FRONTMATTER_KEYS.includes(key)
+
+/**
+ * How this loader reads frontmatter. `allowed-tools` may be a YAML list: the
+ * Agent Skills format writes it space-separated, comma-separated or as a
+ * list, and all three must mean the same grant; the reader joins a list into
+ * the comma form. Keys the loader does not read are skipped whole.
  */
-export const SKILL_FRONTMATTER_OPTIONS = { lists: ['allowed-tools'] } as const
+export const SKILL_FRONTMATTER_OPTIONS = {
+	lists: ['allowed-tools'],
+	readsKey: READS_SKILL_KEY,
+} as const
 
 /**
  * How this file's errors name themselves. Passed to the shared reader so a
@@ -110,6 +137,30 @@ function toSkillMetadata(parsed: ParsedFrontmatter, dirPath: string): SkillMetad
 		skillMetadata.invocation = invocation
 	}
 
+	// The other common spelling of "the model may not pick this":
+	// `disable-model-invocation: true` is `invocation: operator`. Read here,
+	// at the one parser, so a registry that re-reads the file on every load
+	// cannot lose it — a host-side override would be dropped by the first
+	// freshness reload and the model could then load an operator-only skill.
+	const disableModel = scalarAt(values, 'disable-model-invocation')
+	if (disableModel !== undefined) {
+		if (disableModel !== 'true' && disableModel !== 'false') {
+			// Refused for the reason `invocation` is: `yes` quietly reading as
+			// "not disabled" would put the skill back in front of the model.
+			throw new Error(
+				`${source}: disable-model-invocation must be true or false — got "${disableModel}"`,
+			)
+		}
+		if (disableModel === 'true') {
+			if (skillMetadata.invocation !== undefined && skillMetadata.invocation !== 'operator') {
+				throw new Error(
+					`${source}: disable-model-invocation: true contradicts invocation: ${skillMetadata.invocation}`,
+				)
+			}
+			skillMetadata.invocation = 'operator'
+		}
+	}
+
 	const extra = mappingAt(values, 'metadata')
 	if (extra && Object.keys(extra).length > 0) {
 		skillMetadata.metadata = { ...extra }

package/src/skills/registry.ts

@@ -220,6 +220,12 @@ export class SkillRegistry {
 			registeredName: string
 			description: string
 			location: string
+			/**
+			 * The skill's directory (`Skill.dirPath`); `location` is its SKILL.md.
+			 * Always set here. Declared optional so a subclass that overrides
+			 * `catalog()` without it still compiles.
+			 */
+			directory?: string
 			allowedTools?: string
 			invocation?: 'model' | 'operator' | 'both'
 		}[]
@@ -228,6 +234,7 @@ export class SkillRegistry {
 			registeredName: string
 			description: string
 			location: string
+			directory: string
 			allowedTools?: string
 			invocation?: 'model' | 'operator' | 'both'
 		}> = []
@@ -243,6 +250,7 @@ export class SkillRegistry {
 				registeredName,
 				description: skill.metadata.description,
 				location: join(skill.dirPath, SKILL_FILENAME),
+				directory: skill.dirPath,
 				...(skill.metadata.allowedTools === undefined
 					? {}
 					: { allowedTools: skill.metadata.allowedTools }),