mdat 3.4.0 → 3.5.0

package/dist/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { S as version, a as expand, b as setLogger$1, d as templates_default, f as ensureArray, l as createReadme, r as collapse, s as strip, t as check, u as createReadmeInteractive, x as name, y as log } from "../lib-D8QaJZ-l.js";
+import { S as version, a as expand, b as setLogger$1, d as templates_default, f as ensureArray, l as createReadme, r as collapse, s as strip, t as check, u as createReadmeInteractive, x as name, y as log } from "../lib-D3Djaa1D.js";
 import { createLogger } from "lognow";
 import picocolors from "picocolors";
 import prettyMilliseconds from "pretty-ms";

package/dist/lib/index.js

@@ -1,3 +1,3 @@
-import { _ as getReadmeMetadata, a as expand, b as setLogger, c as stripString, g as getContextMetadata, h as mergeConfig, i as collapseString, l as createReadme, m as loadConfig, n as checkString, o as expandString, p as defineConfig, r as collapse, s as strip, t as check, u as createReadmeInteractive, v as resetMetadataCaches } from "../lib-D8QaJZ-l.js";
+import { _ as getReadmeMetadata, a as expand, b as setLogger, c as stripString, g as getContextMetadata, h as mergeConfig, i as collapseString, l as createReadme, m as loadConfig, n as checkString, o as expandString, p as defineConfig, r as collapse, s as strip, t as check, u as createReadmeInteractive, v as resetMetadataCaches } from "../lib-D3Djaa1D.js";
 
 export { check, checkString, collapse, collapseString, createReadme as create, createReadmeInteractive as createInteractive, defineConfig, expand, expandString, getContextMetadata, getReadmeMetadata, loadConfig, mergeConfig, resetMetadataCaches, setLogger, strip, stripString };

package/dist/{lib-D8QaJZ-l.js → lib-D3Djaa1D.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,7 +26,7 @@ import { confirm, group, intro, note, outro, select } from "@clack/prompts";
 
 //#region package.json
 var name = "mdat";
-var version = "3.4.0";
+var version = "3.5.0";
 
 //#endregion
 //#region src/lib/deep-merge-defined.ts
@@ -683,7 +684,7 @@ const listFormatter = new Intl.ListFormat("en", {
 	style: "long",
 	type: "conjunction"
 });
-function codeBlock(command) {
+function codeBlock$1(command) {
 	return [
 		"```sh",
 		command,
@@ -698,17 +699,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,12 +721,12 @@ 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) {
@@ -748,7 +749,7 @@ var install_default = { install: { async content(options) {
 		if (hasCli && isLibrary) return [
 			heading,
 			"",
-			"Pick the option that matches how you plan to use it.",
+			`There are several ways to install ${name} depending on how you're planning to use it:`,
 			"",
 			`${subheading} CLI`,
 			"",
@@ -770,10 +771,17 @@ var install_default = { install: { async content(options) {
 	return [
 		heading,
 		"",
-		...codeBlock(command)
+		...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 +907,118 @@ 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 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(repoUrl) {
+	return GITHUB_REPOSITORY_REGEX.exec(repoUrl)?.groups?.slug ?? repoUrl;
+}
+var skills_default = { skills: { async content(options) {
+	const validOptions = z.object({ 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 subheading = getHeadingPrefix(headingLevel + 1);
+	const skillNoun = skills.length === 1 ? "skill" : "skills";
+	const skillPronoun = skills.length === 1 ? "it" : "them";
+	const introLines = [
+		`${getHeadingPrefix(headingLevel)} Agent skills`,
+		"",
+		`This project includes ${skills.length === 1 ? "an [Agent Skill](https://agentskills.io)" : "[Agent Skills](https://agentskills.io)"} that ${skills.length === 1 ? "teaches" : "teach"} coding agents like Claude Code and Codex how to work with ${name}:`,
+		"",
+		...skills.map((skill) => `- **[\`${skill.name}\`](${skill.filePath})**: ${skill.description.replaceAll(WHITESPACE_REGEX, " ")}`)
+	];
+	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 [
+			...introLines,
+			"",
+			`Install ${skillPronoun} from the repository with the [\`skills\`](https://github.com/vercel-labs/skills) CLI:`,
+			"",
+			...codeBlock(`npx skills add ${getSkillsCliSource(repositoryUrl)}`)
+		].join("\n");
+	}
+	return [
+		...introLines,
+		"",
+		`The ${skillNoun} ${skills.length === 1 ? "is" : "are"} published in the \`${SKILLS_DIRECTORY}\` directory of the \`${name}\` package. Nothing is added to your project until you install ${skillPronoun} with one of the tools below.`,
+		"",
+		`${subheading} Sync from the installed package (recommended)`,
+		"",
+		`With \`${name}\` installed as a project dependency, the [\`skills\`](https://github.com/vercel-labs/skills) CLI finds skills bundled in your dependencies and copies them into your project's agent skill directories, so they match the version of \`${name}\` you have installed:`,
+		"",
+		...codeBlock("npx skills experimental_sync"),
+		"",
+		`Run the command again after upgrading \`${name}\` to refresh the copies. The \`experimental_sync\` command is experimental and its behavior may change.`,
+		...repositoryUrl === void 0 ? [] : [
+			"",
+			`${subheading} Install from the repository`,
+			"",
+			`If \`${name}\` is not a dependency of your project, for example because you use a global installation, install the ${skillNoun} from the repository instead:`,
+			"",
+			...codeBlock(`npx skills add ${getSkillsCliSource(repositoryUrl)}`),
+			"",
+			`${skills.length === 1 ? "A skill" : "Skills"} installed this way ${skills.length === 1 ? "follows" : "follow"} the repository's default branch rather than your installed version of \`${name}\`.`
+		]
+	].join("\n");
+} } };
+
 //#endregion
 //#region src/lib/readme/rules/table-of-contents.ts
 var table_of_contents_default = { "table-of-contents": {
@@ -951,10 +1071,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 +1360,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 +1405,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 +1463,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 +1483,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"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "CLI tool and TypeScript library implementing the Markdown Autophagic Template (MDAT) system. MDAT lets you use comments as dynamic content templates in Markdown files, making it easy to generate and update readme boilerplate.",
   "keywords": [
     "mdat",
@@ -40,7 +40,8 @@
     "mdat": "dist/bin/cli.js"
   },
   "files": [
-    "dist/*"
+    "dist/*",
+    "skills/*"
   ],
   "dependencies": {
     "@clack/prompts": "^1.8.1",
@@ -48,13 +49,14 @@
     "cosmiconfig-typescript-loader": "^6.3.0",
     "deepmerge-ts": "^8.0.2",
     "globby": "^16.2.4",
+    "gray-matter-es": "^0.2.1",
     "lognow": "^0.8.4",
     "mdast-util-toc": "^7.1.0",
     "metascope": "^0.12.0",
     "path-type": "^6.0.0",
     "picocolors": "^1.1.1",
     "plur": "^6.0.0",
-    "pretty-bytes": "^7.1.3",
+    "pretty-bytes": "^7.2.0",
     "pretty-ms": "^9.3.1",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
@@ -69,26 +71,26 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.5",
-    "@kitschpatrol/shared-config": "^8.10.0",
+    "@kitschpatrol/shared-config": "^8.10.1",
     "@types/mdast": "^4.0.4",
     "@types/node": "~24.13.6",
     "@types/unist": "^3.0.3",
     "@types/yargs": "^17.0.35",
-    "@vitest/coverage-v8": "^5.0.1",
+    "@vitest/coverage-v8": "^5.0.3",
     "brewpub": "^0.4.0",
     "bumpp": "^12.3.0",
     "execa": "^10.0.1",
-    "mdat-plugin-cli-help": "^3.2.0",
+    "mdat-plugin-cli-help": "^3.3.0",
     "mdat-plugin-example": "^3.0.0",
     "mdat-plugin-tldraw": "^3.0.0",
     "nanoid": "^6.0.1",
-    "prettier": "^3.9.8",
-    "publint": "^0.3.24",
+    "prettier": "^3.9.9",
+    "publint": "^0.3.25",
     "shx": "^0.4.0",
     "tsdown": "^0.23.0",
     "typescript": "~6.0.3",
     "unplugin-raw": "^0.8.0",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.3"
   },
   "peerDependencies": {
     "prettier": "^3.0.0"

package/readme.md

@@ -46,6 +46,9 @@
   - [Installing a rule plugin](#installing-a-rule-plugin)
   - [Creating a rule plugin](#creating-a-rule-plugin)
   - [Available rule plugins](#available-rule-plugins)
+- [Agent skills](#agent-skills)
+  - [Sync from the installed package (recommended)](#sync-from-the-installed-package-recommended)
+  - [Install from the repository](#install-from-the-repository)
 - [Migrating from 1.x to 2.x](#migrating-from-1x-to-2x)
   - [Flat CLI commands](#flat-cli-commands)
   - [Polyglot metadata](#polyglot-metadata)
@@ -124,7 +127,7 @@ Written in TypeScript with bundled type definitions.
 
 ### Installation
 
-Pick the option that matches how you plan to use it.
+There are several ways to install mdat depending on how you're planning to use it:
 
 #### CLI
 
@@ -617,6 +620,8 @@ Every rule that emits a section heading accepts a `headingLevel` option (`1`-`6`
   <!-- install({ headingLevel: 2, dev: true, homebrew: false }) -->
   ```
 
+  Also aliased as `<!-- installation -->`.
+
 - ##### `<!-- dependencies -->`
 
   Documents platform requirements and peer dependencies. Lists runtime platforms (Node, Python, Rust, Go, Ruby, etc.) with version constraints from `engines` or equivalent metadata, supported operating systems, and required peer dependencies with links to npm. Optional peer dependencies are left out. Version ranges are described in plain language (`>=24.16.0` becomes "24.16.0 or newer"), with the exact range included when it can't be summarized that simply. The optional `headingLevel` sets the Markdown heading level and defaults to `3`.
@@ -658,6 +663,10 @@ Every rule that emits a section heading accepts a `headingLevel` option (`1`-`6`
 
   <!-- /size-table -->
 
+- ##### `<!-- skills -->`
+
+  Documents the [Agent Skills](https://agentskills.io) bundled with the project and how to install them. Detects skills from `skills/<name>/SKILL.md` files, and lists each skill's name and description from its frontmatter, linking the name to the skill's `SKILL.md` file. Publishable npm packages get instructions for syncing skills from the installed package with the [`skills`](https://github.com/vercel-labs/skills) CLI's `experimental_sync` command (recommended), and for installing them from the repository with `skills add`. Private packages and non-Node projects only get the repository instructions. Reports an error if no skills are found. Remember to include the `skills` directory in the `files` field of `package.json`. The optional `headingLevel` sets the Markdown heading level and defaults to `2`.
+
 #### Compound
 
 Compound rules combine several stand-alone rules under a single keyword. Options are passed as an array with one entry per stand-alone rule, in order, e.g. `<!-- footer([{ headingLevel: 3 }, { headingLevel: 3 }]) -->`.
@@ -690,6 +699,8 @@ The `create` command provides starter readme templates:
 - **Standard Readme basic** — Only the "required" sections from the [Standard Readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) spec.
 - **Standard Readme full** — All sections from the [Standard Readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) spec.
 
+If the project has agent skills in `skills/<name>/SKILL.md`, a `<!-- skills -->` placeholder is added after the template's "Usage" section.
+
 ## Plugins
 
 Rule plugins are packages for sharing mdat expansion rules across projects.
@@ -756,6 +767,45 @@ Transform a CLI command's `--help` output into Markdown tables. Recursively call
 
 Example: `<!-- cli-help -->`
 
+#### [mdat-plugin-api](https://github.com/kitschpatrol/mdat-plugin-api)
+
+Generate API documentation for a TypeScript package's public exports. Runs [TypeDoc](https://typedoc.org) over the package's entry point and embeds signatures, JSDoc descriptions, parameter and property tables, and examples as Markdown. A compact format renders one table row per export for large or namespaced APIs, and exports can be selected by name.
+
+Example: `<!-- api({ format: "compact", include: ["sync*"] }) -->`
+
+<!-- //skills -->
+
+## Agent skills
+
+This project includes [Agent Skills](https://agentskills.io) that teach coding agents like Claude Code and Codex how to work with mdat:
+
+- **[`mdat`](skills/mdat/SKILL.md)**: Use and configure mdat, the Markdown Autophagic Template CLI and library that expands HTML comment placeholders such as `<!-- title -->` in Markdown files. Use when a readme or other Markdown file contains mdat comment placeholders, when editing mdat.config.ts or an "mdat" key in package.json, when generating or updating readme boilerplate from project metadata, when `mdat check` fails, or when calling the mdat TypeScript API.
+- **[`mdat-plugin-authoring`](skills/mdat-plugin-authoring/SKILL.md)**: Write custom mdat expansion rules and publishable mdat rule plugins (mdat-plugin-\* packages). Use when creating or debugging rule functions for mdat comment placeholders, validating comment arguments, reading project metadata or the Markdown tree inside a rule, building compound rules, or packaging and testing rules for reuse across projects.
+
+The skills are published in the `skills` directory of the `mdat` package. Nothing is added to your project until you install them with one of the tools below.
+
+### Sync from the installed package (recommended)
+
+With `mdat` installed as a project dependency, the [`skills`](https://github.com/vercel-labs/skills) CLI finds skills bundled in your dependencies and copies them into your project's agent skill directories, so they match the version of `mdat` you have installed:
+
+```sh
+npx skills experimental_sync
+```
+
+Run the command again after upgrading `mdat` to refresh the copies. The `experimental_sync` command is experimental and its behavior may change.
+
+### Install from the repository
+
+If `mdat` is not a dependency of your project, for example because you use a global installation, install the skills from the repository instead:
+
+```sh
+npx skills add kitschpatrol/mdat
+```
+
+Skills installed this way follow the repository's default branch rather than your installed version of `mdat`.
+
+<!-- //skills -->
+
 ## Migrating from 1.x to 2.x
 
 The 2.0 version introduces significant breaking changes in the interest of simplicity and a somewhat narrowed scope of concerns.

package/skills/mdat/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: mdat
+description: Use and configure mdat, the Markdown Autophagic Template CLI and library that expands HTML comment placeholders such as `<!-- title -->` in Markdown files. Use when a readme or other Markdown file contains mdat comment placeholders, when editing mdat.config.ts or an "mdat" key in package.json, when generating or updating readme boilerplate from project metadata, when `mdat check` fails, or when calling the mdat TypeScript API.
+license: MIT
+---
+
+# Using mdat
+
+mdat expands HTML comments in Markdown files into generated content. A comment like `<!-- title -->` is a placeholder. Running `mdat` fills it in from a rule and adds a closing tag:
+
+```md
+<!-- title -->
+
+# my-project
+
+<!-- /title -->
+```
+
+The comments stay in the file, so the content can be regenerated whenever the underlying data changes.
+
+## Ground rules
+
+- **Never hand-edit content between an opening tag and its closing tag.** It is overwritten on the next run. Change the comment's arguments, the rule, or the project metadata the rule reads from (e.g. `package.json`), then re-run `mdat`.
+- **Text outside the tags is ordinary Markdown.** Edit it freely.
+- **Re-run `mdat` after any change that affects generated content**, such as editing headings (the table of contents), `package.json` fields, or embedded files. Then confirm with `mdat check`.
+- `mdat` rewrites files in place. Do not run it on files with uncommitted work you cannot recover.
+- To add a placeholder, write only the opening comment. `mdat` adds the closing tag.
+- Comments whose first word is not a known rule keyword are left alone, as are code-style comments like `<!-- // note -->`.
+
+## CLI
+
+If mdat is a project dependency, run it through the package manager (`pnpm mdat`, `npx mdat`). Run `mdat <command> --help` for the full option list.
+
+| Command                 | Effect                                                                                 |
+| ----------------------- | -------------------------------------------------------------------------------------- |
+| `mdat` or `mdat expand` | Expand placeholders. With no files, expands the closest `readme.md`.                   |
+| `mdat check`            | Dry-run. Exits with code 1 if any file has stale or unexpanded content. Good for CI.   |
+| `mdat collapse`         | Remove generated content, leaving only the opening comments.                           |
+| `mdat strip`            | Remove the mdat comments but keep the generated content.                               |
+| `mdat create`           | Create a new readme from a bundled template. Interactive unless `--interactive false`. |
+
+Common options:
+
+- `mdat docs/*.md` processes specific files.
+- `--config a.ts b.json` (`-c`) loads additional rule files. Available on `expand` and `check`.
+- `--format` (`-f`) formats output with Prettier, which must be installed. If the project formats Markdown with Prettier, pass `--format` to both `mdat` and `mdat check` so they agree.
+- `--print` writes to stdout instead of the file.
+- `--output` (`-o`) and `--name` (`-n`) write to a different directory or file name.
+
+## Comment arguments
+
+Arguments use function-call syntax with a single [JSON5](https://json5.org) value. Parentheses are required:
+
+```md
+<!-- install({ headingLevel: 2, dev: true }) -->
+```
+
+Only JSON5 values are accepted. No JavaScript is evaluated. Bundled rules validate their arguments and report an error on unknown shapes.
+
+## Bundled rules
+
+These work without any configuration. They read normalized project metadata, so most also work in Python, Rust, Go, and Ruby projects, not only Node.
+
+| Keyword                                               | Output                                                                            | Options                                                    |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `title`                                               | Project name as a heading.                                                        |                                                            |
+| `banner`                                              | A banner image found in the project directory.                                    |                                                            |
+| `badges`                                              | npm version, license, CI status, and Git LFS badges.                              | `npm: string[]`, `custom: { [name]: { image, link } }`     |
+| `description` (alias `short-description`)             | Project description.                                                              |                                                            |
+| `table-of-contents` (alias `toc`)                     | Table of contents from the document headings.                                     | `depth` (default `3`), `headingLevel` (default `2`)        |
+| `install` (alias `installation`)                      | Install instructions for consumers of the package. Private packages are rejected. | `headingLevel` (default `3`), `dev`, `homebrew`            |
+| `dependencies`                                        | Runtime platform requirements and required peer dependencies.                     | `headingLevel` (default `3`)                               |
+| `development-dependencies` (alias `dev-dependencies`) | Tools needed to work on the project, from `devEngines` and `packageManager`.      | `headingLevel` (default `3`)                               |
+| `contributing`                                        | Invitation to open issues and pull requests.                                      | `headingLevel` (default `2`)                               |
+| `license`                                             | License section.                                                                  | `headingLevel` (default `2`)                               |
+| `code`                                                | A code block embedded from a file.                                                | `file` (required), `language`, `trim` (default `true`)     |
+| `size`                                                | A file's size.                                                                    | `file` (required), `compression`: `none`, `gzip`, `brotli` |
+| `size-table`                                          | A table of file sizes with Gzip and Brotli columns.                               | `files` (required), `precision` (default `0`)              |
+| `skills`                                              | Agent Skills found in `skills/<name>/SKILL.md` and how to install them.           | `headingLevel` (default `2`)                               |
+| `header`                                              | Compound: `title`, `banner`, `badges`, `short-description`.                       | Array, one entry per sub-rule in order.                    |
+| `footer`                                              | Compound: `contributing`, `license`.                                              | Array, one entry per sub-rule in order.                    |
+
+File paths in `code`, `size`, and `size-table` resolve from the current working directory.
+
+## Configuration
+
+Custom rules live in a config file found by [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig). `mdat.config.ts` in the project root is the usual choice. The file default-exports a record whose keys become comment keywords:
+
+```ts
+import { defineConfig } from 'mdat'
+
+export default defineConfig({
+  // Object form: adds processing order
+  date: {
+    content: () => new Date().toISOString(),
+    order: 1,
+  },
+  // String: static replacement
+  greeting: 'Hello, world!',
+  // Function: sync or async, receives the comment's arguments, e.g. <!-- repeat(3) -->
+  repeat: (options) => 'ha'.repeat(Number(options)),
+})
+```
+
+- A rule must return non-empty Markdown. Empty content and thrown errors are reported as errors.
+- Custom rules merge with the bundled rules. A custom rule with the same keyword as a bundled rule replaces it.
+- With multiple config files, the last rule for a keyword wins, and `--config` files take precedence over discovered config.
+- JSON files work as rule sets. Nested keys are flattened into dot-notated keywords, so `{ "a": { "b": "x" } }` provides `<!-- a.b -->`.
+- `package.json` can hold rules under an `"mdat"` key, or name a shared config package: `"mdat": "@scope/mdat-config"`.
+- Rules from a plugin package are spread into the config: `defineConfig({ ...examplePlugin })`.
+
+For rules that take validated arguments, read the document tree, or are shared across projects, use the `mdat-plugin-authoring` skill if it is available.
+
+## Library API
+
+```ts
+import { check, expand, expandString } from 'mdat'
+import { write } from 'to-vfile'
+
+// Returns VFiles. Writing is the caller's responsibility.
+const [file] = await expand('readme.md')
+await write(file)
+
+const result = await expandString('<!-- title -->')
+console.log(result.toString())
+```
+
+- `expand`, `collapse`, `strip`, and `check` take file paths. With no files they find the closest readme.
+- `expandString`, `collapseString`, `stripString`, and `checkString` take Markdown strings.
+- `create` and `createInteractive` create a readme from a bundled template.
+- `loadConfig` discovers and merges config. `defineConfig` and `mergeConfig` build config objects.
+
+## Troubleshooting
+
+- **A comment is not expanding.** The keyword does not match a loaded rule. Check spelling, confirm the config file is discovered or passed with `--config`, and run with `--verbose`.
+- **`mdat check` fails.** Run `mdat` (with `--format` if the check used it) and commit the result. If it still fails, the rule output is non-deterministic, e.g. a timestamp.
+- **Arguments are ignored or rejected.** Use parentheses: `<!-- keyword({ key: "value" }) -->`. The 1.x form without parentheses is no longer supported.
+- **Old commands.** `mdat readme` is now `mdat`, `mdat readme init` is `mdat create`, and `mdat readme check` is `mdat check`. The `--rules`, `--assets`, `--package`, `--meta`, and `--prefix` options were removed in favor of `--config`.

package/skills/mdat-plugin-authoring/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: mdat-plugin-authoring
+description: Write custom mdat expansion rules and publishable mdat rule plugins (mdat-plugin-* packages). Use when creating or debugging rule functions for mdat comment placeholders, validating comment arguments, reading project metadata or the Markdown tree inside a rule, building compound rules, or packaging and testing rules for reuse across projects.
+license: MIT
+---
+
+# Authoring mdat rules and plugins
+
+An mdat rule maps a comment keyword to generated Markdown. A rule plugin is an npm package whose default export is a record of rules. Start with a rule in the project's `mdat.config.ts`. Move it to a plugin package only when more than one project needs it.
+
+## Rule shapes
+
+```ts
+import type { Config } from 'mdat'
+
+export default {
+  // String: static replacement for <!-- greeting -->
+  greeting: 'Hello, world!',
+  // Array: compound rule, each entry is itself a rule
+  intro: ['# My Project', () => 'Generated description.'],
+  // Object: adds processing order
+  summary: {
+    content: (_options, context) => `Source: ${context.filePath ?? 'unknown'}`,
+    order: 1,
+  },
+  // Function: sync or async
+  time: () => new Date().toDateString(),
+} satisfies Config
+```
+
+The full signature of a content function:
+
+```ts
+type Content = (options: JsonValue, context: RuleContext) => Promise<string> | string
+
+type RuleContext = {
+  /** File path of the source document, if known. */
+  filePath: string | undefined
+  /** Parsed YAML frontmatter from the document, if present. */
+  frontmatter: Record<string, unknown> | undefined
+  /** The full mdast tree of the document. Do not mutate. */
+  tree: Root
+}
+```
+
+## Requirements for a rule
+
+- **Return a non-empty Markdown string.** Empty output is reported as an error. If there is nothing to output, throw an error that says why.
+- **Be deterministic.** `mdat check` compares a fresh expansion against the file on disk, so timestamps, random values, and unstable ordering make the check fail on every run.
+- **Fail with a clear message.** Thrown errors are reported against the comment that triggered them. Include what was missing and how to fix it.
+- **Resolve relative paths deliberately.** The bundled rules resolve file arguments from `process.cwd()`. Use `context.filePath` to resolve relative to the document instead.
+- **Do not include the comment tags in the output.** mdat adds the opening and closing tags.
+
+## Keywords
+
+A keyword consists of letters, numbers, `_`, `$`, `-`, and `.`, and cannot start with `/`, `*`, `#`, `-`, or `.`. Prefer kebab-case, e.g. `cli-help`. Pick a specific keyword. A rule with the same keyword as a bundled rule (`title`, `badges`, `install`, `license`, and so on) replaces it.
+
+## Arguments
+
+A comment passes a single JSON5 value: `<!-- keyword({ file: "./a.ts", trim: false }) -->`. A comment without parentheses passes `{}`. Arguments are untrusted input, so validate them. The bundled rules use [Zod](https://zod.dev):
+
+```ts
+import type { Config } from 'mdat'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { z } from 'zod'
+
+const optionsSchema = z.object({
+  file: z.string(),
+  language: z.string().optional(),
+})
+
+export default {
+  embed: {
+    async content(options) {
+      const { file, language } = optionsSchema.parse(options)
+      const code = await fs.readFile(path.join(process.cwd(), file), 'utf8')
+      return `\`\`\`${language ?? path.extname(file).slice(1)}\n${code.trim()}\n\`\`\``
+    },
+  },
+} satisfies Config
+```
+
+Prefer an object argument over a bare primitive so options can be added later without breaking existing comments.
+
+## Project metadata
+
+mdat exports helpers so rules do not need to parse `package.json` themselves. Both are memoized and work across ecosystems (Node, Python, Rust, Go, Ruby) via [metascope](https://github.com/kitschpatrol/metascope):
+
+```ts
+import { getContextMetadata, getReadmeMetadata } from 'mdat'
+
+// Normalized fields the bundled readme rules use, e.g. name, description,
+// repositoryUrl, issuesUrl, license, author, bin, engines, peerDependencies.
+// Any field may be undefined.
+const { name, repositoryUrl } = await getReadmeMetadata()
+
+// The full metascope metadata context for anything not covered above.
+const metadata = await getContextMetadata()
+```
+
+See the exported `ReadmeMetadata` type for the complete field list. Call `resetMetadataCaches()` between tests that change project files on disk.
+
+## Order and compound rules
+
+- `order` defaults to `0`. Rules with a higher order run later. Use it when a rule reads content other rules generate. The bundled `table-of-contents` rule uses `order: 1` so that it sees headings produced by other rules.
+- A compound rule is an array of rules whose output is joined under one keyword. Its comment takes an array of arguments, one entry per sub-rule in order: `<!-- footer([{ headingLevel: 3 }, { headingLevel: 3 }]) -->`.
+- To reuse a rule from another single-rule record inside a compound rule, use `getSoleRule` from `remark-mdat`.
+
+## Packaging a plugin
+
+- Name the package with the `mdat-plugin-` prefix and add the `mdat-plugin` keyword.
+- Publish ESM with a default export of the rule record, typed with `satisfies Config`.
+- Declare `mdat` as a peer dependency, and as a dev dependency for tests.
+- One package may export several related rules.
+
+```json
+{
+  "name": "mdat-plugin-example",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": ["mdat", "mdat-plugin"],
+  "peerDependencies": {
+    "mdat": "^3.0.0"
+  }
+}
+```
+
+Consumers spread the plugin into their config:
+
+```ts
+import { defineConfig } from 'mdat'
+import example from 'mdat-plugin-example'
+
+export default defineConfig({ ...example })
+```
+
+[mdat-plugin-example](https://github.com/kitschpatrol/mdat-plugin-example) is a minimal template repository. [mdat-plugin-cli-help](https://github.com/kitschpatrol/mdat-plugin-cli-help) and [mdat-plugin-tldraw](https://github.com/kitschpatrol/mdat-plugin-tldraw) are fuller examples with arguments and file output.
+
+## Testing
+
+Test rules through the public API with `expandString`, passing the rule record as config:
+
+```ts
+import { expandString } from 'mdat'
+import { expect, it } from 'vitest'
+import plugin from '../src/index'
+
+it('expands the example rule', async () => {
+  const result = await expandString('<!-- example -->', plugin)
+  expect(result.toString()).toContain('Hello from')
+  expect(result.messages.filter((message) => message.fatal)).toHaveLength(0)
+})
+
+it('is stable across runs', async () => {
+  const first = await expandString('<!-- example -->', plugin)
+  const second = await expandString(first.toString(), plugin)
+  expect(second.toString()).toEqual(first.toString())
+})
+```
+
+Also cover invalid arguments. Rule errors are not thrown. They are reported as messages on the returned VFile with `fatal: true`, alongside informational messages for each successful expansion, so assert on the fatal messages in `result.messages`.
+
+To try a rule file against a real document without touching it, run `mdat --config ./my-rules.ts --print some-file.md`.