skilld-sdk 0.1.0

package/dist/contract.mjs

@@ -0,0 +1,2440 @@
+import { z } from "zod";
+//#region src/contract/core.ts
+/**
+* The skilld public API contract, version 1.
+*
+* One descriptor per operation drives four things: the OpenAPI document, the
+* server's request and response checks, the `skilld-sdk` client, and the
+* route parity test. Every descriptor checks itself when it is defined, so a
+* contract that cannot hold never reaches a route or a client.
+*
+* The wire format is the one `/api/v1` already shipped to the skilld CLI:
+* bare JSON bodies, and `application/problem+json` errors. ADR-0006 records
+* why there is no `{ data, meta }` envelope.
+*/
+const SKILLD_V1_VERSION = "1";
+const SKILLD_V1_PATH_PREFIX = "/api/v1";
+const SKILLD_V1_ORIGIN = "https://skilld.dev";
+const SKILLD_V1_RESPONSE_HEADERS = {
+	requestId: "X-Request-Id",
+	operation: "Skilld-Operation",
+	retryAfter: "Retry-After",
+	deprecation: "Deprecation"
+};
+const SKILLD_V1_METHODS = [
+	"DELETE",
+	"GET",
+	"PATCH",
+	"POST",
+	"PUT"
+];
+const SKILLD_V1_ERROR_CODES = [
+	"INVALID_REQUEST",
+	"AUTH_REQUIRED",
+	"FORBIDDEN",
+	"NOT_FOUND",
+	"CONFLICT",
+	"RATE_LIMITED",
+	"INTERNAL_ERROR",
+	"SERVICE_UNAVAILABLE"
+];
+const SKILLD_V1_ERROR_STATUS = {
+	INVALID_REQUEST: 400,
+	AUTH_REQUIRED: 401,
+	FORBIDDEN: 403,
+	NOT_FOUND: 404,
+	CONFLICT: 409,
+	RATE_LIMITED: 429,
+	INTERNAL_ERROR: 500,
+	SERVICE_UNAVAILABLE: 503
+};
+const SKILLD_V1_ERROR_TITLES = {
+	INVALID_REQUEST: "Invalid request",
+	AUTH_REQUIRED: "Authentication required",
+	FORBIDDEN: "Forbidden",
+	NOT_FOUND: "Not found",
+	CONFLICT: "Conflict",
+	RATE_LIMITED: "Request rate limited",
+	INTERNAL_ERROR: "Internal error",
+	SERVICE_UNAVAILABLE: "Service unavailable"
+};
+/** Every operation can answer these, so no descriptor lists them. */
+const SKILLD_V1_IMPLICIT_ERRORS = ["INTERNAL_ERROR", "SERVICE_UNAVAILABLE"];
+/** A retry can succeed for these codes, and for no others. */
+const SKILLD_V1_RETRYABLE_ERRORS = /* @__PURE__ */ new Set(["RATE_LIMITED", "SERVICE_UNAVAILABLE"]);
+function pathParameterNames(path) {
+	return Array.from(path.matchAll(/\{([^{}]+)\}/g), (match) => match[1]);
+}
+const SEGMENT = String.raw`(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\{[a-z][A-Za-z0-9]*\})`;
+const PATH_TEMPLATE = new RegExp(String.raw`^/api/v1(?:/${SEGMENT})+$`);
+function objectSchemaKeys(schema) {
+	return schema instanceof z.ZodObject ? Object.keys(schema.shape) : null;
+}
+function assertRequestLocations(operation) {
+	for (const location of [
+		"params",
+		"query",
+		"body"
+	]) if (!(location in operation.request) || operation.request[location] === void 0) throw new TypeError(`${operation.id}: request.${location} must be a schema or null`);
+	for (const location of ["params", "query"]) {
+		const schema = operation.request[location];
+		if (schema !== null && objectSchemaKeys(schema) === null) throw new TypeError(`${operation.id}: request.${location} must be an object schema or null`);
+	}
+	for (const key of operation.request.query ? objectSchemaKeys(operation.request.query) ?? [] : []) if (!/^[a-z][A-Za-z0-9]*$/.test(key)) throw new TypeError(`${operation.id}: query key ${key} must be camelCase`);
+	if (operation.method === "GET" && operation.request.body !== null) throw new TypeError(`${operation.id}: a GET operation cannot take a body`);
+}
+function assertPathContract(operation) {
+	if (!PATH_TEMPLATE.test(operation.path)) throw new TypeError(`${operation.id}: path must be a safe literal /api/v1 template`);
+	const names = pathParameterNames(operation.path);
+	if (new Set(names).size !== names.length) throw new TypeError(`${operation.id}: path parameters must be unique`);
+	if (names.length === 0) {
+		if (operation.request.params !== null) throw new TypeError(`${operation.id}: params must be null when the path has no parameters`);
+		return;
+	}
+	const keys = operation.request.params ? objectSchemaKeys(operation.request.params) : null;
+	if (!keys) throw new TypeError(`${operation.id}: path parameters require an object params schema`);
+	if (names.join("\0") !== keys.join("\0")) throw new TypeError(`${operation.id}: params schema keys must match the path parameter order`);
+}
+function assertSemantics(operation) {
+	const { method, semantics, access, cache } = operation;
+	if (semantics.kind === "query" && method !== "GET") throw new TypeError(`${operation.id}: a query must be a GET`);
+	if (semantics.kind === "mutation" && method === "GET") throw new TypeError(`${operation.id}: a mutation cannot be a GET`);
+	if (semantics.kind === "mutation" && semantics.retry === "idempotent" && method !== "PUT" && method !== "DELETE") throw new TypeError(`${operation.id}: only PUT and DELETE mutations may retry`);
+	if (cache._tag === "public") {
+		if (semantics.kind !== "query" || access !== "public") throw new TypeError(`${operation.id}: only public queries may use a shared cache`);
+		if (!Number.isSafeInteger(cache.maxAgeSeconds) || cache.maxAgeSeconds < 1) throw new TypeError(`${operation.id}: cache max age must be a positive number of seconds`);
+		if (!Number.isSafeInteger(cache.staleWhileRevalidateSeconds) || cache.staleWhileRevalidateSeconds < 0) throw new TypeError(`${operation.id}: stale-while-revalidate must be a nonnegative number of seconds`);
+	}
+}
+function assertResponse(operation) {
+	const { status, body } = operation.response;
+	if (status === 204 !== (body === null)) throw new TypeError(`${operation.id}: a 204 response has no body, and every other response has one`);
+	if (status === 201 && operation.method !== "POST") throw new TypeError(`${operation.id}: only POST creates with 201`);
+}
+function assertErrors(operation) {
+	const errors = new Set(operation.errors);
+	if (errors.size !== operation.errors.length) throw new TypeError(`${operation.id}: errors must be unique`);
+	for (const code of SKILLD_V1_IMPLICIT_ERRORS) if (errors.has(code)) throw new TypeError(`${operation.id}: ${code} is implicit, do not list it`);
+	if ((operation.request.params || operation.request.query || operation.request.body) && !errors.has("INVALID_REQUEST")) throw new TypeError(`${operation.id}: an operation that takes input must declare INVALID_REQUEST`);
+	if (operation.access === "account" && !errors.has("AUTH_REQUIRED")) throw new TypeError(`${operation.id}: an account operation must declare AUTH_REQUIRED`);
+	if (operation.access === "public" && errors.has("AUTH_REQUIRED")) throw new TypeError(`${operation.id}: a public operation cannot answer AUTH_REQUIRED`);
+}
+function assertExampleLocation(operation, example, location) {
+	const schema = operation.request[location];
+	const supplied = Object.hasOwn(example.request, location);
+	if (schema === null) {
+		if (supplied) throw new TypeError(`${operation.id}: example supplies request.${location} without a schema`);
+		return;
+	}
+	const value = supplied ? example.request[location] : location === "body" ? void 0 : {};
+	const parsed = schema.safeParse(value);
+	if (!parsed.success) throw new TypeError(`${operation.id}: example request.${location} does not satisfy its schema: ${parsed.error.message}`);
+}
+function assertExamples(operation) {
+	if (operation.docs.examples.length === 0) throw new TypeError(`${operation.id}: at least one example is required`);
+	for (const example of operation.docs.examples) {
+		for (const location of [
+			"params",
+			"query",
+			"body"
+		]) assertExampleLocation(operation, example, location);
+		const body = operation.response.body;
+		if (body === null) {
+			if (example.response !== null) throw new TypeError(`${operation.id}: a 204 example response must be null`);
+			continue;
+		}
+		const parsed = body.producer.safeParse(example.response);
+		if (!parsed.success) throw new TypeError(`${operation.id}: example response does not satisfy the producer schema: ${parsed.error.message}`);
+	}
+}
+function assertOperation(operation) {
+	if (!/^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/.test(operation.id)) throw new TypeError(`${operation.id}: operation ID must be a dotted lowercase identifier`);
+	assertRequestLocations(operation);
+	assertPathContract(operation);
+	assertSemantics(operation);
+	assertResponse(operation);
+	assertErrors(operation);
+	if (!operation.docs.summary || !operation.docs.description || !operation.docs.tag) throw new TypeError(`${operation.id}: summary, description, and tag are required`);
+	if (operation.lifecycle.deprecated && Number.isNaN(Date.parse(operation.lifecycle.deprecated.at))) throw new TypeError(`${operation.id}: deprecation must declare a date`);
+	assertExamples(operation);
+}
+function defineOperation(operation) {
+	assertOperation(operation);
+	return operation;
+}
+function defineRegistry(registry) {
+	if (!/^[a-z][A-Za-z0-9]*$/.test(registry.namespace)) throw new TypeError(`${registry.namespace}: registry namespace must be camelCase`);
+	for (const key of Object.keys(registry.operations)) if (!/^[a-z][A-Za-z0-9]*$/.test(key)) throw new TypeError(`${registry.namespace}.${key}: operation keys must be camelCase`);
+	return registry;
+}
+function defineProtocol(protocol) {
+	const ids = /* @__PURE__ */ new Set();
+	const routes = /* @__PURE__ */ new Map();
+	for (const [name, registry] of Object.entries(protocol.registries)) {
+		if (name !== registry.namespace) throw new TypeError(`${name}: the registry key must equal its namespace ${registry.namespace}`);
+		for (const operation of Object.values(registry.operations)) {
+			if (ids.has(operation.id)) throw new TypeError(`Duplicate operation ID ${operation.id}`);
+			ids.add(operation.id);
+			const route = `${operation.method} ${operation.path.replace(/\{[^{}]+\}/g, "{}")}`;
+			const existing = routes.get(route);
+			if (existing) throw new TypeError(`${operation.id} and ${existing} share the route ${route}`);
+			routes.set(route, operation.id);
+		}
+	}
+	return protocol;
+}
+function listOperations(protocol) {
+	return Object.values(protocol.registries).flatMap((registry) => Object.entries(registry.operations).map(([key, operation]) => ({
+		registry,
+		key,
+		operation
+	})));
+}
+/** A response object with a strict server shape and a lenient client shape. */
+function defineResponseObject(shape) {
+	return {
+		producer: z.strictObject(shape),
+		client: z.looseObject(shape)
+	};
+}
+/**
+* One list response. Every list answers `{ items, total }`, the shape the
+* shipped `skills.search` answer already has. `total` counts the whole result,
+* not this page, so a caller pages with `offset` until it has `total` items.
+*/
+function defineListResponse(item) {
+	return {
+		producer: z.strictObject({
+			items: z.array(item.producer),
+			total: z.number().int().nonnegative()
+		}),
+		client: z.looseObject({
+			items: z.array(item.client),
+			total: z.number().int().nonnegative()
+		})
+	};
+}
+/** `limit` and `offset` for a list query. A query string carries text, so both coerce. */
+function pageQueryShape(options) {
+	return {
+		limit: z.coerce.number().int().min(1).max(options.maxLimit).default(options.defaultLimit),
+		offset: z.coerce.number().int().min(0).max(1e4).default(0)
+	};
+}
+function buildOperationPath(operation, params) {
+	if (pathParameterNames(operation.path).length === 0) return operation.path;
+	if (operation.request.params === null) throw new TypeError(`${operation.id}: operation has an invalid path contract`);
+	const parsed = operation.request.params.parse(params);
+	return operation.path.replace(/\{([^{}]+)\}/g, (_match, name) => {
+		const value = parsed[name];
+		if (typeof value !== "string" && typeof value !== "number") throw new TypeError(`${operation.id}: path parameter ${name} must be a string or number`);
+		const serialized = String(value);
+		if (!serialized || serialized === "." || serialized === "..") throw new TypeError(`${operation.id}: path parameter ${name} cannot be empty or a dot segment`);
+		return encodeURIComponent(serialized);
+	});
+}
+/**
+* RFC 9457 problem details. The skilld CLI parses exactly these six fields
+* and rejects any other, so the producer is strict and stays this shape.
+*/
+const problemSchema = defineResponseObject({
+	type: z.string().min(1),
+	title: z.string().min(1),
+	status: z.number().int().min(400).max(599),
+	detail: z.string().max(1e3).optional(),
+	instance: z.string().optional(),
+	code: z.enum(SKILLD_V1_ERROR_CODES)
+});
+function problemType(code) {
+	return `${SKILLD_V1_ORIGIN}/problems/${code.toLowerCase().replaceAll("_", "-")}`;
+}
+//#endregion
+//#region src/contract/schemas.ts
+/**
+* Field schemas shared by every registry. One field means one thing across
+* the whole contract, so a client reads `owner` or `pageUrl` the same way on
+* every operation.
+*
+* Conventions every operation follows:
+* - Field names are camelCase. Times are ISO 8601 strings. A known-absent value is `null`, never a missing key.
+* - A Skill always carries its provenance: `owner`, `repository`, and `sourceUrl`, the SKILL.md in the author's Repository (VISION principle 1).
+* - Machine-generated text is named for what it is: `generatedSummary`, never `summary`.
+* - Install counts never appear. Stars and likes are the only counts (VISION anti-scope 4).
+*/
+/** A GitHub login or organization name. */
+const ownerSchema = z.string().min(1).max(39).regex(/^[A-Z0-9](?:[A-Z0-9-]*[A-Z0-9])?$/i, "must be a GitHub login");
+const loginSchema = ownerSchema;
+/** A GitHub Repository name. */
+const repositorySchema = z.string().min(1).max(100).regex(/^[\w.-]+$/, "must be a GitHub Repository name");
+/** A Skill directory name as the registry stores it. */
+const skillNameSchema = z.string().min(1).max(100).regex(/^[\w.-]+$/, "must be a Skill name");
+/** A collection slug, as it appears in `/@login/slug`. */
+const collectionSlugSchema = z.string().min(1).max(64).regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/, "must be lowercase letters, digits, and hyphens");
+const isoDateTimeSchema = z.iso.datetime({ offset: true });
+const urlSchema = z.url();
+const countSchema = z.number().int().nonnegative();
+const skillParams = z.strictObject({
+	owner: ownerSchema,
+	repository: repositorySchema,
+	name: skillNameSchema
+});
+const repositoryParams = z.strictObject({
+	owner: ownerSchema,
+	repository: repositorySchema
+});
+/** The fields every Skill card carries, on every list. */
+const skillSummaryShape = {
+	owner: ownerSchema,
+	repository: repositorySchema,
+	name: skillNameSchema,
+	displayName: z.string(),
+	description: z.string().nullable(),
+	stars: countSchema,
+	likes: countSchema,
+	/** When the SKILL.md last changed upstream. */
+	updatedAt: isoDateTimeSchema.nullable(),
+	pageUrl: urlSchema,
+	/** The SKILL.md in the author's Repository. `null` only while the first sync is pending. */
+	sourceUrl: urlSchema.nullable(),
+	runCommand: z.string(),
+	installCommand: z.string()
+};
+const skillSummarySchema = defineResponseObject(skillSummaryShape);
+const exampleSkillSummary = {
+	owner: "vercel-labs",
+	repository: "agent-skills",
+	name: "web-design-guidelines",
+	displayName: "Web Design Guidelines",
+	description: "Review UI code for compliance with web interface guidelines.",
+	stars: 18204,
+	likes: 41,
+	updatedAt: "2026-09-28T14:02:11.000Z",
+	pageUrl: "https://skilld.dev/gh/vercel-labs/agent-skills/web-design-guidelines",
+	sourceUrl: "https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md",
+	runCommand: "npx skilld run vercel-labs/agent-skills/web-design-guidelines",
+	installCommand: "npx skilld install vercel-labs/agent-skills/web-design-guidelines"
+};
+//#endregion
+//#region src/contract/account.ts
+/**
+* Loop 2: the signed-in account, its likes, its watches, its imported GitHub
+* stars, the changes its digest reports, and its skilld tokens.
+*
+* Every operation here needs a skilld.dev sign-in or a skilld token sent as a
+* Bearer credential, and no answer is cached. Account deletion is not in the
+* API: it needs a skilld.dev sign-in in the browser.
+*/
+const accountErrors = ["AUTH_REQUIRED"];
+const accountInputErrors = ["INVALID_REQUEST", "AUTH_REQUIRED"];
+const accountSchema = defineResponseObject({
+	login: loginSchema,
+	/** The GitHub profile name. */
+	name: z.string().nullable(),
+	avatarUrl: urlSchema.nullable(),
+	/** The Author page, `/@login`. */
+	pageUrl: urlSchema,
+	/** The address skilld emails: the one you saved, else your GitHub address. */
+	email: z.string().nullable(),
+	/** True when the digest of your watched Repositories goes to `email`. */
+	digest: z.boolean(),
+	/** True when the weekly goes to `email`. A GitHub address alone is not consent: save an address, or turn on `digest`. */
+	weekly: z.boolean(),
+	/** True when anyone can read your liked Skills at `/@login/liked`. */
+	likesPublic: z.boolean(),
+	/** True when skilld may scan your public Repositories for Skills. */
+	repositoryIndexing: z.boolean(),
+	/** When your last GitHub star import finished. */
+	starsImportedAt: isoDateTimeSchema.nullable()
+});
+const exampleAccount = {
+	login: "harlan-zw",
+	name: "Harlan Wilton",
+	avatarUrl: "https://avatars.githubusercontent.com/u/5326365?v=4",
+	pageUrl: "https://skilld.dev/@harlan-zw",
+	email: "harlan@example.com",
+	digest: true,
+	weekly: true,
+	likesPublic: true,
+	repositoryIndexing: true,
+	starsImportedAt: "2026-09-21T08:14:02.000Z"
+};
+const accountUpdateBody = z.strictObject({
+	email: z.email().max(254).transform((address) => address.toLowerCase()).optional(),
+	digest: z.boolean().optional(),
+	weekly: z.boolean().optional(),
+	likesPublic: z.boolean().optional(),
+	repositoryIndexing: z.boolean().optional()
+}).refine((body) => Object.values(body).some((value) => value !== void 0), { message: "Send at least one setting to change" });
+const repositoryScanSchema = defineResponseObject({
+	/**
+	* `complete`: the scan read every Repository. `partial`: it read only some,
+	* so run it again later. A `github-*` outcome means GitHub refused or failed
+	* the search.
+	*/
+	outcome: z.enum([
+		"complete",
+		"partial",
+		"github-auth-failure",
+		"github-rate-limited",
+		"github-failure"
+	]),
+	/** Repositories that hold a SKILL.md. */
+	repositoriesFound: countSchema,
+	/** Repositories the registry indexed during this scan. */
+	repositoriesIndexed: countSchema,
+	repositoriesFailed: countSchema
+});
+const likedSkillSchema = defineResponseObject({
+	...skillSummaryShape,
+	likedAt: isoDateTimeSchema
+});
+const watchSchema = defineResponseObject({
+	owner: ownerSchema,
+	repository: repositorySchema,
+	/** The Repository page on skilld.dev. */
+	pageUrl: urlSchema,
+	/**
+	* Why the watch exists. `direct`: you watched the Repository. `like`: a like
+	* added it, and removing your last like in the Repository removes it.
+	* `star-import`: you watched it from your imported stars. `collection`: you
+	* watched a collection that names it.
+	*/
+	reason: z.enum([
+		"direct",
+		"like",
+		"star-import",
+		"collection"
+	]),
+	watchedAt: isoDateTimeSchema
+});
+const starredRepositorySchema = defineResponseObject({
+	owner: ownerSchema,
+	repository: repositorySchema,
+	/** The Repository page on skilld.dev. */
+	pageUrl: urlSchema,
+	starredAt: isoDateTimeSchema,
+	/** True when you watch the Repository. */
+	watching: z.boolean(),
+	/** Skills the registry holds for the Repository. */
+	skillCount: countSchema
+});
+const starsImportSchema = defineResponseObject({
+	page: z.number().int().min(1).max(10),
+	/** The page to import next, or `null` when the import is finished. */
+	nextPage: z.number().int().min(2).max(10).nullable(),
+	/** Starred Repositories imported so far. */
+	imported: countSchema,
+	/** Imported Repositories that hold Skills. */
+	withSkills: countSchema,
+	/** Set when the last page is imported. */
+	importedAt: isoDateTimeSchema.nullable()
+});
+const changedSkillShape = {
+	...skillSummaryShape,
+	/** The latest change in the window. */
+	changedAt: isoDateTimeSchema,
+	/** Changes in the window. */
+	changeCount: countSchema,
+	/** Commit messages from the author's Repository, newest first. The author wrote them, not skilld. */
+	commitMessages: z.array(z.string()),
+	/** The latest commit on GitHub. */
+	changeUrl: urlSchema
+};
+const changesWindowShape = {
+	since: isoDateTimeSchema,
+	/** Send this as `since` next time to read only newer changes. */
+	until: isoDateTimeSchema
+};
+const accountChangesSchema = {
+	producer: z.strictObject({
+		...changesWindowShape,
+		items: z.array(z.strictObject(changedSkillShape))
+	}),
+	client: z.looseObject({
+		...changesWindowShape,
+		items: z.array(z.looseObject(changedSkillShape))
+	})
+};
+const tokenSchema = defineResponseObject({
+	id: z.number().int().positive(),
+	label: z.string().nullable(),
+	/** `oauth`: a `skilld auth login` sign-in. `pat`: a token you created. `oidc`: a short CI token from GitHub Actions. */
+	kind: z.enum([
+		"oauth",
+		"pat",
+		"oidc"
+	]),
+	createdAt: isoDateTimeSchema,
+	lastUsedAt: isoDateTimeSchema,
+	/** When the token stops working. `null` means it has no set end. */
+	expiresAt: isoDateTimeSchema.nullable(),
+	/** True for the token that sent this request. */
+	current: z.boolean()
+});
+const issuedTokenSchema = defineResponseObject({
+	id: z.number().int().positive(),
+	label: z.string(),
+	expiresAt: isoDateTimeSchema.nullable(),
+	/** The secret. This answer is the only place it appears. */
+	token: z.string().min(1)
+});
+const tokenParams = z.strictObject({ id: z.coerce.number().int().positive() });
+const exampleWatch = {
+	owner: "vercel-labs",
+	repository: "agent-skills",
+	pageUrl: "https://skilld.dev/gh/vercel-labs/agent-skills",
+	reason: "like",
+	watchedAt: "2026-09-12T10:31:44.000Z"
+};
+const accountV1 = defineRegistry({
+	namespace: "account",
+	description: "Read and change the signed-in account, and manage the Skills of your own Repositories.",
+	operations: {
+		get: defineOperation({
+			id: "account.get",
+			method: "GET",
+			path: "/api/v1/account",
+			access: "account",
+			semantics: { kind: "query" },
+			cache: { _tag: "private" },
+			request: {
+				params: null,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 200,
+				body: accountSchema
+			},
+			errors: accountErrors,
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Get your account",
+				description: "Your login, your Author page, the address skilld emails, and your email and privacy settings.",
+				tag: "Account",
+				examples: [{
+					request: {},
+					response: exampleAccount
+				}]
+			}
+		}),
+		update: defineOperation({
+			id: "account.update",
+			method: "PATCH",
+			path: "/api/v1/account",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "never"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: null,
+				query: null,
+				body: accountUpdateBody
+			},
+			response: {
+				status: 200,
+				body: accountSchema
+			},
+			errors: accountInputErrors,
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Change your settings",
+				description: "Send only the settings to change. A setting you leave out keeps its value. The new address takes effect at once, without a confirmation email. To turn on `digest` or `weekly`, the account needs an address: send `email`, or keep the saved address or your GitHub address. You cannot remove an address; turn both emails off instead. The answer is the account after the change.",
+				tag: "Account",
+				examples: [{
+					request: { body: {
+						email: "harlan@example.com",
+						digest: true
+					} },
+					response: exampleAccount
+				}, {
+					request: { body: { likesPublic: false } },
+					response: {
+						...exampleAccount,
+						likesPublic: false
+					}
+				}]
+			}
+		}),
+		scanRepositories: defineOperation({
+			id: "account.repositories.scan",
+			method: "POST",
+			path: "/api/v1/account/repositories/scan",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "never"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: null,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 200,
+				body: repositoryScanSchema
+			},
+			errors: ["AUTH_REQUIRED", "FORBIDDEN"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Scan your Repositories for Skills",
+				description: "Searches the public Repositories of your GitHub account and its organizations for Skills, and indexes them. Sign-in runs the same scan. If `repositoryIndexing` is off, the answer is FORBIDDEN. If skilld holds no GitHub access for the account, the answer is AUTH_REQUIRED: sign in on skilld.dev again.",
+				tag: "Account",
+				examples: [{
+					request: {},
+					response: {
+						outcome: "complete",
+						repositoriesFound: 3,
+						repositoriesIndexed: 2,
+						repositoriesFailed: 0
+					}
+				}]
+			}
+		}),
+		unpublishRepository: defineOperation({
+			id: "account.repositories.unpublish",
+			method: "DELETE",
+			path: "/api/v1/account/repositories/{owner}/{repository}",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "idempotent"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: repositoryParams,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 204,
+				body: null
+			},
+			errors: [
+				"INVALID_REQUEST",
+				"AUTH_REQUIRED",
+				"FORBIDDEN"
+			],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Unpublish one of your Repositories",
+				description: "Removes every Skill of the Repository from the registry. The Owner must be your own login; any other Owner is FORBIDDEN.",
+				tag: "Account",
+				examples: [{
+					request: { params: {
+						owner: "harlan-zw",
+						repository: "skills"
+					} },
+					response: null
+				}]
+			}
+		})
+	}
+});
+const likesV1 = defineRegistry({
+	namespace: "likes",
+	description: "Like Skills. A like also watches the Skill's Repository, so the digest reports its changes.",
+	operations: {
+		list: defineOperation({
+			id: "likes.list",
+			method: "GET",
+			path: "/api/v1/account/likes",
+			access: "account",
+			semantics: { kind: "query" },
+			cache: { _tag: "private" },
+			request: {
+				params: null,
+				query: z.object(pageQueryShape({
+					defaultLimit: 20,
+					maxLimit: 50
+				})),
+				body: null
+			},
+			response: {
+				status: 200,
+				body: defineListResponse(likedSkillSchema)
+			},
+			errors: accountInputErrors,
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "List your liked Skills",
+				description: "Your liked Skills, newest like first.",
+				tag: "Likes",
+				examples: [{
+					request: { query: { limit: 1 } },
+					response: {
+						items: [{
+							...exampleSkillSummary,
+							likedAt: "2026-09-12T10:31:44.000Z"
+						}],
+						total: 14
+					}
+				}]
+			}
+		}),
+		create: defineOperation({
+			id: "likes.create",
+			method: "PUT",
+			path: "/api/v1/account/likes/{owner}/{repository}/{name}",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "idempotent"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: skillParams,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 204,
+				body: null
+			},
+			errors: [
+				"INVALID_REQUEST",
+				"AUTH_REQUIRED",
+				"NOT_FOUND",
+				"RATE_LIMITED"
+			],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Like a Skill",
+				description: "Likes the Skill and watches its Repository, so the digest reports changes to the Skill. If you already watch the Repository, that watch stays as it is. An account can add 200 likes a day.",
+				tag: "Likes",
+				examples: [{
+					request: { params: {
+						owner: "vercel-labs",
+						repository: "agent-skills",
+						name: "web-design-guidelines"
+					} },
+					response: null
+				}]
+			}
+		}),
+		delete: defineOperation({
+			id: "likes.delete",
+			method: "DELETE",
+			path: "/api/v1/account/likes/{owner}/{repository}/{name}",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "idempotent"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: skillParams,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 204,
+				body: null
+			},
+			errors: accountInputErrors,
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Remove a like",
+				description: "Removes your like. If it was your last like in the Repository, the watch that a like added goes too. A watch you added another way stays.",
+				tag: "Likes",
+				examples: [{
+					request: { params: {
+						owner: "vercel-labs",
+						repository: "agent-skills",
+						name: "web-design-guidelines"
+					} },
+					response: null
+				}]
+			}
+		})
+	}
+});
+const watchesV1 = defineRegistry({
+	namespace: "watches",
+	description: "Watch Repositories, so the digest reports changes to their Skills.",
+	operations: {
+		list: defineOperation({
+			id: "watches.list",
+			method: "GET",
+			path: "/api/v1/account/watches",
+			access: "account",
+			semantics: { kind: "query" },
+			cache: { _tag: "private" },
+			request: {
+				params: null,
+				query: z.object(pageQueryShape({
+					defaultLimit: 50,
+					maxLimit: 100
+				})),
+				body: null
+			},
+			response: {
+				status: 200,
+				body: defineListResponse(watchSchema)
+			},
+			errors: accountInputErrors,
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "List your watched Repositories",
+				description: "The Repositories your digest reports on, newest watch first, with the reason each watch exists.",
+				tag: "Watches",
+				examples: [{
+					request: { query: { limit: 1 } },
+					response: {
+						items: [exampleWatch],
+						total: 6
+					}
+				}]
+			}
+		}),
+		create: defineOperation({
+			id: "watches.create",
+			method: "PUT",
+			path: "/api/v1/account/watches/{owner}/{repository}",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "idempotent"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: repositoryParams,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 204,
+				body: null
+			},
+			errors: [
+				"INVALID_REQUEST",
+				"AUTH_REQUIRED",
+				"NOT_FOUND"
+			],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Watch a Repository",
+				description: "Watches a Repository the registry holds. A watch that a like added becomes a `direct` watch, so removing the like no longer removes it.",
+				tag: "Watches",
+				examples: [{
+					request: { params: {
+						owner: "vercel-labs",
+						repository: "agent-skills"
+					} },
+					response: null
+				}]
+			}
+		}),
+		delete: defineOperation({
+			id: "watches.delete",
+			method: "DELETE",
+			path: "/api/v1/account/watches/{owner}/{repository}",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "idempotent"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: repositoryParams,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 204,
+				body: null
+			},
+			errors: accountInputErrors,
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Stop watching a Repository",
+				description: "Removes the watch, whatever its reason. Your likes stay.",
+				tag: "Watches",
+				examples: [{
+					request: { params: {
+						owner: "vercel-labs",
+						repository: "agent-skills"
+					} },
+					response: null
+				}]
+			}
+		})
+	}
+});
+const starsV1 = defineRegistry({
+	namespace: "stars",
+	description: "Import your GitHub stars and find the starred Repositories that hold Skills.",
+	operations: {
+		list: defineOperation({
+			id: "stars.list",
+			method: "GET",
+			path: "/api/v1/account/stars",
+			access: "account",
+			semantics: { kind: "query" },
+			cache: { _tag: "private" },
+			request: {
+				params: null,
+				query: z.object(pageQueryShape({
+					defaultLimit: 50,
+					maxLimit: 100
+				})),
+				body: null
+			},
+			response: {
+				status: 200,
+				body: defineListResponse(starredRepositorySchema)
+			},
+			errors: accountInputErrors,
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "List your starred Repositories that hold Skills",
+				description: "Reads your last import, newest star first. Run `stars.import` to read GitHub again.",
+				tag: "Stars",
+				examples: [{
+					request: { query: { limit: 1 } },
+					response: {
+						items: [{
+							owner: "vercel-labs",
+							repository: "agent-skills",
+							pageUrl: "https://skilld.dev/gh/vercel-labs/agent-skills",
+							starredAt: "2026-08-30T21:05:10.000Z",
+							watching: false,
+							skillCount: 6
+						}],
+						total: 3
+					}
+				}]
+			}
+		}),
+		import: defineOperation({
+			id: "stars.import",
+			method: "POST",
+			path: "/api/v1/account/stars/import",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "never"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: null,
+				query: null,
+				body: z.strictObject({ page: z.number().int().min(1).max(10).default(1) })
+			},
+			response: {
+				status: 200,
+				body: starsImportSchema
+			},
+			errors: accountInputErrors,
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Import your GitHub stars",
+				description: "Imports one page of 100 GitHub stars and keeps the Repositories whose name mentions a Skill. Page 1 replaces the last import. Send each `nextPage` until it is `null`; the import stops after page 10. If skilld holds no GitHub access for the account, the answer is AUTH_REQUIRED: sign in on skilld.dev again.",
+				tag: "Stars",
+				examples: [{
+					request: { body: {} },
+					response: {
+						page: 1,
+						nextPage: 2,
+						imported: 4,
+						withSkills: 2,
+						importedAt: null
+					}
+				}, {
+					request: { body: { page: 2 } },
+					response: {
+						page: 2,
+						nextPage: null,
+						imported: 5,
+						withSkills: 3,
+						importedAt: "2026-10-01T07:45:00.000Z"
+					}
+				}]
+			}
+		})
+	}
+});
+const changesV1 = defineRegistry({
+	namespace: "changes",
+	description: "Read what changed in your watched Repositories: the content of your digest.",
+	operations: { list: defineOperation({
+		id: "changes.list",
+		method: "GET",
+		path: "/api/v1/account/changes",
+		access: "account",
+		semantics: { kind: "query" },
+		cache: { _tag: "private" },
+		request: {
+			params: null,
+			query: z.object({ since: isoDateTimeSchema.optional() }),
+			body: null
+		},
+		response: {
+			status: 200,
+			body: accountChangesSchema
+		},
+		errors: accountInputErrors,
+		lifecycle: { introduced: "1.0.0" },
+		docs: {
+			summary: "List changes to your watched Skills",
+			description: "The Skills that changed in your watched Repositories between `since` and now, the same selection as your digest. A watch that a like added reports only the Skills you liked. Without `since`, the window is the last 30 days. The answer covers at most the 30 Repositories with the most changes.",
+			tag: "Changes",
+			examples: [{
+				request: { query: { since: "2026-09-01T00:00:00.000Z" } },
+				response: {
+					since: "2026-09-01T00:00:00.000Z",
+					until: "2026-10-01T09:00:00.000Z",
+					items: [{
+						...exampleSkillSummary,
+						changedAt: "2026-09-28T14:02:11.000Z",
+						changeCount: 2,
+						commitMessages: ["docs: add focus ring rules", "docs: clarify form labels"],
+						changeUrl: "https://github.com/vercel-labs/agent-skills/commit/4f1c2a9e0b7d3c5a8e6f1b2d4c7a9e0f3b5d8c1a"
+					}]
+				}
+			}]
+		}
+	}) }
+});
+const tokensV1 = defineRegistry({
+	namespace: "tokens",
+	description: "Create, list, and revoke the skilld tokens that act for your account.",
+	operations: {
+		list: defineOperation({
+			id: "tokens.list",
+			method: "GET",
+			path: "/api/v1/account/tokens",
+			access: "account",
+			semantics: { kind: "query" },
+			cache: { _tag: "private" },
+			request: {
+				params: null,
+				query: z.object(pageQueryShape({
+					defaultLimit: 50,
+					maxLimit: 100
+				})),
+				body: null
+			},
+			response: {
+				status: 200,
+				body: defineListResponse(tokenSchema)
+			},
+			errors: accountInputErrors,
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "List your tokens",
+				description: "Your tokens that still work, most recently used first. A revoked or expired token is not listed. The answer never holds a secret.",
+				tag: "Tokens",
+				examples: [{
+					request: {},
+					response: {
+						items: [{
+							id: 412,
+							label: "CI deploy",
+							kind: "pat",
+							createdAt: "2026-09-02T11:20:00.000Z",
+							lastUsedAt: "2026-10-01T06:58:31.000Z",
+							expiresAt: "2026-12-01T11:20:00.000Z",
+							current: true
+						}],
+						total: 1
+					}
+				}]
+			}
+		}),
+		create: defineOperation({
+			id: "tokens.create",
+			method: "POST",
+			path: "/api/v1/account/tokens",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "never"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: null,
+				query: null,
+				body: z.strictObject({
+					label: z.string().trim().min(1).max(80),
+					/** Days until the token stops working. Leave it out for a token with no set end. */
+					ttlDays: z.number().int().min(1).max(3650).optional()
+				})
+			},
+			response: {
+				status: 201,
+				body: issuedTokenSchema
+			},
+			errors: [...accountInputErrors, "FORBIDDEN"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Create a token",
+				description: "Creates a skilld token that acts for your account. Send it as a Bearer credential. Store `token` now: no later answer shows it. A one-hour GitHub Actions token cannot create a token, so that request is FORBIDDEN.",
+				tag: "Tokens",
+				examples: [{
+					request: { body: {
+						label: "CI deploy",
+						ttlDays: 90
+					} },
+					response: {
+						id: 412,
+						label: "CI deploy",
+						expiresAt: "2026-12-31T09:00:00.000Z",
+						token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEsInRpZCI6NDEyfQ.c2lnbmF0dXJl"
+					}
+				}]
+			}
+		}),
+		revoke: defineOperation({
+			id: "tokens.revoke",
+			method: "DELETE",
+			path: "/api/v1/account/tokens/{id}",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "idempotent"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: tokenParams,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 204,
+				body: null
+			},
+			errors: [
+				"INVALID_REQUEST",
+				"AUTH_REQUIRED",
+				"NOT_FOUND"
+			],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Revoke a token",
+				description: "Revokes one of your tokens. It stops working at once, even if it sent this request. A token of another account is NOT_FOUND.",
+				tag: "Tokens",
+				examples: [{
+					request: { params: { id: 412 } },
+					response: null
+				}]
+			}
+		})
+	}
+});
+//#endregion
+//#region src/contract/collections.ts
+/**
+* Slugs that already name a static route under `/@login/`. A collection with
+* one of them would be created and then never reached, because the static
+* route wins.
+*/
+const RESERVED_COLLECTION_SLUGS = /* @__PURE__ */ new Set(["liked"]);
+const curatorParams = z.strictObject({ login: loginSchema });
+const collectionParams = z.strictObject({
+	login: loginSchema,
+	slug: collectionSlugSchema
+});
+const collectionSkillParams = z.strictObject({
+	login: loginSchema,
+	slug: collectionSlugSchema,
+	owner: ownerSchema,
+	repository: repositorySchema,
+	name: skillNameSchema
+});
+/** Why the curator picked the Skill, in their own words. */
+const reasonSchema = z.string().trim().min(1).max(2e3);
+const curatorIdentityFields = {
+	login: loginSchema,
+	/** The GitHub profile name, when the account has one. */
+	name: z.string().nullable(),
+	avatarUrl: urlSchema.nullable()
+};
+const collectionFields = {
+	slug: collectionSlugSchema,
+	title: z.string(),
+	/** The curator's introduction to the collection. */
+	description: z.string().nullable(),
+	pageUrl: urlSchema,
+	/** Installs every Skill the collection names. */
+	installCommand: z.string()
+};
+const curatorIdentitySchema = defineResponseObject(curatorIdentityFields);
+/** One Skill in a collection, with the curator's reason for it. */
+const collectionSkillSchema = defineResponseObject({
+	...skillSummaryShape,
+	reason: z.string().nullable()
+});
+const collectionSkillPage = defineListResponse(collectionSkillSchema);
+const collectionDetailSchema = {
+	producer: z.strictObject({
+		...collectionFields,
+		curator: curatorIdentitySchema.producer,
+		skills: collectionSkillPage.producer
+	}),
+	client: z.looseObject({
+		...collectionFields,
+		curator: curatorIdentitySchema.client,
+		skills: collectionSkillPage.client
+	})
+};
+const collectionSummarySchema = defineResponseObject({
+	...collectionFields,
+	/** Every Skill the collection names, also a Skill the registry cannot show now. */
+	skillCount: countSchema
+});
+const curatorFields = {
+	...curatorIdentityFields,
+	pageUrl: urlSchema
+};
+const curatorListItemSchema = defineResponseObject({
+	...curatorFields,
+	collectionCount: countSchema
+});
+const curatorDetailFields = {
+	...curatorFields,
+	/** Installs every Skill that the curator's collections name. */
+	installCommand: z.string()
+};
+const curatorDetailSchema = {
+	producer: z.strictObject({
+		...curatorDetailFields,
+		collections: z.array(collectionSummarySchema.producer)
+	}),
+	client: z.looseObject({
+		...curatorDetailFields,
+		collections: z.array(collectionSummarySchema.client)
+	})
+};
+const collectionSkillEntry = z.strictObject({
+	owner: ownerSchema,
+	repository: repositorySchema,
+	name: skillNameSchema,
+	reason: reasonSchema.nullable().optional()
+});
+const createCollectionBody = z.strictObject({
+	slug: collectionSlugSchema.refine((slug) => !RESERVED_COLLECTION_SLUGS.has(slug), "is reserved"),
+	title: z.string().trim().min(1).max(120),
+	description: z.string().trim().min(1).max(4e3).nullable().optional(),
+	skills: z.array(collectionSkillEntry).max(100).refine((skills) => new Set(skills.map((skill) => `${skill.owner}/${skill.repository}/${skill.name}`)).size === skills.length, "must name each Skill once").default([])
+});
+const exampleCurator = {
+	login: "harlan-zw",
+	name: "Harlan Wilton",
+	avatarUrl: "https://avatars.githubusercontent.com/u/5326365?v=4"
+};
+const exampleCollectionFields = {
+	slug: "design-engineering-essentials",
+	title: "Design Engineering Essentials",
+	description: "The Skills I give an agent before it touches interface code.",
+	pageUrl: "https://skilld.dev/@harlan-zw/design-engineering-essentials",
+	installCommand: "npx skilld add @harlan-zw/design-engineering-essentials"
+};
+const exampleCollectionSkill = {
+	...exampleSkillSummary,
+	reason: "Checks interface code against a published list of rules before review."
+};
+const exampleCollection = {
+	...exampleCollectionFields,
+	curator: exampleCurator,
+	skills: {
+		items: [exampleCollectionSkill],
+		total: 1
+	}
+};
+const curatorsV1 = defineRegistry({
+	namespace: "curators",
+	description: "Read the curators who assemble collections on skilld.dev, their collections, and the Skills they like.",
+	operations: {
+		list: defineOperation({
+			id: "curators.list",
+			method: "GET",
+			path: "/api/v1/curators",
+			access: "public",
+			semantics: { kind: "query" },
+			cache: {
+				_tag: "public",
+				maxAgeSeconds: 300,
+				staleWhileRevalidateSeconds: 3600
+			},
+			request: {
+				params: null,
+				query: z.object(pageQueryShape({
+					defaultLimit: 30,
+					maxLimit: 60
+				})),
+				body: null
+			},
+			response: {
+				status: 200,
+				body: defineListResponse(curatorListItemSchema)
+			},
+			errors: ["INVALID_REQUEST"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "List curators",
+				description: "The skilld.dev/community directory. It holds the first 60 curators: curators with a featured collection come first, then the rest by GitHub stars. A curator who publishes Skills but no collection yet has a `collectionCount` of 0.",
+				tag: "Curators",
+				examples: [{
+					request: { query: { limit: 1 } },
+					response: {
+						items: [{
+							...exampleCurator,
+							pageUrl: "https://skilld.dev/@harlan-zw",
+							collectionCount: 2
+						}],
+						total: 41
+					}
+				}]
+			}
+		}),
+		get: defineOperation({
+			id: "curators.get",
+			method: "GET",
+			path: "/api/v1/curators/{login}",
+			access: "public",
+			semantics: { kind: "query" },
+			cache: {
+				_tag: "public",
+				maxAgeSeconds: 60,
+				staleWhileRevalidateSeconds: 300
+			},
+			request: {
+				params: curatorParams,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 200,
+				body: curatorDetailSchema
+			},
+			errors: ["INVALID_REQUEST", "NOT_FOUND"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Get a curator",
+				description: "One curator and their collections, newest first. `installCommand` installs every Skill that the collections name. If no skilld.dev account has the login, the answer is NOT_FOUND.",
+				tag: "Curators",
+				examples: [{
+					request: { params: { login: "harlan-zw" } },
+					response: {
+						...exampleCurator,
+						pageUrl: "https://skilld.dev/@harlan-zw",
+						installCommand: "npx skilld add @harlan-zw",
+						collections: [{
+							...exampleCollectionFields,
+							skillCount: 8
+						}]
+					}
+				}]
+			}
+		}),
+		likes: defineOperation({
+			id: "curators.likes",
+			method: "GET",
+			path: "/api/v1/curators/{login}/likes",
+			access: "public",
+			semantics: { kind: "query" },
+			cache: {
+				_tag: "public",
+				maxAgeSeconds: 60,
+				staleWhileRevalidateSeconds: 300
+			},
+			request: {
+				params: curatorParams,
+				query: z.object(pageQueryShape({
+					defaultLimit: 50,
+					maxLimit: 100
+				})),
+				body: null
+			},
+			response: {
+				status: 200,
+				body: defineListResponse(defineResponseObject(skillSummaryShape))
+			},
+			errors: ["INVALID_REQUEST", "NOT_FOUND"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "List the Skills a curator likes",
+				description: "The 200 Skills the curator liked most recently, newest like first: the list at skilld.dev/@login/liked. A curator can keep the list private. If the list is private, or no account has the login, the answer is NOT_FOUND. This operation never shows a private list, not even to its owner. Use `likes.list` for your own likes.",
+				tag: "Curators",
+				examples: [{
+					request: {
+						params: { login: "harlan-zw" },
+						query: { limit: 1 }
+					},
+					response: {
+						items: [exampleSkillSummary],
+						total: 12
+					}
+				}]
+			}
+		})
+	}
+});
+const collectionsV1 = defineRegistry({
+	namespace: "collections",
+	description: "Read a collection, build your own, and watch one so the digest reports changes to its Skills.",
+	operations: {
+		get: defineOperation({
+			id: "collections.get",
+			method: "GET",
+			path: "/api/v1/collections/{login}/{slug}",
+			access: "public",
+			semantics: { kind: "query" },
+			cache: {
+				_tag: "public",
+				maxAgeSeconds: 60,
+				staleWhileRevalidateSeconds: 300
+			},
+			request: {
+				params: collectionParams,
+				query: z.object(pageQueryShape({
+					defaultLimit: 100,
+					maxLimit: 100
+				})),
+				body: null
+			},
+			response: {
+				status: 200,
+				body: collectionDetailSchema
+			},
+			errors: ["INVALID_REQUEST", "NOT_FOUND"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Get a collection",
+				description: "One collection at skilld.dev/@login/slug, with its Skills in the curator's order and the reason for each. A collection can name a whole Repository: that entry shows the Repository's most recently changed Skill. A Skill the registry cannot show now, for example because its Repository is broken, is left out of `skills`.",
+				tag: "Collections",
+				examples: [{
+					request: { params: {
+						login: "harlan-zw",
+						slug: "design-engineering-essentials"
+					} },
+					response: exampleCollection
+				}]
+			}
+		}),
+		create: defineOperation({
+			id: "collections.create",
+			method: "POST",
+			path: "/api/v1/collections",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "never"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: null,
+				query: null,
+				body: createCollectionBody
+			},
+			response: {
+				status: 201,
+				body: collectionDetailSchema
+			},
+			errors: [
+				"INVALID_REQUEST",
+				"AUTH_REQUIRED",
+				"CONFLICT"
+			],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Create a collection",
+				description: "Creates a collection at skilld.dev/@your-login/slug, with up to 100 Skills in the order you send them. Every Skill must be in the registry, or the answer is INVALID_REQUEST. If you already have a collection with the slug, the answer is CONFLICT.",
+				tag: "Collections",
+				examples: [{
+					request: { body: {
+						slug: "design-engineering-essentials",
+						title: "Design Engineering Essentials",
+						description: "The Skills I give an agent before it touches interface code.",
+						skills: [{
+							owner: "vercel-labs",
+							repository: "agent-skills",
+							name: "web-design-guidelines",
+							reason: "Checks interface code against a published list of rules before review."
+						}]
+					} },
+					response: exampleCollection
+				}]
+			}
+		}),
+		addSkill: defineOperation({
+			id: "collections.skills.add",
+			method: "PUT",
+			path: "/api/v1/collections/{login}/{slug}/skills/{owner}/{repository}/{name}",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "idempotent"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: collectionSkillParams,
+				query: null,
+				body: z.strictObject({ reason: reasonSchema.nullable().optional() }).default({})
+			},
+			response: {
+				status: 200,
+				body: collectionSkillSchema
+			},
+			errors: [
+				"INVALID_REQUEST",
+				"AUTH_REQUIRED",
+				"FORBIDDEN",
+				"NOT_FOUND"
+			],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Add a Skill to a collection",
+				description: "Adds the Skill to the end of one of your collections, and answers the collection entry. If the collection already has the Skill, its place stays the same. Send `reason` to set the reason, or `null` to clear it. If you leave out `reason`, the stored reason stays. Only the curator can change a collection: for another login the answer is FORBIDDEN.",
+				tag: "Collections",
+				examples: [{
+					request: {
+						params: {
+							login: "harlan-zw",
+							slug: "design-engineering-essentials",
+							owner: "vercel-labs",
+							repository: "agent-skills",
+							name: "web-design-guidelines"
+						},
+						body: { reason: "Checks interface code against a published list of rules before review." }
+					},
+					response: exampleCollectionSkill
+				}]
+			}
+		}),
+		removeSkill: defineOperation({
+			id: "collections.skills.remove",
+			method: "DELETE",
+			path: "/api/v1/collections/{login}/{slug}/skills/{owner}/{repository}/{name}",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "idempotent"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: collectionSkillParams,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 204,
+				body: null
+			},
+			errors: [
+				"INVALID_REQUEST",
+				"AUTH_REQUIRED",
+				"FORBIDDEN",
+				"NOT_FOUND"
+			],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Remove a Skill from a collection",
+				description: "Removes the Skill from one of your collections. If the Skill shows for a whole-Repository entry, that entry goes. If the collection does not have the Skill, nothing changes. Only the curator can change a collection: for another login the answer is FORBIDDEN.",
+				tag: "Collections",
+				examples: [{
+					request: { params: {
+						login: "harlan-zw",
+						slug: "design-engineering-essentials",
+						owner: "vercel-labs",
+						repository: "agent-skills",
+						name: "web-design-guidelines"
+					} },
+					response: null
+				}]
+			}
+		}),
+		watch: defineOperation({
+			id: "collections.watch",
+			method: "PUT",
+			path: "/api/v1/collections/{login}/{slug}/watch",
+			access: "account",
+			semantics: {
+				kind: "mutation",
+				retry: "idempotent"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: collectionParams,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 200,
+				body: defineResponseObject({ 
+				/** The Repositories of the collection, all of which you now watch. */
+watched: countSchema })
+			},
+			errors: [
+				"INVALID_REQUEST",
+				"AUTH_REQUIRED",
+				"NOT_FOUND"
+			],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Watch a collection",
+				description: "Watches every Repository the collection names, so your digest reports their changes. A Repository you already watch stays watched. A Repository added to the collection later is not watched until you send this again.",
+				tag: "Collections",
+				examples: [{
+					request: { params: {
+						login: "harlan-zw",
+						slug: "design-engineering-essentials"
+					} },
+					response: { watched: 8 }
+				}]
+			}
+		})
+	}
+});
+//#endregion
+//#region src/contract/registry.ts
+const repositoryProfileFields = {
+	owner: ownerSchema,
+	repository: repositorySchema,
+	/** The Repository description on GitHub. */
+	description: z.string().nullable(),
+	stars: countSchema,
+	/** The Repository's last push, as the registry last read it. */
+	pushedAt: isoDateTimeSchema.nullable(),
+	repositoryUrl: urlSchema,
+	pageUrl: urlSchema,
+	/** Installs every Skill in the Repository. */
+	installCommand: z.string()
+};
+const repositoryProfileSchema = {
+	producer: z.strictObject({
+		...repositoryProfileFields,
+		skills: z.array(skillSummarySchema.producer)
+	}),
+	client: z.looseObject({
+		...repositoryProfileFields,
+		skills: z.array(skillSummarySchema.client)
+	})
+};
+const repositoriesV1 = defineRegistry({
+	namespace: "repositories",
+	description: "Read one Repository and every Skill the registry holds from it.",
+	operations: { get: defineOperation({
+		id: "repositories.get",
+		method: "GET",
+		path: "/api/v1/repositories/{owner}/{repository}",
+		access: "public",
+		semantics: { kind: "query" },
+		cache: {
+			_tag: "public",
+			maxAgeSeconds: 60,
+			staleWhileRevalidateSeconds: 300
+		},
+		request: {
+			params: repositoryParams,
+			query: null,
+			body: null
+		},
+		response: {
+			status: 200,
+			body: repositoryProfileSchema
+		},
+		errors: ["INVALID_REQUEST", "NOT_FOUND"],
+		lifecycle: { introduced: "1.0.0" },
+		docs: {
+			summary: "Get a Repository",
+			description: "One Repository and every Skill the registry holds from it, most recently changed first. `installCommand` installs all of them. If the registry holds no Skill from the Repository, the answer is NOT_FOUND: send an index request to add it.",
+			tag: "Repositories",
+			examples: [{
+				request: { params: {
+					owner: "vercel-labs",
+					repository: "agent-skills"
+				} },
+				response: {
+					owner: "vercel-labs",
+					repository: "agent-skills",
+					description: "Skills for AI coding agents.",
+					stars: 18204,
+					pushedAt: "2026-09-30T09:12:44.000Z",
+					repositoryUrl: "https://github.com/vercel-labs/agent-skills",
+					pageUrl: "https://skilld.dev/gh/vercel-labs/agent-skills",
+					installCommand: "npx skilld add vercel-labs/agent-skills",
+					skills: [exampleSkillSummary]
+				}
+			}]
+		}
+	}) }
+});
+/**
+* `owner/repository`, or a URL. The server reads a URL the way the skilld.dev
+* search box does: a `tree` or `blob` link, a `.git` suffix, or a trailing
+* slash still names the Repository, and a host other than github.com is
+* INVALID_REQUEST. No `i` flag, because JSON Schema patterns cannot carry one.
+*/
+const REPOSITORY_REFERENCE = /^(?:[\w.-]+\/[\w.-]+|https?:\/\/\S+)$/;
+const indexProgressSchema = z.discriminatedUnion("stage", [
+	z.strictObject({ stage: z.literal("queued") }),
+	z.strictObject({ stage: z.literal("checking") }),
+	z.strictObject({
+		stage: z.literal("indexing"),
+		indexed: countSchema,
+		total: countSchema
+	})
+]);
+const indexProgressClientSchema = z.discriminatedUnion("stage", [
+	z.looseObject({ stage: z.literal("queued") }),
+	z.looseObject({ stage: z.literal("checking") }),
+	z.looseObject({
+		stage: z.literal("indexing"),
+		indexed: countSchema,
+		total: countSchema
+	})
+]);
+const indexTargetFields = {
+	owner: ownerSchema,
+	repository: repositorySchema
+};
+const indexQueuedFields = {
+	status: z.literal("queued"),
+	/** Poll `indexRequests.get` with this until the status changes. */
+	id: z.uuid(),
+	...indexTargetFields
+};
+const indexIndexedFields = {
+	status: z.literal("indexed"),
+	...indexTargetFields
+};
+const indexFailedFields = {
+	status: z.literal("failed"),
+	...indexTargetFields,
+	/** Why the registry could not index the Repository, in words a person can act on. */
+	reason: z.string()
+};
+const indexQueued = {
+	producer: z.strictObject({
+		...indexQueuedFields,
+		progress: indexProgressSchema
+	}),
+	client: z.looseObject({
+		...indexQueuedFields,
+		progress: indexProgressClientSchema
+	})
+};
+const indexIndexed = {
+	producer: z.strictObject({
+		...indexIndexedFields,
+		skills: z.array(skillSummarySchema.producer)
+	}),
+	client: z.looseObject({
+		...indexIndexedFields,
+		skills: z.array(skillSummarySchema.client)
+	})
+};
+const indexFailed = {
+	producer: z.strictObject(indexFailedFields),
+	client: z.looseObject(indexFailedFields)
+};
+const indexRequestCreatedSchema = {
+	producer: z.discriminatedUnion("status", [indexIndexed.producer, indexQueued.producer]),
+	client: z.discriminatedUnion("status", [indexIndexed.client, indexQueued.client])
+};
+const indexRequestSchema = {
+	producer: z.discriminatedUnion("status", [
+		indexQueued.producer,
+		indexIndexed.producer,
+		indexFailed.producer
+	]),
+	client: z.discriminatedUnion("status", [
+		indexQueued.client,
+		indexIndexed.client,
+		indexFailed.client
+	])
+};
+const exampleIndexRequestId = "0f8b5c1e-3d4a-4f6b-9a2c-7e1d5b8c9a04";
+const indexRequestsV1 = defineRegistry({
+	namespace: "indexRequests",
+	description: "Ask the registry to index a GitHub Repository, then poll until its Skills are in.",
+	operations: {
+		create: defineOperation({
+			id: "index_requests.create",
+			method: "POST",
+			path: "/api/v1/index-requests",
+			access: "public",
+			semantics: {
+				kind: "mutation",
+				retry: "never"
+			},
+			cache: { _tag: "private" },
+			request: {
+				params: null,
+				query: null,
+				body: z.strictObject({ repository: z.string().trim().min(3).max(2048).regex(REPOSITORY_REFERENCE, "must be owner/repository or a github.com URL") })
+			},
+			response: {
+				status: 201,
+				body: indexRequestCreatedSchema
+			},
+			errors: ["INVALID_REQUEST"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Index a Repository",
+				description: "If the registry already holds Skills from the Repository, the status is `indexed` and the answer lists them. If not, the status is `queued`: poll `indexRequests.get` with the `id`. A second request for a Repository that is already queued answers the same `id`.",
+				tag: "Index requests",
+				examples: [{
+					request: { body: { repository: "https://github.com/vercel-labs/agent-skills" } },
+					response: {
+						status: "queued",
+						id: exampleIndexRequestId,
+						owner: "vercel-labs",
+						repository: "agent-skills",
+						progress: { stage: "queued" }
+					}
+				}, {
+					request: { body: { repository: "vercel-labs/agent-skills" } },
+					response: {
+						status: "indexed",
+						owner: "vercel-labs",
+						repository: "agent-skills",
+						skills: [exampleSkillSummary]
+					}
+				}]
+			}
+		}),
+		get: defineOperation({
+			id: "index_requests.get",
+			method: "GET",
+			path: "/api/v1/index-requests/{id}",
+			access: "public",
+			semantics: { kind: "query" },
+			cache: { _tag: "private" },
+			request: {
+				params: z.strictObject({ id: z.uuid() }),
+				query: null,
+				body: null
+			},
+			response: {
+				status: 200,
+				body: indexRequestSchema
+			},
+			errors: ["INVALID_REQUEST", "NOT_FOUND"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Get an index request",
+				description: "The state of one index request. Poll while the status is `queued`. `indexed` lists the Skills the registry found. `failed` gives the reason.",
+				tag: "Index requests",
+				examples: [{
+					request: { params: { id: exampleIndexRequestId } },
+					response: {
+						status: "queued",
+						id: exampleIndexRequestId,
+						owner: "vercel-labs",
+						repository: "agent-skills",
+						progress: {
+							stage: "indexing",
+							indexed: 3,
+							total: 6
+						}
+					}
+				}, {
+					request: { params: { id: exampleIndexRequestId } },
+					response: {
+						status: "failed",
+						owner: "vercel-labs",
+						repository: "agent-skills",
+						reason: "No supported SKILL.md files were found."
+					}
+				}]
+			}
+		})
+	}
+});
+const ownerRepositorySchema = defineResponseObject({
+	repository: repositorySchema,
+	description: z.string().nullable(),
+	stars: countSchema,
+	/** The Skills the registry holds from this Repository. */
+	skillCount: countSchema,
+	pageUrl: urlSchema
+});
+const ownerFields = {
+	login: ownerSchema,
+	/** The GitHub profile name, when the registry has read one. */
+	name: z.string().nullable(),
+	avatarUrl: urlSchema,
+	kind: z.enum(["user", "organization"]),
+	pageUrl: urlSchema
+};
+const ownerProfileSchema = {
+	producer: z.strictObject({
+		...ownerFields,
+		repositories: z.array(ownerRepositorySchema.producer)
+	}),
+	client: z.looseObject({
+		...ownerFields,
+		repositories: z.array(ownerRepositorySchema.client)
+	})
+};
+const ownersV1 = defineRegistry({
+	namespace: "owners",
+	description: "Read one GitHub Owner and the Repositories it publishes Skills from.",
+	operations: { get: defineOperation({
+		id: "owners.get",
+		method: "GET",
+		path: "/api/v1/owners/{owner}",
+		access: "public",
+		semantics: { kind: "query" },
+		cache: {
+			_tag: "public",
+			maxAgeSeconds: 60,
+			staleWhileRevalidateSeconds: 300
+		},
+		request: {
+			params: z.strictObject({ owner: ownerSchema }),
+			query: null,
+			body: null
+		},
+		response: {
+			status: 200,
+			body: ownerProfileSchema
+		},
+		errors: ["INVALID_REQUEST", "NOT_FOUND"],
+		lifecycle: { introduced: "1.0.0" },
+		docs: {
+			summary: "Get an Owner",
+			description: "One GitHub organization or user, and each Repository it publishes Skills from, the Repository with the most Skills first. If the registry holds no Skill from the Owner, the answer is NOT_FOUND.",
+			tag: "Owners",
+			examples: [{
+				request: { params: { owner: "vercel-labs" } },
+				response: {
+					login: "vercel-labs",
+					name: "Vercel Labs",
+					avatarUrl: "https://github.com/vercel-labs.png",
+					kind: "organization",
+					pageUrl: "https://skilld.dev/gh/vercel-labs",
+					repositories: [{
+						repository: "agent-skills",
+						description: "Skills for AI coding agents.",
+						stars: 18204,
+						skillCount: 6,
+						pageUrl: "https://skilld.dev/gh/vercel-labs/agent-skills"
+					}]
+				}
+			}]
+		}
+	}) }
+});
+const trackSlugSchema = z.string().min(1).max(64).regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/, "must be lowercase letters, digits, and hyphens");
+const trackFields = {
+	slug: trackSlugSchema,
+	label: z.string(),
+	/** The second-person line a person wrote for the track. */
+	line: z.string(),
+	pageUrl: urlSchema
+};
+const trackSummarySchema = defineResponseObject({
+	...trackFields,
+	skillCount: countSchema
+});
+const trackDetailSchema = {
+	producer: z.strictObject({
+		...trackFields,
+		items: z.array(skillSummarySchema.producer),
+		total: countSchema
+	}),
+	client: z.looseObject({
+		...trackFields,
+		items: z.array(skillSummarySchema.client),
+		total: countSchema
+	})
+};
+const exampleTrack = {
+	slug: "design",
+	label: "Design and interface work",
+	line: "You care how the interface looks, moves, and reads.",
+	pageUrl: "https://skilld.dev/skills/design"
+};
+const tracksV1 = defineRegistry({
+	namespace: "tracks",
+	description: "Tracks: Skills for one kind of work. A person writes each label and line and pins the Skills that lead it.",
+	operations: {
+		list: defineOperation({
+			id: "tracks.list",
+			method: "GET",
+			path: "/api/v1/tracks",
+			access: "public",
+			semantics: { kind: "query" },
+			cache: {
+				_tag: "public",
+				maxAgeSeconds: 300,
+				staleWhileRevalidateSeconds: 3600
+			},
+			request: {
+				params: null,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 200,
+				body: defineListResponse(trackSummarySchema)
+			},
+			errors: [],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "List tracks",
+				description: "Every track that holds at least one Skill, the track with the most Skills first. The list is short, so it has no pages.",
+				tag: "Tracks",
+				examples: [{
+					request: {},
+					response: {
+						items: [{
+							...exampleTrack,
+							skillCount: 41
+						}],
+						total: 14
+					}
+				}]
+			}
+		}),
+		get: defineOperation({
+			id: "tracks.get",
+			method: "GET",
+			path: "/api/v1/tracks/{slug}",
+			access: "public",
+			semantics: { kind: "query" },
+			cache: {
+				_tag: "public",
+				maxAgeSeconds: 300,
+				staleWhileRevalidateSeconds: 3600
+			},
+			request: {
+				params: z.strictObject({ slug: trackSlugSchema }),
+				query: z.object(pageQueryShape({
+					defaultLimit: 20,
+					maxLimit: 100
+				})),
+				body: null
+			},
+			response: {
+				status: 200,
+				body: trackDetailSchema
+			},
+			errors: ["INVALID_REQUEST", "NOT_FOUND"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Get a track",
+				description: "One track and its Skills, in the order its page shows them: the pinned Skills first, then the rest by stars. `total` counts every Skill in the track.",
+				tag: "Tracks",
+				examples: [{
+					request: {
+						params: { slug: "design" },
+						query: { limit: 1 }
+					},
+					response: {
+						...exampleTrack,
+						items: [exampleSkillSummary],
+						total: 41
+					}
+				}]
+			}
+		})
+	}
+});
+const trendingPostSchema = defineResponseObject({
+	url: urlSchema,
+	platform: z.enum(["x", "bsky"]),
+	authorHandle: z.string(),
+	/** The display name the network sent with the post, if any. */
+	authorName: z.string().nullable(),
+	text: z.string(),
+	postedAt: isoDateTimeSchema
+});
+const socialFields = {
+	/** Separate accounts that posted about the Skill in the window. */
+	authorCount: countSchema,
+	mentionCount: countSchema
+};
+const starSurgeFields = {
+	/** Stars the Repository gained on the surge day. */
+	starGain: countSchema,
+	/** UTC midnight of the surge day. */
+	surgedOn: isoDateTimeSchema
+};
+/**
+* Why a Skill is on the board. ADR-0004 makes each row state its own reason,
+* and a row a post put there ships that post.
+*
+* - `social`: devs posted about the Skill on X or Bluesky. `post` is one of those posts.
+* - `star-surge`: the Repository gained stars fast, and it holds only this Skill.
+* - `social-and-star-surge`: both of the above.
+* - `star-count`: the socials were quiet, so the board filled up with a well-starred Skill. Nobody posted about it.
+*/
+const trendingSignalSchema = {
+	producer: z.discriminatedUnion("kind", [
+		z.strictObject({
+			kind: z.literal("social"),
+			...socialFields,
+			post: trendingPostSchema.producer
+		}),
+		z.strictObject({
+			kind: z.literal("star-surge"),
+			...starSurgeFields
+		}),
+		z.strictObject({
+			kind: z.literal("social-and-star-surge"),
+			...socialFields,
+			post: trendingPostSchema.producer,
+			...starSurgeFields
+		}),
+		z.strictObject({ kind: z.literal("star-count") })
+	]),
+	client: z.discriminatedUnion("kind", [
+		z.looseObject({
+			kind: z.literal("social"),
+			...socialFields,
+			post: trendingPostSchema.client
+		}),
+		z.looseObject({
+			kind: z.literal("star-surge"),
+			...starSurgeFields
+		}),
+		z.looseObject({
+			kind: z.literal("social-and-star-surge"),
+			...socialFields,
+			post: trendingPostSchema.client,
+			...starSurgeFields
+		}),
+		z.looseObject({ kind: z.literal("star-count") })
+	])
+};
+const trendingSkillSchema = {
+	producer: z.strictObject({
+		...skillSummaryShape,
+		signal: trendingSignalSchema.producer
+	}),
+	client: z.looseObject({
+		...skillSummaryShape,
+		signal: trendingSignalSchema.client
+	})
+};
+/** The board's two windows, in the hours the ranking reads. */
+const TRENDING_WINDOW_HOURS = {
+	week: 168,
+	month: 720
+};
+const trendingV1 = defineRegistry({
+	namespace: "trending",
+	description: "Skills devs talk about on X and Bluesky, each with the reason it is on the board (ADR-0004). Never ranked by installs or likes.",
+	operations: { list: defineOperation({
+		id: "trending.list",
+		method: "GET",
+		path: "/api/v1/trending",
+		access: "public",
+		semantics: { kind: "query" },
+		cache: {
+			_tag: "public",
+			maxAgeSeconds: 300,
+			staleWhileRevalidateSeconds: 600
+		},
+		request: {
+			params: null,
+			query: z.object({
+				window: z.enum(["week", "month"]).default("week"),
+				limit: z.coerce.number().int().min(1).max(30).default(30)
+			}),
+			body: null
+		},
+		response: {
+			status: 200,
+			body: defineListResponse(trendingSkillSchema)
+		},
+		errors: ["INVALID_REQUEST"],
+		lifecycle: { introduced: "1.0.0" },
+		docs: {
+			summary: "List trending Skills",
+			description: "The trending board at skilld.dev/skills/trending, in rank order. Rows with a `social` or `star-surge` reason always rank above `star-count` rows. `total` counts the whole board, at most 30 rows.",
+			tag: "Trending",
+			examples: [{
+				request: { query: {
+					window: "week",
+					limit: 1
+				} },
+				response: {
+					items: [{
+						...exampleSkillSummary,
+						signal: {
+							kind: "social",
+							authorCount: 3,
+							mentionCount: 4,
+							post: {
+								url: "https://x.com/ada_ships/status/1972000000000000000",
+								platform: "x",
+								authorHandle: "ada_ships",
+								authorName: "Ada",
+								text: "web-design-guidelines catches the UI mistakes I used to catch in review.",
+								postedAt: "2026-09-29T16:40:00.000Z"
+							}
+						}
+					}],
+					total: 30
+				}
+			}]
+		}
+	}) }
+});
+//#endregion
+//#region src/contract/skills.ts
+/**
+* A Skill name as the Agent Skills specification allows it. Search answers
+* only names that pass, because the skilld CLI rejects any other.
+*/
+const specSkillNameSchema = z.string().max(64).regex(/^[a-z0-9](?:[a-z0-9]|-(?!-)){0,62}[a-z0-9]$|^[a-z0-9]$/);
+const isSpecSkillName = (value) => specSkillNameSchema.safeParse(value).success;
+const searchSource = z.strictObject({
+	provider: z.literal("github"),
+	owner: z.string().min(1).max(39),
+	repository: z.string().min(1).max(100),
+	selector: z.strictObject({
+		type: z.literal("named-skill"),
+		name: specSkillNameSchema
+	})
+});
+/**
+* Frozen. skilld 3.2.0 parses this answer with `deny_unknown_fields`, so a new
+* field here fails every released `skilld search`. Add new fields to
+* `skills.get` instead.
+*/
+const searchItemShape = {
+	name: specSkillNameSchema,
+	description: z.string().max(500).nullable(),
+	source: searchSource,
+	stargazerCount: countSchema
+};
+const skillSearchResponse = {
+	producer: z.strictObject({
+		items: z.array(z.strictObject(searchItemShape)).max(50),
+		total: countSchema
+	}),
+	client: z.looseObject({
+		items: z.array(z.looseObject(searchItemShape)).max(50),
+		total: countSchema
+	})
+};
+const skillDetailSchema = defineResponseObject({
+	...skillSummaryShape,
+	/** The GitHub profile name of the Owner, when the registry has synced it. */
+	authorName: z.string().nullable(),
+	license: z.string().nullable(),
+	repositoryUrl: urlSchema,
+	/** The SKILL.md path inside the Repository. */
+	skillPath: z.string().nullable(),
+	/** The commit the registry last read. */
+	sourceCommit: z.string().nullable(),
+	/** True when the SKILL.md is gone upstream. The registry keeps the last copy it read. */
+	sourceGone: z.boolean(),
+	/** The Repository's last push. `updatedAt` is the SKILL.md's own last change. */
+	pushedAt: isoDateTimeSchema.nullable(),
+	tags: z.array(z.string()),
+	/** The `allowed-tools` the SKILL.md frontmatter asks for. */
+	allowedTools: z.array(z.string()),
+	/** Files beside the SKILL.md. `run --file` reads one. */
+	files: z.array(z.strictObject({
+		path: z.string(),
+		size: countSchema
+	})),
+	/** Machine-generated from the SKILL.md. Never written by the author. */
+	generatedSummary: z.string().nullable(),
+	/** The SKILL.md text the registry last read, frontmatter included. */
+	markdown: z.string().nullable()
+});
+/**
+* The skilld.dev/skills listing. Stars order it by default. Likes order it
+* only when the caller asks (ADR-0003), and install counts never do.
+*/
+const skillBrowseQuery = z.object({
+	q: z.string().trim().min(1).max(200).optional(),
+	owner: ownerSchema.optional(),
+	tag: z.string().trim().toLowerCase().min(1).max(64).regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/, "must be a tag slug").optional(),
+	sort: z.enum([
+		"stars",
+		"likes",
+		"updated"
+	]).default("stars"),
+	...pageQueryShape({
+		defaultLimit: 20,
+		maxLimit: 100
+	})
+});
+const skillsV1 = defineRegistry({
+	namespace: "skills",
+	description: "Search the registry and read one Skill with its provenance.",
+	operations: {
+		search: defineOperation({
+			id: "skills.search",
+			method: "GET",
+			path: "/api/v1/skills",
+			access: "public",
+			semantics: { kind: "query" },
+			cache: {
+				_tag: "public",
+				maxAgeSeconds: 60,
+				staleWhileRevalidateSeconds: 300
+			},
+			request: {
+				params: null,
+				query: z.strictObject({
+					q: z.string().trim().min(1).max(200),
+					limit: z.coerce.number().int().min(1).max(50).default(20)
+				}),
+				body: null
+			},
+			response: {
+				status: 200,
+				body: skillSearchResponse
+			},
+			errors: ["INVALID_REQUEST"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Search Skills",
+				description: "Semantic search over admitted Skills. The answer shape is frozen for skilld 3.2.0, so use `skills.get` for anything beyond the source and the star count.",
+				tag: "Skills",
+				examples: [{
+					request: { query: {
+						q: "tailwind",
+						limit: 1
+					} },
+					response: {
+						items: [{
+							name: "tailwind-v4",
+							description: "Tailwind CSS v4 patterns and migration notes.",
+							source: {
+								provider: "github",
+								owner: "nuxt",
+								repository: "ui",
+								selector: {
+									type: "named-skill",
+									name: "tailwind-v4"
+								}
+							},
+							stargazerCount: 5421
+						}],
+						total: 12
+					}
+				}]
+			}
+		}),
+		get: defineOperation({
+			id: "skills.get",
+			method: "GET",
+			path: "/api/v1/skills/{owner}/{repository}/{name}",
+			access: "public",
+			semantics: { kind: "query" },
+			cache: {
+				_tag: "public",
+				maxAgeSeconds: 60,
+				staleWhileRevalidateSeconds: 300
+			},
+			request: {
+				params: skillParams,
+				query: null,
+				body: null
+			},
+			response: {
+				status: 200,
+				body: skillDetailSchema
+			},
+			errors: ["INVALID_REQUEST", "NOT_FOUND"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Get a Skill",
+				description: "One Skill with its provenance: the Owner, the exact SKILL.md, the commit the registry read, and the run and install commands.",
+				tag: "Skills",
+				examples: [{
+					request: { params: {
+						owner: "vercel-labs",
+						repository: "agent-skills",
+						name: "web-design-guidelines"
+					} },
+					response: {
+						...exampleSkillSummary,
+						authorName: "Vercel Labs",
+						license: "MIT",
+						repositoryUrl: "https://github.com/vercel-labs/agent-skills",
+						skillPath: "skills/web-design-guidelines/SKILL.md",
+						sourceCommit: "4f1c2a9e0b7d3c5a8e6f1b2d4c7a9e0f3b5d8c1a",
+						sourceGone: false,
+						pushedAt: "2026-09-30T09:12:44.000Z",
+						tags: ["design", "accessibility"],
+						allowedTools: [],
+						files: [{
+							path: "references/checklist.md",
+							size: 4210
+						}],
+						generatedSummary: "Checks interface code against a published list of web design rules.",
+						markdown: "---\nname: web-design-guidelines\ndescription: Review UI code for compliance with web interface guidelines.\n---\n\n# Web Design Guidelines\n"
+					}
+				}]
+			}
+		}),
+		browse: defineOperation({
+			id: "skills.browse",
+			method: "GET",
+			path: "/api/v1/browse",
+			access: "public",
+			semantics: { kind: "query" },
+			cache: {
+				_tag: "public",
+				maxAgeSeconds: 60,
+				staleWhileRevalidateSeconds: 300
+			},
+			request: {
+				params: null,
+				query: skillBrowseQuery,
+				body: null
+			},
+			response: {
+				status: 200,
+				body: defineListResponse(skillSummarySchema)
+			},
+			errors: ["INVALID_REQUEST"],
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Browse Skills",
+				description: "The listing behind skilld.dev/skills, filtered by `owner` and `tag`. `sort` orders it by stars, likes, or the last SKILL.md change. With `q`, Skills rank by relevance to the query and `sort` does not apply. Use `tracks.get` for the Skills of one track.",
+				tag: "Skills",
+				examples: [{
+					request: { query: {
+						owner: "vercel-labs",
+						sort: "stars",
+						limit: 1
+					} },
+					response: {
+						items: [exampleSkillSummary],
+						total: 6
+					}
+				}]
+			}
+		})
+	}
+});
+//#endregion
+//#region src/contract/index.ts
+const skilldV1Protocol = defineProtocol({
+	version: "1",
+	registries: {
+		skills: skillsV1,
+		repositories: repositoriesV1,
+		indexRequests: indexRequestsV1,
+		owners: ownersV1,
+		tracks: tracksV1,
+		trending: trendingV1,
+		curators: curatorsV1,
+		collections: collectionsV1,
+		account: accountV1,
+		likes: likesV1,
+		watches: watchesV1,
+		stars: starsV1,
+		changes: changesV1,
+		tokens: tokensV1
+	}
+});
+//#endregion
+export { RESERVED_COLLECTION_SLUGS, SKILLD_V1_ERROR_CODES, SKILLD_V1_ERROR_STATUS, SKILLD_V1_ERROR_TITLES, SKILLD_V1_IMPLICIT_ERRORS, SKILLD_V1_METHODS, SKILLD_V1_ORIGIN, SKILLD_V1_PATH_PREFIX, SKILLD_V1_RESPONSE_HEADERS, SKILLD_V1_RETRYABLE_ERRORS, SKILLD_V1_VERSION, TRENDING_WINDOW_HOURS, accountChangesSchema, accountSchema, accountV1, buildOperationPath, changesV1, collectionDetailSchema, collectionSkillSchema, collectionSlugSchema, collectionsV1, countSchema, createCollectionBody, curatorDetailSchema, curatorListItemSchema, curatorsV1, defineListResponse, defineOperation, defineProtocol, defineRegistry, defineResponseObject, exampleSkillSummary, indexRequestCreatedSchema, indexRequestSchema, indexRequestsV1, isSpecSkillName, isoDateTimeSchema, issuedTokenSchema, likedSkillSchema, likesV1, listOperations, loginSchema, ownerProfileSchema, ownerSchema, ownersV1, pageQueryShape, problemSchema, problemType, repositoriesV1, repositoryParams, repositoryProfileSchema, repositoryScanSchema, repositorySchema, skillBrowseQuery, skillDetailSchema, skillNameSchema, skillParams, skillSearchResponse, skillSummarySchema, skillSummaryShape, skilldV1Protocol, skillsV1, specSkillNameSchema, starredRepositorySchema, starsImportSchema, starsV1, tokenSchema, tokensV1, trackDetailSchema, trackSlugSchema, trackSummarySchema, tracksV1, trendingSignalSchema, trendingSkillSchema, trendingV1, urlSchema, watchSchema, watchesV1 };