@nseng-ai/areg 0.1.1

package/src/operations/doctor-skills.ts

@@ -0,0 +1,471 @@
+import { failure, negative, ok, type ClinkrExit } from "@nseng-ai/clinkr";
+import { commandBackedSkillSurface } from "@nseng-ai/command-backed-skill-registry";
+import { optionalEntries, optionalEntry } from "@nseng-ai/foundation/primitives";
+import { z } from "zod";
+
+import type { AregCliContext } from "../context.ts";
+import type {
+	AregCheckSkillInspection,
+	AregPathState,
+	AregPiSkillInventoryInspection,
+	AregProjectBaseInspection,
+	AregReplacementInspection,
+	AregSkillKindSkillInspection,
+	AregSkillNameInventory,
+	AregTextFileState,
+} from "../gateways.ts";
+import { uniqueSortedStrings } from "../sort.ts";
+import { renderDoctorSkills } from "./doctor-skills-report.ts";
+import {
+	DOCTOR_SKILL_SEVERITY_RANK,
+	doctorSkillFindingSeverities,
+	type DoctorSkillFindingSeverity,
+} from "./doctor-skills-severity.ts";
+import { parsePiSettings } from "./pi-settings.ts";
+import { collectCheckSkillInspections, collectSkillKindInspections } from "./project-inspection.ts";
+import { buildSkillKindRecords, type SkillKindRecord } from "./skill-kind-inference.ts";
+import { isAgentsSkillMirror, isClaudeSkillMirror } from "./skill-mirror-conventions.ts";
+
+const doctorStatusValues = ["ok", "warning", "error"] as const;
+
+export type { DoctorSkillFindingSeverity } from "./doctor-skills-severity.ts";
+export type DoctorSkillsStatus = (typeof doctorStatusValues)[number];
+
+export interface DoctorSkillFinding {
+	code: string;
+	severity: DoctorSkillFindingSeverity;
+	message: string;
+	remediation: string;
+	skill?: string;
+	path?: string;
+	surface?: string;
+	evidence?: Record<string, string | boolean | number | string[]>;
+}
+
+export interface DoctorSkillsResult {
+	projectDir: string;
+	summary: {
+		status: DoctorSkillsStatus;
+		findingCounts: Record<DoctorSkillFindingSeverity, number>;
+	};
+	findings: readonly DoctorSkillFinding[];
+}
+
+export interface DoctorSkillsInspection {
+	projectDir: string;
+	base: AregProjectBaseInspection;
+	skillInventory: AregSkillNameInventory;
+	piSkillInventory: AregPiSkillInventoryInspection;
+	replacement: AregReplacementInspection;
+	piDir: AregPathState;
+	piSettings: AregTextFileState;
+	checkSkills: readonly AregCheckSkillInspection[];
+	skillKindSkills: readonly AregSkillKindSkillInspection[];
+}
+
+const doctorSkillFindingSchema: z.ZodType<DoctorSkillFinding> = z
+	.object({
+		code: z.string(),
+		severity: z.enum(doctorSkillFindingSeverities),
+		message: z.string(),
+		remediation: z.string(),
+		skill: z.string().optional(),
+		path: z.string().optional(),
+		surface: z.string().optional(),
+		evidence: z
+			.record(z.string(), z.union([z.string(), z.boolean(), z.number(), z.array(z.string())]))
+			.optional(),
+	})
+	.transform(
+		(finding): DoctorSkillFinding => ({
+			code: finding.code,
+			severity: finding.severity,
+			message: finding.message,
+			remediation: finding.remediation,
+			...optionalEntries({
+				skill: finding.skill,
+				path: finding.path,
+				surface: finding.surface,
+				evidence: finding.evidence,
+			}),
+		}),
+	);
+
+export const doctorSkillsRequestSchema = z.object({
+	path: z
+		.string()
+		.default(".")
+		.describe("Project directory or subdirectory to inspect (default: current directory)."),
+});
+
+export const doctorSkillsResultSchema = z.object({
+	projectDir: z.string(),
+	summary: z.object({
+		status: z.enum(doctorStatusValues),
+		findingCounts: z.object({
+			error: z.number(),
+			warning: z.number(),
+			info: z.number(),
+		}),
+	}),
+	findings: z.array(doctorSkillFindingSchema),
+});
+
+export type DoctorSkillsRequest = z.infer<typeof doctorSkillsRequestSchema>;
+
+export async function runDoctorSkills(
+	ctx: AregCliContext,
+	request: DoctorSkillsRequest,
+): Promise<ClinkrExit<DoctorSkillsResult>> {
+	const inspection = await inspectDoctorSkillsProject(ctx, request.path);
+	if (inspection.type === "error") return failure("project-inspection-failed", inspection.message);
+	const result = buildDoctorSkillsResult(inspection.value);
+	if (result.findings.length === 0) return ok(result);
+	return negative("Skill registry drift found.", {
+		data: result,
+		human: renderDoctorSkills(result),
+	});
+}
+
+export function buildDoctorSkillsResult(inspection: DoctorSkillsInspection): DoctorSkillsResult {
+	const findings = buildDoctorSkillFindings(inspection);
+	const findingCounts = countFindings(findings);
+	return {
+		projectDir: inspection.projectDir,
+		summary: {
+			status: statusForCounts(findingCounts),
+			findingCounts,
+		},
+		findings,
+	};
+}
+
+export function buildDoctorSkillFindings(
+	inspection: DoctorSkillsInspection,
+): readonly DoctorSkillFinding[] {
+	const piSettings = parsePiSettings(inspection.piDir, inspection.piSettings);
+	if (!piSettings.ok) {
+		return [
+			{
+				code: "pi-settings-unreadable",
+				severity: "error",
+				message: piSettings.error.message,
+				remediation:
+					"Fix .pi/settings.json so skill inventory and replacement diagnostics can run.",
+				path: ".pi/settings.json",
+			},
+		];
+	}
+	const skillKindRecords = buildSkillKindRecords({
+		projectDir: inspection.projectDir,
+		projectPathState: inspection.base.projectPathState,
+		piDir: inspection.piDir,
+		piSettings: inspection.piSettings,
+		replacement: inspection.replacement,
+		skills: inspection.skillKindSkills,
+	});
+	const records = skillKindRecords.ok ? skillKindRecords.value : [];
+	const findings: DoctorSkillFinding[] = [];
+	findings.push(...filesystemFindings(inspection));
+	findings.push(...piInventoryFindings(inspection));
+	findings.push(...replacementFindings(records, piSettings.value.exclusions));
+	if (!skillKindRecords.ok) {
+		findings.push({
+			code: "skill-kind-inspection-invalid",
+			severity: "error",
+			message: skillKindRecords.error.message,
+			remediation:
+				"Fix the managed skill metadata so command-backed replacement diagnostics can inspect it.",
+		});
+	}
+	return sortFindings(findings);
+}
+
+async function inspectDoctorSkillsProject(
+	ctx: AregCliContext,
+	requestPath: string,
+): Promise<{ type: "ok"; value: DoctorSkillsInspection } | { type: "error"; message: string }> {
+	const base = await ctx.project.inspectProjectBase({
+		cwd: ctx.cwd,
+		projectPath: requestPath,
+		env: ctx.env,
+	});
+	if (base.projectPathState.type === "missing")
+		return { type: "error", message: `Target ${base.projectDir} does not exist.` };
+	if (base.projectPathState.type !== "directory")
+		return { type: "error", message: `${base.projectDir} is not a directory.` };
+	const repoRoot = await ctx.git.optionalRepoRoot({ cwd: base.projectDir });
+	if (repoRoot.type === "error") return { type: "error", message: repoRoot.error.message };
+	if (repoRoot.type === "missing")
+		return { type: "error", message: `No Git root found containing ${base.projectDir}.` };
+	const projectDir = repoRoot.value;
+	const rootBase =
+		projectDir === base.projectDir
+			? base
+			: await ctx.project.inspectProjectBase({ cwd: projectDir, projectPath: ".", env: ctx.env });
+	const piArtifacts = await ctx.project.inspectPiArtifacts({ projectDir, env: ctx.env });
+	const skillInventory = await ctx.project.inspectSkillNameInventory({ projectDir, env: ctx.env });
+	const piSkillInventory = await ctx.project.inspectPiSkillInventory({ projectDir, env: ctx.env });
+	const skillNames = allKnownSkillNames(skillInventory, { includeSkillKindNames: true });
+	const checkSkills = await collectCheckSkillInspections(ctx, projectDir, skillNames);
+	const skillKindSkills = await collectSkillKindInspections(ctx, projectDir, skillNames);
+	return {
+		type: "ok",
+		value: {
+			projectDir,
+			base: rootBase,
+			skillInventory,
+			piSkillInventory,
+			replacement: piArtifacts.replacement,
+			piDir: piArtifacts.piDir,
+			piSettings: piArtifacts.piSettings,
+			checkSkills,
+			skillKindSkills,
+		},
+	};
+}
+
+function filesystemFindings(inspection: DoctorSkillsInspection): readonly DoctorSkillFinding[] {
+	const findings: DoctorSkillFinding[] = [];
+	const managed = new Set(inspection.skillInventory.skillKindNames);
+	const skillNames = allKnownSkillNames(inspection.skillInventory);
+	const checkSkillsByName = new Map(inspection.checkSkills.map((skill) => [skill.name, skill]));
+	for (const skillName of skillNames) {
+		const roots = rootsForSkill(inspection.skillInventory, skillName);
+		const independentRoots = independentRootsForSkill(
+			skillName,
+			roots,
+			checkSkillsByName.get(skillName),
+		);
+		if (independentRoots.length > 1) {
+			findings.push({
+				code: "skill-root-shadowed",
+				severity: "warning",
+				skill: skillName,
+				message: `${skillName} appears in multiple canonical skill roots: ${independentRoots.join(", ")}.`,
+				remediation:
+					"Keep one canonical skill root; use areg-managed symlink mirrors for agent-specific skill roots.",
+				evidence: { roots, independentRoots: [...independentRoots] },
+			});
+		}
+		if (!managed.has(skillName)) {
+			findings.push({
+				code: "skill-root-unmanaged",
+				severity: "warning",
+				skill: skillName,
+				message: `${skillName} exists on disk but is absent from areg's managed skill-kind inventory.`,
+				remediation:
+					"Run areg skill list/show to confirm the root is intentionally unmanaged, then move or reconcile the skill root.",
+				evidence: { roots },
+			});
+		}
+	}
+	for (const skill of inspection.skillKindSkills) {
+		if (skill.skillDir.type !== "symlink") continue;
+		findings.push({
+			code: "skill-root-symlink-refused",
+			severity: "error",
+			skill: skill.name,
+			path: skill.baseRelativePath,
+			message: `${skill.baseRelativePath} is a symlink; diagnostics refuse to treat it as a canonical skill root.`,
+			remediation: "Replace the symlink with a real skill directory or remove the shadowing root.",
+			evidence: { target: skill.skillDir.target },
+		});
+	}
+	for (const skill of inspection.checkSkills) {
+		if (skill.skillsPath.type !== "missing" && skill.localSkillMd.type !== "file") {
+			findings.push(missingSkillMdFinding(skill.name, `skills/${skill.name}/SKILL.md`));
+		}
+		if (skill.agentsPath.type !== "missing" && skill.remoteSkillMd.type !== "file") {
+			findings.push(missingSkillMdFinding(skill.name, `.agents/skills/${skill.name}/SKILL.md`));
+		}
+	}
+	return findings;
+}
+
+function piInventoryFindings(inspection: DoctorSkillsInspection): readonly DoctorSkillFinding[] {
+	const findings: DoctorSkillFinding[] = [];
+	const expected = new Set(inspection.skillInventory.skillKindNames);
+	const exposed = new Set(inspection.piSkillInventory.skillNames);
+	for (const skill of [...expected].sort()) {
+		if (exposed.has(skill)) continue;
+		findings.push({
+			code: "pi-inventory-missing-skill",
+			severity: "warning",
+			skill,
+			message: `Areg sees ${skill}, but Pi's model-facing skill inventory ${inventoryQualifier(inspection.piSkillInventory)} does not expose it.`,
+			remediation:
+				"Refresh Pi startup skill inventory or add/verify a replacement command with areg skill apply command-backed if the skill is command-backed.",
+			evidence: {
+				piInventoryApproximation: inspection.piSkillInventory.isApproximation,
+				piInventorySource: inspection.piSkillInventory.source,
+				exposedSkillNames: [...inspection.piSkillInventory.skillNames],
+			},
+		});
+	}
+	for (const skill of [...exposed].sort()) {
+		if (expected.has(skill)) continue;
+		findings.push({
+			code: "pi-inventory-extra-skill",
+			severity: "info",
+			skill,
+			message: `Pi's model-facing skill inventory ${inventoryQualifier(inspection.piSkillInventory)} exposes ${skill}, but areg does not manage it.`,
+			remediation:
+				"Remove stale Pi skill inventory entries or add the skill to an areg-managed root.",
+			evidence: { piInventorySource: inspection.piSkillInventory.source },
+		});
+	}
+	return findings;
+}
+
+function replacementFindings(
+	records: readonly SkillKindRecord[],
+	exclusions: readonly string[],
+): readonly DoctorSkillFinding[] {
+	const findings: DoctorSkillFinding[] = [];
+	const excludedSkills = new Set(
+		exclusions
+			.filter((entry) => entry.startsWith("-skills/"))
+			.map((entry) => entry.slice("-skills/".length)),
+	);
+	for (const record of records) {
+		// Unlisted skills are deliberately excluded without a Pi replacement; their
+		// drift states (mirrors present, missing sidecar, ...) infer other kinds and
+		// still reach this finding.
+		if (record.kind === "unlisted") continue;
+		if (record.artifacts.isPiExcluded && !record.replacement.verified) {
+			findings.push(
+				replacementFinding(record.skill, record.replacement.surface, {
+					code: "excluded-skill-without-replacement",
+					severity: "error",
+					message: `${record.skill} is excluded in .pi/settings.json without a verified replacement surface.`,
+					remediation:
+						"Add the replacement Pi command surface and keep the exclusion, or remove the exclusion.",
+				}),
+			);
+		}
+		if (record.replacement.verified && !record.artifacts.isPiExcluded) {
+			findings.push(
+				replacementFinding(record.skill, record.replacement.surface, {
+					code: "command-backed-skill-not-excluded",
+					severity: "warning",
+					message: `${record.skill} has a verified replacement command but is not excluded from Pi skill discovery.`,
+					remediation:
+						"Run areg skill apply command-backed <skill> if this skill is command-backed, or remove the stale replacement surface expectation.",
+				}),
+			);
+		}
+	}
+	for (const skill of [...excludedSkills].sort()) {
+		if (records.some((record) => record.skill === skill)) continue;
+		const surface = commandBackedSkillSurface(skill);
+		findings.push(
+			replacementFinding(skill, surface, {
+				code: "excluded-skill-without-replacement",
+				severity: "error",
+				message: `${skill} is excluded in .pi/settings.json but was not found in areg's skill inventory.`,
+				remediation: "Remove the stale exclusion or restore the skill and its replacement command.",
+			}),
+		);
+	}
+	return findings;
+}
+
+function replacementFinding(
+	skill: string,
+	surface: string | undefined,
+	finding: Pick<DoctorSkillFinding, "code" | "severity" | "message" | "remediation">,
+): DoctorSkillFinding {
+	return {
+		...finding,
+		skill,
+		...optionalEntry("surface", surface),
+	};
+}
+
+type SkillRoot = "skills" | ".agents/skills" | ".claude/skills";
+
+function rootsForSkill(inventory: AregSkillNameInventory, skillName: string): SkillRoot[] {
+	const roots: SkillRoot[] = [];
+	if (inventory.skillsDirectoryNames.includes(skillName)) roots.push("skills");
+	if (inventory.agentsSkillNames.includes(skillName)) roots.push(".agents/skills");
+	if (inventory.claudeSkillNames.includes(skillName)) roots.push(".claude/skills");
+	return roots;
+}
+
+function allKnownSkillNames(
+	inventory: AregSkillNameInventory,
+	options: { includeSkillKindNames?: boolean } = {},
+): readonly string[] {
+	return uniqueSortedStrings([
+		...inventory.skillsDirectoryNames,
+		...inventory.agentsSkillNames,
+		...inventory.claudeSkillNames,
+		...(options.includeSkillKindNames === true ? inventory.skillKindNames : []),
+	]);
+}
+
+function independentRootsForSkill(
+	skillName: string,
+	roots: readonly SkillRoot[],
+	checkSkill: AregCheckSkillInspection | undefined,
+): readonly SkillRoot[] {
+	return roots.filter((root) => !isAregManagedMirrorRoot(skillName, root, checkSkill));
+}
+
+function isAregManagedMirrorRoot(
+	skillName: string,
+	root: SkillRoot,
+	checkSkill: AregCheckSkillInspection | undefined,
+): boolean {
+	if (checkSkill === undefined) return false;
+	switch (root) {
+		case "skills":
+			return false;
+		case ".agents/skills":
+			return isAgentsSkillMirror(checkSkill.agentsPath, skillName);
+		case ".claude/skills":
+			return isClaudeSkillMirror(checkSkill.claudePath, skillName);
+	}
+}
+
+function missingSkillMdFinding(skill: string, path: string): DoctorSkillFinding {
+	return {
+		code: "skill-root-missing-skill-md",
+		severity: "error",
+		skill,
+		path,
+		message: `${path} is missing or unreadable.`,
+		remediation: "Add a readable SKILL.md or remove the directory from the skill root.",
+	};
+}
+
+function countFindings(
+	findings: readonly DoctorSkillFinding[],
+): Record<DoctorSkillFindingSeverity, number> {
+	return {
+		error: findings.filter((finding) => finding.severity === "error").length,
+		warning: findings.filter((finding) => finding.severity === "warning").length,
+		info: findings.filter((finding) => finding.severity === "info").length,
+	};
+}
+
+function statusForCounts(counts: Record<DoctorSkillFindingSeverity, number>): DoctorSkillsStatus {
+	if (counts.error > 0) return "error";
+	if (counts.warning > 0) return "warning";
+	return "ok";
+}
+
+function inventoryQualifier(inventory: AregPiSkillInventoryInspection): string {
+	return inventory.isApproximation ? "approximation" : "snapshot";
+}
+
+function sortFindings(findings: readonly DoctorSkillFinding[]): readonly DoctorSkillFinding[] {
+	return [...findings].sort(
+		(left, right) =>
+			DOCTOR_SKILL_SEVERITY_RANK[left.severity] - DOCTOR_SKILL_SEVERITY_RANK[right.severity] ||
+			left.code.localeCompare(right.code) ||
+			(left.skill ?? "").localeCompare(right.skill ?? "") ||
+			(left.path ?? left.surface ?? "").localeCompare(right.path ?? right.surface ?? ""),
+	);
+}

package/src/operations/file-state.ts

@@ -0,0 +1,77 @@
+import { optionalEntry } from "@nseng-ai/foundation/primitives";
+import { resultErr, type Result } from "@nseng-ai/foundation/result";
+
+import type { AregPathState, AregTextFileState } from "../gateways.ts";
+
+type NonUsableTextFileState = Exclude<AregTextFileState, { type: "file" } | { type: "missing" }>;
+type NonUsableDirectoryState = Exclude<AregPathState, { type: "directory" } | { type: "missing" }>;
+
+export function isPathStateError(error: { code: string }): boolean {
+	return (
+		error.code === "path_symlink" ||
+		error.code === "path_not_file" ||
+		error.code === "path_not_directory"
+	);
+}
+
+export function validateOptionalDirectoryState(options: {
+	pathLabel: string;
+	state: AregPathState;
+	action: string;
+	symlinkSubject?: string;
+}): Result<undefined> {
+	if (options.state.type === "missing" || options.state.type === "directory")
+		return { ok: true, value: undefined };
+	return rejectDirectoryState({
+		pathLabel: options.pathLabel,
+		state: options.state,
+		action: options.action,
+		...optionalEntry("symlinkSubject", options.symlinkSubject),
+	});
+}
+
+export function rejectTextState<T>(options: {
+	pathLabel: string;
+	state: NonUsableTextFileState;
+	action: string;
+	description?: string;
+	unreadableMode?: "failed-read" | "not-file";
+}): Result<T> {
+	if (options.state.type === "symlink") {
+		const subject =
+			options.description === undefined
+				? options.pathLabel
+				: `${options.description} at ${options.pathLabel}`;
+		return resultErr({
+			code: "path_symlink",
+			message: `${subject} is a symlink; refusing to ${options.action}.`,
+		});
+	}
+	if (options.state.type === "unreadable" && options.unreadableMode !== "not-file") {
+		return resultErr({
+			code: "path_read_failed",
+			message: `Failed to read ${options.pathLabel}: ${options.state.message}`,
+		});
+	}
+	return resultErr({
+		code: "path_not_file",
+		message: `${options.pathLabel} exists but is not a file.`,
+	});
+}
+
+function rejectDirectoryState<T>(options: {
+	pathLabel: string;
+	state: NonUsableDirectoryState;
+	action: string;
+	symlinkSubject?: string;
+}): Result<T> {
+	if (options.state.type === "symlink")
+		return resultErr({
+			code: "path_symlink",
+			message: `${options.symlinkSubject ?? options.pathLabel} is a symlink; refusing to ${options.action}.`,
+		});
+	return resultErr({
+		code: "path_not_directory",
+		message: `${options.pathLabel} exists but is not a directory.`,
+	});
+}

package/src/operations/frontmatter.ts

@@ -0,0 +1,151 @@
+import {
+	splitMarkdownFrontmatter,
+	stripLineEnding,
+} from "@nseng-ai/foundation/markdown-frontmatter";
+import { err, type Result } from "@nseng-ai/foundation/result";
+
+const FRONTMATTER_KEY_RE = /^(?<key>[A-Za-z0-9_-]+):(?<value>.*)$/u;
+
+export interface SkillFrontmatterData {
+	fields: Readonly<Record<string, string>>;
+	keys: ReadonlySet<string>;
+}
+
+export type SkillFrontmatterParseResult = Result<SkillFrontmatterData>;
+
+export type SkillFrontmatterTopLevelLineParseResult =
+	| { type: "key"; key: string; value: string }
+	| { type: "not_top_level" }
+	| { type: "invalid"; line: string };
+
+export function parseSkillFrontmatterBlock(text: string): SkillFrontmatterParseResult {
+	const split = splitMarkdownFrontmatter(text);
+	if (split.type === "not_found")
+		return err({
+			code: "frontmatter_missing_opening_delimiter",
+			message: "missing opening frontmatter delimiter '---'",
+		});
+	if (split.type === "missing_closing_fence")
+		return err({
+			code: "frontmatter_missing_closing_delimiter",
+			message: "missing closing frontmatter delimiter '---'",
+		});
+
+	const lines = split.block.frontmatterLinesWithEndings.map(stripLineEnding);
+	const fields: Record<string, string> = {};
+	const keys = new Set<string>();
+	let currentKey: string | undefined;
+	let currentValues: string[] = [];
+	function flushCurrent(): void {
+		if (currentKey === undefined) return;
+		let rawValue = currentValues
+			.filter((value) => value.length > 0)
+			.join(" ")
+			.trim();
+		if (
+			rawValue.length >= 2 &&
+			rawValue[0] === rawValue.at(-1) &&
+			(rawValue[0] === '"' || rawValue[0] === "'")
+		)
+			rawValue = rawValue.slice(1, -1);
+		fields[currentKey] = rawValue;
+	}
+	for (const line of lines) {
+		const stripped = line.trim();
+		if (stripped.length === 0) continue;
+		if (stripped.startsWith("#")) continue;
+		const parsedLine = parseSkillFrontmatterTopLevelLine(line);
+		if (parsedLine.type === "key") {
+			flushCurrent();
+			if (keys.has(parsedLine.key))
+				return err({
+					code: "frontmatter_duplicate_key",
+					message: `duplicate frontmatter key: ${JSON.stringify(parsedLine.key)}`,
+				});
+			currentKey = parsedLine.key;
+			keys.add(currentKey);
+			currentValues = [];
+			const inlineValue = parsedLine.value.trim();
+			if (inlineValue.length > 0) currentValues.push(inlineValue);
+			continue;
+		}
+		if (parsedLine.type === "invalid")
+			return err({
+				code: "frontmatter_invalid_line",
+				message: `invalid frontmatter line: ${JSON.stringify(parsedLine.line)}`,
+			});
+		if (currentKey === undefined)
+			return err({
+				code: "frontmatter_invalid_line",
+				message: `invalid frontmatter line: ${JSON.stringify(line)}`,
+			});
+		currentValues.push(line.trim());
+	}
+	flushCurrent();
+	return { ok: true, value: { fields, keys } };
+}
+
+export function parseSkillFrontmatterTopLevelLine(
+	line: string,
+): SkillFrontmatterTopLevelLineParseResult {
+	const content = stripLineEnding(line);
+	if (content.trim().length === 0) return { type: "not_top_level" };
+	if (content.trim().startsWith("#")) return { type: "not_top_level" };
+	if (content.startsWith(" ") || content.startsWith("\t")) return { type: "not_top_level" };
+	const match = FRONTMATTER_KEY_RE.exec(content);
+	if (match?.groups === undefined) return { type: "invalid", line: content };
+	return { type: "key", key: match.groups.key ?? "", value: match.groups.value ?? "" };
+}
+
+export function isSkillFrontmatterTopLevelKey(line: string, key: string): boolean {
+	const parsed = parseSkillFrontmatterTopLevelLine(line);
+	return parsed.type === "key" && parsed.key === key;
+}
+
+export function transformSkillFrontmatter(
+	text: string,
+	pathLabel: string,
+	desired: Readonly<Record<string, string | undefined>>,
+): Result<string> {
+	const parsed = parseSkillFrontmatterBlock(text);
+	if (!parsed.ok)
+		return {
+			ok: false,
+			error: { ...parsed.error, message: `${pathLabel} ${parsed.error.message}` },
+		};
+
+	const split = splitMarkdownFrontmatter(text);
+	if (split.type !== "found")
+		return err({
+			code: "frontmatter_invalid_bounds",
+			message: `${pathLabel} invalid frontmatter bounds`,
+		});
+
+	const lines = [...split.block.linesWithEndings];
+	const nameIndex = lines.findIndex(
+		(line, index) =>
+			index > 0 && index < split.block.closingIndex && isSkillFrontmatterTopLevelKey(line, "name"),
+	);
+	if (nameIndex === -1)
+		return err({
+			code: "frontmatter_missing_name",
+			message: `${pathLabel} missing name field in frontmatter`,
+		});
+
+	const managedKeys = Object.keys(desired);
+	const kept = lines.filter(
+		(line, index) =>
+			index <= 0 ||
+			index >= split.block.closingIndex ||
+			!managedKeys.some((key) => isSkillFrontmatterTopLevelKey(line, key)),
+	);
+	const keptNameIndex = kept.findIndex(
+		(line, index) => index > 0 && isSkillFrontmatterTopLevelKey(line, "name"),
+	);
+	const additions = managedKeys.flatMap((key) => {
+		const value = desired[key];
+		return value === undefined ? [] : [`${key}: ${value}${split.block.lineEnding}`];
+	});
+	kept.splice(keptNameIndex + 1, 0, ...additions);
+	return { ok: true, value: kept.join("") };
+}