mdat 3.4.1 → 3.6.0

package/dist/{lib-CG4EOuoa.js → lib-CqQWGRqt.js}

@@ -17,6 +17,7 @@ import { isFile, isFileSync } from "path-type";
 import { promisify } from "node:util";
 import { brotliCompress, gzip } from "node:zlib";
 import prettyBytes from "pretty-bytes";
+import { matter } from "gray-matter-es";
 import { toc } from "mdast-util-toc";
 import { VFile } from "vfile";
 import { Configuration } from "unified-engine";
@@ -25,14 +26,13 @@ import { confirm, group, intro, note, outro, select } from "@clack/prompts";
 
 //#region package.json
 var name = "mdat";
-var version = "3.4.1";
+var version = "3.6.0";
 
 //#endregion
 //#region src/lib/deep-merge-defined.ts
 const deepmerge = deepmergeCustom({ mergeArrays: false });
 function stripUndefinedDeep(object) {
-	if (Array.isArray(object)) return object.map((v) => v !== null && typeof v === "object" ? stripUndefinedDeep(v) : v).filter((v) => v !== void 0);
-	return Object.entries(object).map(([k, v]) => [k, v !== null && typeof v === "object" ? stripUndefinedDeep(v) : v]).reduce((acc, [k, v]) => v === void 0 ? acc : {
+	return Array.isArray(object) ? object.map((v) => v !== null && typeof v === "object" ? stripUndefinedDeep(v) : v).filter((v) => v !== void 0) : Object.entries(object).map(([k, v]) => [k, v !== null && typeof v === "object" ? stripUndefinedDeep(v) : v]).reduce((acc, [k, v]) => v === void 0 ? acc : {
 		...acc,
 		[k]: v
 	}, {});
@@ -192,6 +192,29 @@ function getHomebrewFormula(packageName, scripts) {
 	}
 }
 /**
+* VS Code Marketplace item identifier for packages that are VS Code extensions,
+* identified by an `engines.vscode` field.
+*
+* @returns E.g. `kitschpatrol.tldraw-preview`, or undefined if the package
+*   isn't an extension
+*/
+function getVscodeExtensionId(nodePackage) {
+	return typeof nodePackage?.publisher === "string" && nodePackage.engines?.vscode !== void 0 ? `${nodePackage.publisher}.${nodePackage.name}` : void 0;
+}
+/**
+* Obsidian community plugin identifier, from the plugin's manifest.json.
+*/
+function getObsidianPluginId(manifests) {
+	return helpers.firstOf(manifests)?.data.id;
+}
+/**
+* Package location within a monorepo, from the package.json
+* `repository.directory` field.
+*/
+function getRepositoryDirectory(nodePackage) {
+	return typeof nodePackage?.repository === "object" ? nodePackage.repository.directory : void 0;
+}
+/**
 * Reset cached context metadata. Call between tests or when the underlying
 * project files may have changed on disk.
 *
@@ -201,12 +224,12 @@ function resetContextMetadata() {
 	metascopeMetadata = void 0;
 }
 const readmeMetadataTemplate = defineTemplate((context) => {
-	const { githubActions, gitStats, licenseFile, metascope, nodePackageJson } = context;
+	const { githubActions, gitStats, licenseFile, metascope, nodePackageJson, obsidianPluginManifestJson } = context;
 	const codemeta = templates.codemetaJson(context, {});
 	const nodePackage = helpers.firstOf(nodePackageJson)?.data;
 	const licenseFileData = helpers.firstOf(licenseFile);
 	const ciActionFilePath = helpers.ensureArray(githubActions).find((entry) => entry.data.name.toLowerCase() === "ci")?.source;
-	const repoUrl = codemeta.codeRepository?.replace(GIT_PREFIX_REGEX, "").replace(GIT_SUFFIX_REGEX, "").replace(TRAILING_SLASH_REGEX, "");
+	const repositoryUrl = codemeta.codeRepository?.replace(GIT_PREFIX_REGEX, "").replace(GIT_SUFFIX_REGEX, "").replace(TRAILING_SLASH_REGEX, "");
 	const bin = (() => {
 		if (nodePackage === void 0) return;
 		const binField = nodePackage.bin;
@@ -256,6 +279,9 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 		};
 	})();
 	const homebrewFormula = getHomebrewFormula(nodePackage?.name, nodePackage?.scripts);
+	const repositoryDirectory = getRepositoryDirectory(nodePackage);
+	const vscodeExtensionId = getVscodeExtensionId(nodePackage);
+	const obsidianPluginId = getObsidianPluginId(obsidianPluginManifestJson);
 	const firstAuthor = helpers.firstOf(helpers.ensureArray(codemeta.author));
 	return {
 		author: helpers.firstOf(helpers.mixedStringsToArray(helpers.toBasicNames(codemeta.author))),
@@ -275,12 +301,15 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 		licenseFilePath: licenseFileData?.source,
 		licenseUrl: licenseFileData?.data.match?.spdxUrl,
 		name: codemeta.name,
+		obsidianPluginId,
 		operatingSystem: codemeta.operatingSystem ?? getSupportedOperatingSystems(nodePackage?.os),
 		peerDependencies,
 		projectDirectory: metascope?.data.options.path === void 0 ? void 0 : `file://${metascope.data.options.path}`,
-		repositoryUrl: repoUrl,
+		repositoryDirectory,
+		repositoryUrl,
 		runtimePlatform: codemeta.runtimePlatform,
-		usesGitLfs: helpers.firstOf(gitStats)?.data.hasLfs === true
+		usesGitLfs: helpers.firstOf(gitStats)?.data.hasLfs === true,
+		vscodeExtensionId
 	};
 });
 let readmeMetadata;
@@ -315,24 +344,159 @@ function resetMetadataCaches() {
 
 //#endregion
 //#region src/lib/readme/rules/badges.ts
+const HOMEBREW_FORMULA_REGEX = /^(?<owner>[^\/]+)\/(?<tap>[^\/]+)\/(?<formula>[^\/]+)$/v;
+const GITHUB_REPOSITORY_REGEX$1 = /^https:\/\/github\.com\/(?<owner>[^\/]+)\/(?<repo>[^\/]+)$/v;
+const NO_NPM_PACKAGE = "no public npm package was found. Remove \"private\": true from package.json if the package is published, or list packages explicitly, e.g. badges({ npm: [\"package-name\"] })";
+const optionsSchema$2 = z.object({
+	bundleSize: z.boolean().optional(),
+	ci: z.boolean().optional(),
+	custom: z.record(z.string(), z.object({
+		image: z.string(),
+		link: z.string()
+	})).default({}),
+	githubRelease: z.boolean().optional(),
+	gitLfs: z.boolean().optional(),
+	homebrew: z.union([z.boolean(), z.string().regex(HOMEBREW_FORMULA_REGEX, "The badges \"homebrew\" option expects a formula in the form \"owner/tap/formula\"")]).optional(),
+	license: z.boolean().optional(),
+	npm: z.union([z.boolean(), z.array(z.string()).min(1, "Pass npm: false instead of an empty array to hide the NPM version badge")]).optional(),
+	npmDownloads: z.boolean().optional(),
+	obsidianDownloads: z.boolean().optional(),
+	vscode: z.boolean().optional()
+});
+/**
+* Escape text for a path segment of a shields.io static badge, where `-` and
+* `_` are delimiters and must be doubled to appear literally.
+*/
+function escapeStaticBadgeText(text) {
+	return encodeURIComponent(text.replaceAll("-", "--").replaceAll("_", "__"));
+}
+/**
+* One badge per npm package, for badges that report on npm packages.
+*/
+function mapNpmPackages(npmPackages, toBadge) {
+	return npmPackages.length === 0 ? { unavailable: NO_NPM_PACKAGE } : npmPackages.map((packageName) => toBadge(packageName));
+}
+/**
+* Owner and name of the project's GitHub repository, or undefined if the
+* repository isn't on GitHub.
+*/
+function getGithubRepository(repositoryUrl = "") {
+	const { owner, repo } = GITHUB_REPOSITORY_REGEX$1.exec(repositoryUrl)?.groups ?? {};
+	return owner === void 0 || repo === void 0 ? void 0 : {
+		owner,
+		repo
+	};
+}
+/**
+* Reason for badges that need a GitHub repository.
+*/
+function getNotGithubReason(repositoryUrl) {
+	return `${repositoryUrl === void 0 ? "no repository URL was found in the project metadata" : `the repository URL "${repositoryUrl}" is not a GitHub repository`}. Set the "repository" field in package.json to the project's GitHub repository.`;
+}
+/**
+* Explicit package names are useful for monorepos. Otherwise the package itself
+* is used if it's public, even when the NPM version badge is hidden, so the
+* download and size badges can still appear.
+*/
+function getNpmPackages(option, { isPublicNpmPackage, name }) {
+	if (Array.isArray(option)) return option;
+	return isPublicNpmPackage && name !== void 0 ? [name] : [];
+}
+/**
+* Badges in display order. Each appears when its metadata is available unless
+* it's `optIn`, and its option can hide it (`false`) or require it (`true`).
+*/
+const badgeDefinitions = [
+	{
+		key: "npm",
+		render: ({ npmPackages }) => mapNpmPackages(npmPackages, (packageName) => `[![NPM Package ${packageName}](https://img.shields.io/npm/v/${packageName}.svg)](https://www.npmjs.com/package/${packageName})`)
+	},
+	{
+		key: "license",
+		render: ({ license, licenseUrl }) => license === void 0 || licenseUrl === void 0 ? { unavailable: "no license file matching a known SPDX license was found" } : [`[![License: ${license}](https://img.shields.io/badge/License-${license.replaceAll("-", "--")}-yellow.svg)](${licenseUrl})`]
+	},
+	{
+		key: "ci",
+		render({ ciActionFileName, repositoryUrl }) {
+			if (ciActionFileName === void 0) return { unavailable: "no GitHub Actions workflow named \"CI\" was found in .github/workflows" };
+			if (repositoryUrl === void 0) return { unavailable: "no repository URL was found in the project metadata" };
+			return [`[![CI](${repositoryUrl}/actions/workflows/${ciActionFileName}/badge.svg)](${repositoryUrl}/actions/workflows/${ciActionFileName})`];
+		}
+	},
+	{
+		key: "gitLfs",
+		render: ({ usesGitLfs }) => usesGitLfs ? ["![Git LFS](https://img.shields.io/badge/Git%20LFS-enabled-F64935?logo=gitlfs&logoColor=white)"] : { unavailable: "the repository does not track any files with Git LFS" }
+	},
+	{
+		key: "vscode",
+		render({ repositoryDirectory, repositoryUrl, vscodeExtensionId }) {
+			if (vscodeExtensionId === void 0) return { unavailable: "package.json is missing a \"publisher\" or \"engines.vscode\" field" };
+			const repository = getGithubRepository(repositoryUrl);
+			if (repository === void 0) return { unavailable: `the extension version is read from package.json on GitHub, but ${getNotGithubReason(repositoryUrl)}` };
+			const packageJsonPath = [repositoryDirectory, "package.json"].filter((segment) => segment !== void 0).join("/");
+			const packageJsonUrl = `https://raw.githubusercontent.com/${repository.owner}/${repository.repo}/HEAD/${packageJsonPath}`;
+			return [`[![Visual Studio Marketplace Version](https://img.shields.io/badge/dynamic/json?url=${encodeURIComponent(packageJsonUrl)}&query=version&label=VS%20Code%20Marketplace)](https://marketplace.visualstudio.com/items?itemName=${vscodeExtensionId})`];
+		}
+	},
+	{
+		key: "homebrew",
+		render({ homebrewFormula, options }) {
+			const formulaPath = typeof options.homebrew === "string" ? options.homebrew : homebrewFormula;
+			if (formulaPath === void 0) return { unavailable: "no \"brewpub --tap <owner>/<tap>\" invocation was found in the package.json scripts. Pass the formula explicitly instead, e.g. badges({ homebrew: \"owner/tap/formula\" })" };
+			const formulaParts = HOMEBREW_FORMULA_REGEX.exec(formulaPath)?.groups;
+			if (formulaParts?.owner === void 0 || formulaParts.tap === void 0 || formulaParts.formula === void 0) return { unavailable: `the detected formula "${formulaPath}" is not in the form "owner/tap/formula"` };
+			const { formula, owner, tap } = formulaParts;
+			return [`[![Homebrew](https://img.shields.io/badge/Homebrew-${escapeStaticBadgeText(formulaPath)}-FBB040?logo=homebrew&logoColor=white)](https://github.com/${owner}/homebrew-${tap}/blob/HEAD/Formula/${formula}.rb)`];
+		}
+	},
+	{
+		key: "githubRelease",
+		optIn: true,
+		render({ repositoryUrl }) {
+			const repository = getGithubRepository(repositoryUrl);
+			if (repository === void 0) return { unavailable: getNotGithubReason(repositoryUrl) };
+			const { owner, repo } = repository;
+			return [`[![GitHub Release](https://img.shields.io/github/v/release/${owner}/${repo}?label=Release)](https://github.com/${owner}/${repo}/releases/latest)`];
+		}
+	},
+	{
+		key: "npmDownloads",
+		optIn: true,
+		render: ({ npmPackages }) => mapNpmPackages(npmPackages, (packageName) => `[![NPM Downloads ${packageName}](https://img.shields.io/npm/dm/${packageName})](https://www.npmjs.com/package/${packageName})`)
+	},
+	{
+		key: "obsidianDownloads",
+		optIn: true,
+		render({ obsidianPluginId }) {
+			if (obsidianPluginId === void 0) return { unavailable: "no Obsidian plugin manifest.json was found" };
+			const statsUrl = "https://raw.githubusercontent.com/obsidianmd/obsidian-releases/master/community-plugin-stats.json";
+			const query = `$["${obsidianPluginId}"].downloads`;
+			return [`[![Obsidian Downloads](https://img.shields.io/badge/dynamic/json?logo=obsidian&color=%23A88BFA&label=Downloads&query=${encodeURIComponent(query)}&url=${encodeURIComponent(statsUrl)})](https://community.obsidian.md/plugins/${obsidianPluginId})`];
+		}
+	},
+	{
+		key: "bundleSize",
+		optIn: true,
+		render: ({ npmPackages }) => mapNpmPackages(npmPackages, (packageName) => `[![Bundle Size ${packageName}](https://img.shields.io/bundlephobia/minzip/${packageName}?label=Size)](https://bundlephobia.com/package/${packageName})`)
+	}
+];
 var badges_default = { badges: { async content(options) {
-	const validOptions = z.object({
-		custom: z.record(z.string(), z.object({
-			image: z.string(),
-			link: z.string()
-		})).optional(),
-		npm: z.array(z.string()).optional()
-	}).optional().parse(options);
+	const validOptions = optionsSchema$2.parse(options ?? {});
 	const metadata = await getReadmeMetadata();
-	const { ciActionFileName, license, licenseUrl, name, repositoryUrl, usesGitLfs } = metadata;
+	const context = {
+		...metadata,
+		npmPackages: getNpmPackages(validOptions.npm, metadata),
+		options: validOptions
+	};
 	const badges = [];
-	if (validOptions?.npm === void 0) {
-		if (metadata.isPublicNpmPackage) badges.push(`[![NPM Package ${name}](https://img.shields.io/npm/v/${name}.svg)](https://www.npmjs.com/package/${name})`);
-	} else for (const packageName of validOptions.npm) badges.push(`[![NPM Package ${packageName}](https://img.shields.io/npm/v/${packageName}.svg)](https://www.npmjs.com/package/${packageName})`);
-	if (license !== void 0 && licenseUrl !== void 0) badges.push(`[![License: ${license}](https://img.shields.io/badge/License-${license.replaceAll("-", "--")}-yellow.svg)](${licenseUrl})`);
-	if (ciActionFileName !== void 0 && repositoryUrl !== void 0) badges.push(`[![CI](${repositoryUrl}/actions/workflows/${ciActionFileName}/badge.svg)](${repositoryUrl}/actions/workflows/${ciActionFileName})`);
-	if (usesGitLfs) badges.push("![Git LFS](https://img.shields.io/badge/Git%20LFS-enabled-F64935?logo=gitlfs&logoColor=white)");
-	if (validOptions?.custom !== void 0) for (const [badgeName, { image, link }] of Object.entries(validOptions.custom)) badges.push(`[![${badgeName}](${image})](${link})`);
+	for (const { key, optIn = false, render } of badgeDefinitions) {
+		const option = validOptions[key];
+		if (option === false || optIn && option === void 0) continue;
+		const result = render(context);
+		if (Array.isArray(result)) badges.push(...result);
+		else if (option !== void 0) throw new Error(`The "${key}" badge was requested, but ${result.unavailable}`);
+	}
+	for (const [badgeName, { image, link }] of Object.entries(validOptions.custom)) badges.push(`[![${badgeName}](${image})](${link})`);
 	return badges.join("\n");
 } } };
 
@@ -417,29 +581,51 @@ var code_default = { code: { async content(options) {
 
 //#endregion
 //#region src/lib/readme/rules/utilities/heading.ts
+const MAX_HEADING_LEVEL = 6;
 /**
 * Option schema for the Markdown heading level (1-6) at which a rule emits its
-* section heading. Sub-headings, if any, are nested one level deeper. Rules
-* default to level 3, matching their placement under a level 2 section like
-* "Getting started" in the house readme template.
+* section heading. Sub-headings, if any, are nested one level deeper, whether
+* or not the section heading itself is shown. Each rule's default matches its
+* placement in the house readme template.
+*/
+const headingLevelSchema = z.number().int().min(1).max(MAX_HEADING_LEVEL).optional();
+/**
+* Option schema for a rule's section heading. `true` (the default) emits the
+* rule's standard heading, `false` leaves the heading out, and a string
+* replaces the heading text.
 */
-const headingLevelSchema = z.number().int().min(1).max(6).optional();
+const headingSchema = z.union([z.boolean(), z.string().trim().min(1)]).optional();
 /**
 * The `#` prefix for a Markdown heading, clamped to the maximum level of 6.
 */
 function getHeadingPrefix(level) {
-	return "#".repeat(Math.min(level, 6));
+	return "#".repeat(Math.min(level, MAX_HEADING_LEVEL));
+}
+/**
+* The lines of a rule's section heading, including the blank line separating it
+* from the section body, or no lines if the heading is suppressed.
+*
+* @param heading - Value of the rule's `heading` option
+* @param level - Markdown heading level
+* @param defaultText - Heading text used unless `heading` overrides it
+*/
+function getHeadingLines(heading, level, defaultText) {
+	if (heading === false) return [];
+	const text = typeof heading === "string" ? heading : defaultText;
+	return [`${getHeadingPrefix(level)} ${text}`, ""];
 }
 
 //#endregion
 //#region src/lib/readme/rules/contributing.ts
 var contributing_default = { contributing: { async content(options) {
-	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
+	const validOptions = z.object({
+		heading: headingSchema,
+		headingLevel: headingLevelSchema
+	}).optional().parse(options);
 	const { issuesUrl } = await getReadmeMetadata();
 	if (issuesUrl === void 0) throw new Error("Could not find \"bugs.url\" entry in package.json");
 	return [
-		`${getHeadingPrefix(validOptions?.headingLevel ?? 2)} Contributing`,
-		"",
+		...getHeadingLines(validOptions?.heading, validOptions?.headingLevel ?? 2, "Contributing"),
 		`[Issues](${issuesUrl}) are welcome and appreciated.`,
 		"",
 		"Please open an issue to discuss changes before submitting a pull request. Unsolicited PRs (especially AI-generated ones) are unlikely to be merged.",
@@ -529,7 +715,10 @@ function getPlatformItem(key, version) {
 	return version === void 0 || version.trim() === "" ? `- ${display}` : `- ${display} ${describeVersionRange(version)}`;
 }
 var dependencies_default = { dependencies: { async content(options) {
-	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
+	const validOptions = z.object({
+		heading: headingSchema,
+		headingLevel: headingLevelSchema
+	}).optional().parse(options);
 	const { engines, operatingSystem, peerDependencies, runtimePlatform } = await getReadmeMetadata();
 	const items = [];
 	const engineEntries = Object.entries(engines ?? {});
@@ -550,11 +739,7 @@ var dependencies_default = { dependencies: { async content(options) {
 		items.push(`- [${name}](${npmUrl}) \`${version}\` _(peer dependency)_`);
 	}
 	if (items.length === 0) return "";
-	return [
-		`${getHeadingPrefix(validOptions?.headingLevel ?? 3)} Dependencies`,
-		"",
-		...items
-	].join("\n");
+	return [...getHeadingLines(validOptions?.heading, validOptions?.headingLevel ?? 3, "Dependencies"), ...items].join("\n");
 } } };
 
 //#endregion
@@ -597,7 +782,10 @@ const TOOL_INFO = {
 	}
 };
 var development_dependencies_default = { "development-dependencies": { async content(options) {
-	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
+	const validOptions = z.object({
+		heading: headingSchema,
+		headingLevel: headingLevelSchema
+	}).optional().parse(options);
 	const { developmentDependencies } = await getReadmeMetadata();
 	if (developmentDependencies === void 0) return "";
 	const { packageManagers, runtimes } = developmentDependencies;
@@ -607,11 +795,7 @@ var development_dependencies_default = { "development-dependencies": { async con
 		const display = info ? `[${info.display}](${info.url})` : name;
 		items.push(version === void 0 || version === "" ? `- ${display}` : `- ${display} ${version}`);
 	}
-	return [
-		`${getHeadingPrefix(validOptions?.headingLevel ?? 3)} Development dependencies`,
-		"",
-		...items
-	].join("\n");
+	return [...getHeadingLines(validOptions?.heading, validOptions?.headingLevel ?? 3, "Development dependencies"), ...items].join("\n");
 } } };
 
 //#endregion
@@ -624,12 +808,15 @@ var dev_dependencies_default = { "dev-dependencies": getSoleRule(development_dep
 //#endregion
 //#region src/lib/readme/rules/license.ts
 var license_default = { license: { async content(options) {
-	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
+	const validOptions = z.object({
+		heading: headingSchema,
+		headingLevel: headingLevelSchema
+	}).optional().parse(options);
 	const { author, authorUrl, license, licenseFilePath } = await getReadmeMetadata();
 	if (author === void 0) throw new Error("Could not find author name in project");
 	if (license === void 0 || licenseFilePath === void 0) throw new Error("Could not find license for project");
 	const authorDisplay = authorUrl === void 0 ? author : `[${author}](${authorUrl})`;
-	return `${`${getHeadingPrefix(validOptions?.headingLevel ?? 2)} License`}\n[${license}](${licenseFilePath}) © ${authorDisplay}`;
+	return [...getHeadingLines(validOptions?.heading, validOptions?.headingLevel ?? 2, "License"), `[${license}](${licenseFilePath}) © ${authorDisplay}`].join("\n");
 } } };
 
 //#endregion
@@ -683,7 +870,7 @@ const listFormatter = new Intl.ListFormat("en", {
 	style: "long",
 	type: "conjunction"
 });
-function codeBlock(command) {
+function codeBlock$1(command) {
 	return [
 		"```sh",
 		command,
@@ -698,17 +885,17 @@ function getCliLines(name, homebrewFormula) {
 	return [
 		"Run it once without installing:",
 		"",
-		...codeBlock(`npx ${name}`),
+		...codeBlock$1(`npx ${name}`),
 		...homebrewFormula === void 0 ? [] : [
 			"",
 			"Or install it globally with Homebrew:",
 			"",
-			...codeBlock(`brew install ${homebrewFormula}`)
+			...codeBlock$1(`brew install ${homebrewFormula}`)
 		],
 		"",
 		"Or install it globally with npm:",
 		"",
-		...codeBlock(`npm install --global ${name}`)
+		...codeBlock$1(`npm install --global ${name}`)
 	];
 }
 /**
@@ -720,34 +907,34 @@ function getLibraryLines(name, bin, hasTypes, dev) {
 	if (bin === void 0 || bin.length === 0) return [
 		`${lead}:`,
 		"",
-		...codeBlock(command)
+		...codeBlock$1(command)
 	];
 	return [
 		`${lead} to import the ${hasTypes ? "TypeScript API" : "API"}. This also puts the ${listFormatter.format(bin.map((binName) => `\`${binName}\``))} ${bin.length === 1 ? "CLI" : "CLIs"} on your project's path:`,
 		"",
-		...codeBlock(command)
+		...codeBlock$1(command)
 	];
 }
 var install_default = { install: { async content(options) {
 	const validOptions = z.object({
 		dev: z.boolean().optional(),
+		heading: headingSchema,
 		headingLevel: headingLevelSchema,
 		homebrew: z.union([z.string(), z.literal(false)]).optional()
-	}).optional().parse(options);
+	}).parse(options ?? {});
 	const { bin, hasTypes, homebrewFormula, isLibrary, isNodePackage, isPublicNpmPackage, name, runtimePlatform } = await getReadmeMetadata();
 	if (name === void 0) throw new Error("Could not find project name");
-	const headingLevel = validOptions?.headingLevel ?? 3;
-	const heading = `${getHeadingPrefix(headingLevel)} Installation`;
+	const headingLevel = validOptions.headingLevel ?? 3;
+	const headingLines = getHeadingLines(validOptions.heading, headingLevel, "Installation");
 	const subheading = getHeadingPrefix(headingLevel + 1);
 	if (isNodePackage) {
 		if (!isPublicNpmPackage) throw new Error("Install instructions require a publishable package, but package.json sets \"private\": true");
-		const homebrew = validOptions?.homebrew === void 0 ? homebrewFormula : validOptions.homebrew === false ? void 0 : validOptions.homebrew;
+		const homebrew = validOptions.homebrew === void 0 ? homebrewFormula : validOptions.homebrew === false ? void 0 : validOptions.homebrew;
 		const hasCli = bin !== void 0 && bin.length > 0;
 		const cliLines = getCliLines(name, homebrew);
-		const libraryLines = getLibraryLines(name, bin, hasTypes, validOptions?.dev ?? false);
+		const libraryLines = getLibraryLines(name, bin, hasTypes, validOptions.dev ?? false);
 		if (hasCli && isLibrary) return [
-			heading,
-			"",
+			...headingLines,
 			`There are several ways to install ${name} depending on how you're planning to use it:`,
 			"",
 			`${subheading} CLI`,
@@ -758,22 +945,21 @@ var install_default = { install: { async content(options) {
 			"",
 			...libraryLines
 		].join("\n");
-		return [
-			heading,
-			"",
-			...hasCli ? cliLines : libraryLines
-		].join("\n");
+		return [...headingLines, ...hasCli ? cliLines : libraryLines].join("\n");
 	}
 	const platform = (prefix) => runtimePlatform?.some((p) => p.startsWith(prefix));
 	const command = platform("python") ? `pip install ${name}` : platform("rust") ? `cargo install ${name}` : platform("go") ? `go install ${name}@latest` : platform("ruby") ? `gem install ${name}` : void 0;
 	if (command === void 0) throw new Error("Could not determine project ecosystem for install instructions");
-	return [
-		heading,
-		"",
-		...codeBlock(command)
-	].join("\n");
+	return [...headingLines, ...codeBlock$1(command)].join("\n");
 } } };
 
+//#endregion
+//#region src/lib/readme/rules/installation.ts
+/**
+* Simple alias for `install`
+*/
+var installation_default = { installation: getSoleRule(install_default) };
+
 //#endregion
 //#region src/lib/readme/rules/utilities/size/size-report.ts
 const brotliCompressAsync = promisify(brotliCompress);
@@ -899,6 +1085,127 @@ var size_table_default = { "size-table": { async content(options) {
 	});
 } } };
 
+//#endregion
+//#region src/lib/readme/rules/skills.ts
+const SKILLS_DIRECTORY = "skills";
+const SKILL_FILE_NAME = "SKILL.md";
+const GITHUB_REPOSITORY_REGEX = /^https:\/\/github\.com\/(?<slug>[^\/]+\/[^\/]+)$/v;
+const WHITESPACE_REGEX = /\s+/gv;
+const FIRST_SENTENCE_REGEX = /^.*?(?<!\b(?:e\.g|i\.e|vs))[.!?](?=\s+\p{Lu})/v;
+const skillFrontmatterSchema = z.object({
+	description: z.string().trim().min(1),
+	name: z.string().trim().min(1)
+});
+function codeBlock(command) {
+	return [
+		"```sh",
+		command,
+		"```"
+	];
+}
+/**
+* Find Agent Skills in the project's `skills` directory, where each skill is a
+* subdirectory containing a `SKILL.md` file with `name` and `description`
+* frontmatter.
+*
+* @throws {Error} If a `SKILL.md` file has missing or invalid frontmatter
+*/
+async function findSkills(projectDirectory) {
+	const skillsDirectory = path.join(projectDirectory, SKILLS_DIRECTORY);
+	let entries;
+	try {
+		entries = await fs.readdir(skillsDirectory, { withFileTypes: true });
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return [];
+		throw error;
+	}
+	const skills = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const skillFilePath = path.join(skillsDirectory, entry.name, SKILL_FILE_NAME);
+		let skillFile;
+		try {
+			skillFile = await fs.readFile(skillFilePath, "utf8");
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") continue;
+			throw error;
+		}
+		const frontmatter = skillFrontmatterSchema.safeParse(matter(skillFile).data);
+		if (!frontmatter.success) throw new Error(`Skill at "${path.relative(projectDirectory, skillFilePath)}" needs "name" and "description" strings in its frontmatter`);
+		skills.push({
+			...frontmatter.data,
+			filePath: `${SKILLS_DIRECTORY}/${entry.name}/${SKILL_FILE_NAME}`
+		});
+	}
+	return skills.toSorted((a, b) => a.name.localeCompare(b.name));
+}
+/**
+* The argument identifying a repository to the `skills add` command, which
+* accepts an `owner/repo` shorthand for GitHub and full URLs for other hosts.
+*/
+function getSkillsCliSource(repositoryUrl) {
+	return GITHUB_REPOSITORY_REGEX.exec(repositoryUrl)?.groups?.slug ?? repositoryUrl;
+}
+/**
+* The first sentence of a skill description, which by convention says what the
+* skill does, leaving out the guidance on when to use it that follows.
+*/
+function getFirstSentence(description) {
+	const singleLine = description.replaceAll(WHITESPACE_REGEX, " ");
+	return FIRST_SENTENCE_REGEX.exec(singleLine)?.[0] ?? singleLine;
+}
+var skills_default = { skills: { async content(options) {
+	const validOptions = z.object({
+		heading: headingSchema,
+		headingLevel: headingLevelSchema
+	}).optional().parse(options);
+	const skills = await findSkills(process.cwd());
+	if (skills.length === 0) throw new Error(`Could not find any skills, expected at least one "${SKILLS_DIRECTORY}/<name>/${SKILL_FILE_NAME}" file in the project`);
+	const { isPublicNpmPackage, name, repositoryUrl } = await getReadmeMetadata();
+	if (name === void 0) throw new Error("Could not find project name");
+	const headingLevel = validOptions?.headingLevel ?? 2;
+	const skillHeading = getHeadingPrefix(headingLevel + 1);
+	const skillNoun = plur("skill", skills.length);
+	const agentSkillsLink = `${skills.length === 1 ? "an" : skills.length} [${plur("Agent Skill", skills.length)}](https://agentskills.io)`;
+	const skillsCliLink = "Vercel's [skills CLI](https://github.com/vercel-labs/skills)";
+	const headingLines = getHeadingLines(validOptions?.heading, headingLevel, "Agent skills");
+	const skillLines = [`Included ${skillNoun}:`, ...skills.flatMap((skill) => [
+		"",
+		`${skillHeading} Skill: [\`${skill.name}\`](${skill.filePath})`,
+		"",
+		getFirstSentence(skill.description)
+	])];
+	if (!isPublicNpmPackage) {
+		if (repositoryUrl === void 0) throw new Error("Skill install instructions require either a publishable npm package or a repository URL in the project metadata");
+		return [
+			...headingLines,
+			`This project includes ${agentSkillsLink} to help coding agents work with ${name}.`,
+			"",
+			`To install the ${skillNoun}, run ${skillsCliLink}:`,
+			"",
+			...codeBlock(`npx skills add ${getSkillsCliSource(repositoryUrl)}`),
+			"",
+			...skillLines
+		].join("\n");
+	}
+	return [
+		...headingLines,
+		`This project bundles ${agentSkillsLink} in its published package to help coding agents work with ${name}.`,
+		"",
+		`To sync the ${skillNoun} into your project, run ${skillsCliLink} from your project root:`,
+		"",
+		...codeBlock("npx skills experimental_sync"),
+		...repositoryUrl === void 0 ? [] : [
+			"",
+			"Or install globally:",
+			"",
+			...codeBlock(`npx skills add ${getSkillsCliSource(repositoryUrl)} --global`)
+		],
+		"",
+		...skillLines
+	].join("\n");
+} } };
+
 //#endregion
 //#region src/lib/readme/rules/table-of-contents.ts
 var table_of_contents_default = { "table-of-contents": {
@@ -912,6 +1219,7 @@ var table_of_contents_default = { "table-of-contents": {
 				z.literal(5),
 				z.literal(6)
 			]).optional(),
+			heading: headingSchema,
 			headingLevel: headingLevelSchema
 		}).optional().parse(options);
 		const result = toc(tree, {
@@ -920,12 +1228,12 @@ var table_of_contents_default = { "table-of-contents": {
 			tight: true
 		});
 		if (result.map === void 0) throw new Error("Could not generate table of contents");
-		const heading = `${getHeadingPrefix(validOptions?.headingLevel ?? 2)} Table of contents`;
 		const rootWrapper = {
 			children: result.map.children,
 			type: "root"
 		};
-		return [heading, remark().use(remarkGfm).stringify(rootWrapper).replaceAll("\n\n", "\n")].join("\n");
+		const tocString = remark().use(remarkGfm).stringify(rootWrapper).replaceAll("\n\n", "\n");
+		return [...getHeadingLines(validOptions?.heading, validOptions?.headingLevel ?? 2, "Table of contents"), tocString].join("\n");
 	},
 	order: 1
 } };
@@ -951,10 +1259,12 @@ var rules_default = {
 	...footer_default,
 	...header_default,
 	...install_default,
+	...installation_default,
 	...license_default,
 	...short_description_default,
 	...size_default,
 	...size_table_default,
+	...skills_default,
 	...table_of_contents_default,
 	...title_default,
 	...toc_default
@@ -1238,19 +1548,19 @@ var mdat_readme_default = "<!-- title -->\n\n<!-- banner -->\n\n<!-- badges -->\
 
 //#endregion
 //#region src/lib/readme/templates/standard-readme-basic-compound.md?raw
-var standard_readme_basic_compound_default = "<!-- header -->\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" }) --> comment as well.\n```\n\n<!-- footer -->\n";
+var standard_readme_basic_compound_default = "<!-- header -->\n\n<!-- install({ headingLevel: 2 }) -->\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ file: \"path/to/example.ts\" }) --> comment as well.\n```\n\n<!-- footer -->\n";
 
 //#endregion
 //#region src/lib/readme/templates/standard-readme-basic.md?raw
-var standard_readme_basic_default = "<!-- title -->\n\n<!-- short-description -->\n\n<!-- table-of-contents -->\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n<!-- contributing -->\n\n<!-- license -->\n";
+var standard_readme_basic_default = "<!-- title -->\n\n<!-- short-description -->\n\n<!-- table-of-contents -->\n\n<!-- install({ headingLevel: 2 }) -->\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ file: \"path/to/example.ts\" }) --> comment as well.\n```\n\n<!-- contributing -->\n\n<!-- license -->\n";
 
 //#endregion
 //#region src/lib/readme/templates/standard-readme-full-compound.md?raw
-var standard_readme_full_compound_default = "<!-- header -->\n\n_Long description goes here._\n\n_No heading. Cover the main reasons for building the repository. This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module's routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections._\n\n<!-- table-of-contents -->\n\n## Background\n\n_Cover motivation. Cover abstract dependencies. Cover intellectual provenance: A See Also section is also fitting._\n\n### See also\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n### Dependencies\n\n_Required if there are unusual dependencies or dependencies that must be manually installed._\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n```ts\n// If importable, code block indicating both import functionality and usage.\n```\n\n### CLI\n\n```ts\n// If CLI compatible, code block indicating common usage.\n```\n\n## _Extra Sections (Rename)_\n\n## Security\n\n## API\n\n_Describe exported functions and objects._\n\n- _Describe signatures, return types, callbacks, and events._\n- _Cover types covered where not obvious._\n- _Describe caveats._\n- _If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present._\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Thanks\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- footer -->\n";
+var standard_readme_full_compound_default = "<!-- header -->\n\n_Long description goes here._\n\n_No heading. Cover the main reasons for building the repository. This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module's routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections._\n\n<!-- table-of-contents -->\n\n## Background\n\n_Cover motivation. Cover abstract dependencies. Cover intellectual provenance: A See Also section is also fitting._\n\n### See also\n\n<!-- install({ headingLevel: 2 }) -->\n\n<!-- dependencies -->\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ file: \"path/to/example.ts\" }) --> comment as well.\n```\n\n```ts\n// If importable, code block indicating both import functionality and usage.\n```\n\n### CLI\n\n```ts\n// If CLI compatible, code block indicating common usage.\n```\n\n## _Extra Sections (Rename)_\n\n## Security\n\n## API\n\n_Describe exported functions and objects._\n\n- _Describe signatures, return types, callbacks, and events._\n- _Cover types covered where not obvious._\n- _Describe caveats._\n- _If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present._\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Thanks\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- footer -->\n";
 
 //#endregion
 //#region src/lib/readme/templates/standard-readme-full.md?raw
-var standard_readme_full_default = "<!-- title -->\n\n<!-- banner -->\n\n<!-- badges -->\n\n<!-- short-description -->\n\n_Long description goes here._\n\n_No heading. Cover the main reasons for building the repository. This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module's routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections._\n\n<!-- table-of-contents -->\n\n## Background\n\n_Cover motivation. Cover abstract dependencies. Cover intellectual provenance: A See Also section is also fitting._\n\n### See also\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n### Dependencies\n\n_Required if there are unusual dependencies or dependencies that must be manually installed._\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n```ts\n// If importable, code block indicating both import functionality and usage.\n```\n\n### CLI\n\n```ts\n// If CLI compatible, code block indicating common usage.\n```\n\n## _Extra Sections (Rename)_\n\n## Security\n\n## API\n\n_Describe exported functions and objects._\n\n- _Describe signatures, return types, callbacks, and events._\n- _Cover types covered where not obvious._\n- _Describe caveats._\n- _If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present._\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Thanks\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- contributing -->\n\n<!-- license -->\n";
+var standard_readme_full_default = "<!-- title -->\n\n<!-- banner -->\n\n<!-- badges -->\n\n<!-- short-description -->\n\n_Long description goes here._\n\n_No heading. Cover the main reasons for building the repository. This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module's routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections._\n\n<!-- table-of-contents -->\n\n## Background\n\n_Cover motivation. Cover abstract dependencies. Cover intellectual provenance: A See Also section is also fitting._\n\n### See also\n\n<!-- install({ headingLevel: 2 }) -->\n\n<!-- dependencies -->\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ file: \"path/to/example.ts\" }) --> comment as well.\n```\n\n```ts\n// If importable, code block indicating both import functionality and usage.\n```\n\n### CLI\n\n```ts\n// If CLI compatible, code block indicating common usage.\n```\n\n## _Extra Sections (Rename)_\n\n## Security\n\n## API\n\n_Describe exported functions and objects._\n\n- _Describe signatures, return types, callbacks, and events._\n- _Cover types covered where not obvious._\n- _Describe caveats._\n- _If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present._\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Thanks\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- contributing -->\n\n<!-- license -->\n";
 
 //#endregion
 //#region src/lib/readme/templates/index.ts
@@ -1283,6 +1593,8 @@ var templates_default = {
 
 //#endregion
 //#region src/lib/readme/create.ts
+const USAGE_HEADING = "\n## Usage\n";
+const NEXT_SECTION_REGEX = /\n(?:## |<!-- (?:contributing|footer) -->)/v;
 /**
 * Creates a new readme file interactively.
 *
@@ -1339,7 +1651,8 @@ async function createReadme(options) {
 		expand: true,
 		template: Object.keys(templates_default)[0]
 	}, options ?? {});
-	const templateString = getTemplateForConfig(resolvedOptions.template, resolvedOptions.compound);
+	const baseTemplateString = getTemplateForConfig(resolvedOptions.template, resolvedOptions.compound);
+	const templateString = (await findSkills(process.cwd())).length > 0 ? addSkillsPlaceholder(baseTemplateString) : baseTemplateString;
 	const readmePath = path.join(resolvedOptions.output, "readme.md");
 	if (!resolvedOptions.overwrite) {
 		let exists = true;
@@ -1358,6 +1671,20 @@ async function createReadme(options) {
 	}
 	return readmePath;
 }
+/**
+* Adds a `<!-- skills -->` placeholder to a template, between the end of its
+* "Usage" section and whatever follows it.
+*
+* @throws {Error} If the template has no "Usage" section followed by another
+*   section
+*/
+function addSkillsPlaceholder(template) {
+	const usageIndex = template.indexOf(USAGE_HEADING);
+	const nextSectionOffset = usageIndex === -1 ? void 0 : NEXT_SECTION_REGEX.exec(template.slice(usageIndex + 10))?.index;
+	if (nextSectionOffset === void 0) throw new Error("Could not find a \"## Usage\" section followed by another section in the template");
+	const insertIndex = usageIndex + 10 + nextSectionOffset + 1;
+	return `${template.slice(0, insertIndex)}<!-- skills -->\n\n${template.slice(insertIndex)}`;
+}
 function getTemplateForConfig(templateKey, compound) {
 	if (!Object.hasOwn(templates_default, templateKey)) throw new Error(`Unknown template "${templateKey}". Available templates: ${Object.keys(templates_default).join(", ")}`);
 	return templates_default[templateKey].content[compound ? "compound" : "explicit"];