@santi020k/eslint-config-basic 1.6.0 → 2.0.0-beta.1

package/dist/agent-skill-generator.js

@@ -4,53 +4,81 @@ import { pathToFileURL } from "node:url";
 import { detectProjectOptions } from "./index.js";
 const AGENT_TARGETS = [
   {
+    format: "frontmatter",
     label: ".agent (generic skill format)",
     markerFolder: ".agent",
-    skillSubdir: "skills",
     skillFile: "eslint-standards.md",
-    format: "frontmatter"
+    skillSubdir: "skills"
   },
   {
+    format: "frontmatter",
     label: ".agents (generic skill format)",
     markerFolder: ".agents",
-    skillSubdir: "skills",
     skillFile: "eslint-standards.md",
-    format: "frontmatter"
+    skillSubdir: "skills"
   },
   {
+    format: "plain",
     label: "Claude Code (.claude/commands)",
     markerFolder: ".claude",
-    skillSubdir: "commands",
     skillFile: "eslint.md",
-    format: "plain"
+    skillSubdir: "commands"
   },
   {
+    format: "cursor",
     label: "Cursor (.cursor/rules)",
     markerFolder: ".cursor",
-    skillSubdir: "rules",
     skillFile: "eslint-standards.mdc",
-    format: "cursor"
+    skillSubdir: "rules"
   },
   {
+    format: "frontmatter",
     label: "Windsurf (.windsurf/rules)",
     markerFolder: ".windsurf",
-    skillSubdir: "rules",
     skillFile: "eslint-standards.md",
-    format: "frontmatter"
+    skillSubdir: "rules"
   },
   {
+    format: "plain",
     label: "Copilot (.copilot)",
     markerFolder: ".copilot",
-    skillSubdir: "instructions",
     skillFile: "eslint-standards.md",
-    format: "plain"
+    skillSubdir: "instructions"
   },
   {
+    format: "plain",
     label: "Aider (.aider)",
     markerFolder: ".aider",
-    skillSubdir: ".",
     skillFile: "eslint-standards.md",
-    format: "plain"
+    skillSubdir: "."
+  },
+  {
+    format: "plain",
+    label: "Gemini (.gemini)",
+    markerFolder: ".gemini",
+    skillFile: "styleguide.md",
+    skillSubdir: "."
+  },
+  {
+    format: "plain",
+    label: "Cline (.clinerules)",
+    markerFolder: ".clinerules",
+    skillFile: "eslint-standards.md",
+    skillSubdir: "."
+  },
+  {
+    format: "plain",
+    label: "Roo Code (.roo/rules)",
+    markerFolder: ".roo",
+    skillFile: "eslint-standards.md",
+    skillSubdir: "rules"
+  },
+  {
+    format: "kiro",
+    label: "Kiro (.kiro/steering)",
+    markerFolder: ".kiro",
+    skillFile: "eslint-standards.md",
+    skillSubdir: "steering"
   }
 ];
 const FEATURE_MAP = [
@@ -68,85 +96,141 @@ const FEATURE_MAP = [
   ["eslint-config-hono/", "frameworks", "Hono"],
   ["eslint-config-expo/", "frameworks", "Expo"],
   ["eslint-config-qwik/", "frameworks", "Qwik"],
+  ["eslint-config-react-router/", "frameworks", "React Router"],
   ["eslint-config-remix/", "frameworks", "Remix"],
   ["eslint-config-solid/", "frameworks", "SolidJS"],
+  ["eslint-config-nuxt/", "frameworks", "Nuxt"],
+  ["eslint-config-lit/", "frameworks", "Lit"],
+  ["eslint-config-tanstack-start/", "frameworks", "TanStack Start"],
+  ["eslint-config-preact/", "frameworks", "Preact"],
+  ["eslint-config-slidev/", "frameworks", "Slidev"],
+  ["eslint-config-vite/", "frameworks", "Vite"],
   // Testing
-  ["optionals/vitest", "testing", "Vitest"],
-  ["optionals/jest", "testing", "Jest"],
-  ["optionals/playwright", "testing", "Playwright"],
-  ["optionals/cypress", "testing", "Cypress"],
-  ["optionals/testing-library", "testing", "Testing Library"],
+  ["integrations/vitest", "testing", "Vitest"],
+  ["integrations/jest", "testing", "Jest"],
+  ["eslint-config-integrations/jest-dom", "testing", "Jest DOM"],
+  ["integrations/playwright", "testing", "Playwright"],
+  ["integrations/cypress", "testing", "Cypress"],
+  ["integrations/testing-library", "testing", "Testing Library"],
   // Tools
   ["eslint-config/prettier", "tools", "Prettier"],
-  ["optionals/cspell", "tools", "CSpell"],
-  ["eslint-config-optionals/jsdoc", "tools", "JSDoc"],
-  ["optionals/swagger", "tools", "Swagger"],
+  ["integrations/cspell", "tools", "CSpell"],
+  ["eslint-config-integrations/jsdoc", "tools", "JSDoc"],
+  ["integrations/swagger", "tools", "Swagger"],
+  ["eslint-config-integrations/command", "tools", "Command"],
+  ["eslint-config-integrations/docker", "tools", "Docker"],
+  ["eslint-config-integrations/github-actions", "tools", "GitHub Actions"],
+  ["eslint-config-integrations/nx", "tools", "Nx"],
+  ["integrations/pnpm/", "tools", "pnpm"],
   // Libraries
+  ["eslint-config-integrations/ai-sdk", "libraries", "AI SDK"],
+  ["eslint-config-integrations/mcp", "libraries", "MCP"],
+  ["eslint-config-integrations/mastra", "libraries", "Mastra"],
+  ["eslint-config-integrations/openai-agents", "libraries", "OpenAI Agents"],
+  ["eslint-config-integrations/langchain", "libraries", "LangChain"],
+  ["eslint-config-integrations/llamaindex", "libraries", "LlamaIndex"],
   ["santi020k/tailwind/", "libraries", "Tailwind CSS"],
-  ["optionals/i18next", "libraries", "i18next"],
-  ["optionals/stencil", "libraries", "Stencil"],
-  ["optionals/storybook", "libraries", "Storybook"],
-  ["eslint-config-optionals/tanstack-query", "libraries", "TanStack Query"],
-  ["eslint-config-optionals/tanstack-router", "libraries", "TanStack Router"],
+  ["integrations/i18next", "libraries", "i18next"],
+  ["integrations/stencil", "libraries", "Stencil"],
+  ["storybook:recommended", "libraries", "Storybook"],
+  ["eslint-config-integrations/tanstack-query", "libraries", "TanStack Query"],
+  ["eslint-config-integrations/tanstack-router", "libraries", "TanStack Router"],
+  ["eslint-config-integrations/autogen", "libraries", "Autogen"],
+  ["eslint-config-integrations/google-genai", "libraries", "Google GenAI"],
+  ["eslint-config-integrations/drizzle", "libraries", "Drizzle ORM"],
+  ["eslint-config-integrations/prisma", "libraries", "Prisma"],
+  ["eslint-config-integrations/typeorm", "libraries", "TypeORM"],
+  ["eslint-config-integrations/mikro-orm", "libraries", "MikroORM"],
+  ["eslint-config-integrations/sequelize", "libraries", "Sequelize"],
+  ["eslint-config-integrations/zod", "libraries", "Zod"],
+  ["eslint-config-turbo/", "libraries", "Turbo"],
   // Formats
-  ["optionals/graphql/", "formats", "GraphQL"],
-  ["optionals/yaml/", "formats", "YAML"],
-  ["optionals/jsonc/", "formats", "JSONC"],
-  ["optionals/markdown", "formats", "Markdown"],
+  ["integrations/css/", "formats", "CSS"],
+  ["integrations/html/", "formats", "HTML"],
+  ["eslint-config-integrations/package-json", "formats", "Package JSON"],
+  ["integrations/graphql/", "formats", "GraphQL"],
+  ["integrations/yaml/", "formats", "YAML"],
+  ["integrations/jsonc/", "formats", "JSONC"],
+  ["integrations/markdown", "formats", "Markdown"],
   ["eslint-config-mdx/", "formats", "MDX"],
-  ["optionals/toml/", "formats", "TOML"],
+  ["integrations/toml/", "formats", "TOML"],
   // Extensions
   ["eslint-config/unicorn", "extensions", "Unicorn"],
   ["eslint-config/sonarjs", "extensions", "SonarJS"],
-  ["eslint-config-optionals/security", "extensions", "Security"],
-  ["eslint-config-optionals/perfectionist", "extensions", "Perfectionist"],
-  ["optionals/regexp", "extensions", "Regexp"],
-  ["eslint-config/best-practices", "extensions", "Best Practices"]
+  ["eslint-config-integrations/security", "extensions", "Security"],
+  ["eslint-config-integrations/perfectionist", "extensions", "Perfectionist"],
+  ["integrations/regexp", "extensions", "Regexp"],
+  ["eslint-config/best-practices", "extensions", "Best Practices"],
+  ["eslint-config-integrations/a11y/", "extensions", "Accessibility (a11y)"],
+  ["eslint-config-integrations/biome", "extensions", "Biome"],
+  ["eslint-config-integrations/import-boundaries", "extensions", "Import Boundaries"],
+  ["integrations/compat/", "extensions", "Browser Compat"],
+  ["integrations/de-morgan/", "extensions", "De Morgan"],
+  ["integrations/depend/", "extensions", "Depend"],
+  ["integrations/node/", "extensions", "Node.js"],
+  ["eslint-config-integrations/no-only-tests", "extensions", "No Only Tests"],
+  ["integrations/oxlint", "extensions", "Oxlint"]
 ];
-const DETECTED_FRAMEWORK_LABELS = {
-  angular: "Angular",
-  astro: "Astro",
-  expo: "Expo",
-  hono: "Hono",
-  nest: "NestJS",
-  next: "Next.js",
-  qwik: "Qwik",
-  react: "React",
-  remix: "Remix",
-  solid: "SolidJS",
-  svelte: "Svelte",
-  vue: "Vue"
-};
-const FEATURE_LABELS = {
-  "best-practices": "Best Practices",
-  cspell: "CSpell",
-  cypress: "Cypress",
-  graphql: "GraphQL",
-  i18next: "i18next",
-  jest: "Jest",
-  jsdoc: "JSDoc",
-  jsonc: "JSONC",
-  markdown: "Markdown",
-  mdx: "MDX",
-  perfectionist: "Perfectionist",
-  playwright: "Playwright",
-  prettier: "Prettier",
-  regexp: "Regexp",
-  security: "Security",
-  sonarjs: "SonarJS",
-  stencil: "Stencil",
-  storybook: "Storybook",
-  swagger: "Swagger",
-  tailwind: "Tailwind CSS",
-  "tanstack-query": "TanStack Query",
-  "tanstack-router": "TanStack Router",
-  "testing-library": "Testing Library",
-  toml: "TOML",
-  unicorn: "Unicorn",
-  vitest: "Vitest",
-  yaml: "YAML"
-};
-const toFeatureLabel = (value) => FEATURE_LABELS[value] ?? value;
+const DETECTED_FRAMEWORK_LABELS = /* @__PURE__ */ new Map([
+  ["angular", "Angular"],
+  ["astro", "Astro"],
+  ["expo", "Expo"],
+  ["hono", "Hono"],
+  ["lit", "Lit"],
+  ["nest", "NestJS"],
+  ["next", "Next.js"],
+  ["nuxt", "Nuxt"],
+  ["preact", "Preact"],
+  ["qwik", "Qwik"],
+  ["react", "React"],
+  ["react-router", "React Router"],
+  ["remix", "Remix"],
+  ["slidev", "Slidev"],
+  ["solid", "SolidJS"],
+  ["svelte", "Svelte"],
+  ["tanstack-start", "TanStack Start"],
+  ["vite", "Vite"],
+  ["vue", "Vue"]
+]);
+const FEATURE_LABELS = /* @__PURE__ */ new Map([
+  ["best-practices", "Best Practices"],
+  ["compat", "Browser Compat"],
+  ["cspell", "CSpell"],
+  ["css", "CSS"],
+  ["cypress", "Cypress"],
+  ["de-morgan", "De Morgan"],
+  ["depend", "Depend"],
+  ["graphql", "GraphQL"],
+  ["html", "HTML"],
+  ["i18next", "i18next"],
+  ["jest", "Jest"],
+  ["jsdoc", "JSDoc"],
+  ["jsonc", "JSONC"],
+  ["markdown", "Markdown"],
+  ["mdx", "MDX"],
+  ["node", "Node.js"],
+  ["oxlint", "Oxlint"],
+  ["perfectionist", "Perfectionist"],
+  ["playwright", "Playwright"],
+  ["pnpm", "pnpm"],
+  ["prettier", "Prettier"],
+  ["regexp", "Regexp"],
+  ["security", "Security"],
+  ["sonarjs", "SonarJS"],
+  ["stencil", "Stencil"],
+  ["storybook", "Storybook"],
+  ["swagger", "Swagger"],
+  ["tailwind", "Tailwind CSS"],
+  ["tanstack-query", "TanStack Query"],
+  ["tanstack-router", "TanStack Router"],
+  ["testing-library", "Testing Library"],
+  ["toml", "TOML"],
+  ["unicorn", "Unicorn"],
+  ["vitest", "Vitest"],
+  ["yaml", "YAML"]
+]);
+const toFeatureLabel = (value) => FEATURE_LABELS.get(value) ?? value;
+const extractRuleNamespaces = (rules) => Object.keys(rules).filter((key) => key.includes("/")).map((key) => key.slice(0, key.indexOf("/")));
 const collectTokens = (configs) => {
   const tokens = [];
   for (const entry of configs) {
@@ -159,27 +243,50 @@ const collectTokens = (configs) => {
       tokens.push(...Object.keys(cfg.plugins));
     }
     if (cfg.rules && typeof cfg.rules === "object") {
-      for (const key of Object.keys(cfg.rules)) {
-        const slash = key.indexOf("/");
-        if (slash > -1) tokens.push(key.slice(0, slash));
-      }
+      tokens.push(...extractRuleNamespaces(cfg.rules));
     }
   }
   return tokens;
 };
+const recordFeature = (features, category, label) => {
+  if (category === "typescript") {
+    features.typescript = true;
+    return;
+  }
+  switch (category) {
+    case "extensions":
+      features.extensions.push(label);
+      break;
+    case "formats":
+      features.formats.push(label);
+      break;
+    case "frameworks":
+      features.frameworks.push(label);
+      break;
+    case "libraries":
+      features.libraries.push(label);
+      break;
+    case "testing":
+      features.testing.push(label);
+      break;
+    case "tools":
+      features.tools.push(label);
+      break;
+  }
+};
 const extractFeatures = (configs, lintCommand, configFile) => {
   const tokens = collectTokens(configs);
   const features = {
-    typescript: false,
+    configFile,
+    extensions: [],
+    formats: [],
     frameworks: [],
-    testing: [],
-    tools: [],
     libraries: [],
-    formats: [],
-    extensions: [],
     lintCommand,
-    configFile,
-    source: "config-file"
+    source: "config-file",
+    testing: [],
+    tools: [],
+    typescript: false
   };
   const seen = /* @__PURE__ */ new Set();
   for (const [pattern, category, label] of FEATURE_MAP) {
@@ -187,11 +294,7 @@ const extractFeatures = (configs, lintCommand, configFile) => {
     const matched = tokens.some((t) => t.includes(pattern));
     if (!matched) continue;
     seen.add(label);
-    if (category === "typescript") {
-      features.typescript = true;
-    } else {
-      features[category].push(label);
-    }
+    recordFeature(features, category, label);
   }
   return features;
 };
@@ -243,42 +346,36 @@ const analyzeEslintConfig = async (cwd) => {
 const featuresFromDetection = (cwd) => {
   const opts = detectProjectOptions(cwd);
   const lintCommand = detectLintCommand(cwd);
-  const frameworks = (opts.detectedFrameworks ?? []).map((f) => DETECTED_FRAMEWORK_LABELS[f] ?? f);
+  const frameworks = (opts.detectedFrameworks ?? []).map((f) => DETECTED_FRAMEWORK_LABELS.get(f) ?? f);
   return {
-    typescript: opts.typescript === true,
+    configFile: null,
+    extensions: (opts.extensions ?? []).map(toFeatureLabel),
+    formats: (opts.formats ?? []).map(toFeatureLabel),
     frameworks,
-    testing: (opts.testing ?? []).map(toFeatureLabel),
-    tools: (opts.tools ?? []).map(toFeatureLabel),
     libraries: (opts.libraries ?? []).map(toFeatureLabel),
-    formats: (opts.formats ?? []).map(toFeatureLabel),
-    extensions: (opts.extensions ?? []).map(toFeatureLabel),
     lintCommand,
-    configFile: null,
-    source: "detection-fallback"
+    source: "detection-fallback",
+    testing: (opts.testing ?? []).map(toFeatureLabel),
+    tools: (opts.tools ?? []).map(toFeatureLabel),
+    typescript: opts.typescript === true
   };
 };
-const generateSkillContent = (features, format) => {
-  const { typescript, frameworks, testing, tools, libraries, formats, extensions, lintCommand } = features;
-  const summaryLines = [];
-  summaryLines.push(`- **TypeScript**: ${typescript ? "enabled" : "disabled"}`);
-  if (frameworks.length > 0) summaryLines.push(`- **Frameworks**: ${frameworks.join(", ")}`);
-  if (testing.length > 0) summaryLines.push(`- **Testing**: ${testing.join(", ")}`);
-  if (tools.length > 0) summaryLines.push(`- **Tools**: ${tools.join(", ")}`);
-  if (libraries.length > 0) summaryLines.push(`- **Libraries**: ${libraries.join(", ")}`);
-  if (formats.length > 0) summaryLines.push(`- **Formats**: ${formats.join(", ")}`);
-  if (extensions.length > 0) summaryLines.push(`- **Extensions**: ${extensions.join(", ")}`);
-  const tsSection = typescript ? `
-### TypeScript
-
-- Use explicit type annotations on all exported functions and values
-- Use \`import type\` for type-only imports
-- Avoid \`any\` \u2014 prefer \`unknown\` with type guards
-- Prefer \`const\` over \`let\` whenever the binding is not reassigned
-- Return types must be explicit on exported functions
-` : "";
-  const frameworkSections = [];
+const buildSummaryLines = (features) => {
+  const { extensions, formats, frameworks, libraries, testing, tools, typescript } = features;
+  const lines = [];
+  lines.push(`- **TypeScript**: ${typescript ? "enabled" : "disabled"}`);
+  if (frameworks.length > 0) lines.push(`- **Frameworks**: ${frameworks.join(", ")}`);
+  if (testing.length > 0) lines.push(`- **Testing**: ${testing.join(", ")}`);
+  if (tools.length > 0) lines.push(`- **Tools**: ${tools.join(", ")}`);
+  if (libraries.length > 0) lines.push(`- **Libraries**: ${libraries.join(", ")}`);
+  if (formats.length > 0) lines.push(`- **Formats**: ${formats.join(", ")}`);
+  if (extensions.length > 0) lines.push(`- **Extensions**: ${extensions.join(", ")}`);
+  return lines;
+};
+const buildFrameworkSections = (frameworks) => {
+  const sections = [];
   if (frameworks.some((f) => f === "React" || f === "Next.js")) {
-    frameworkSections.push(`
+    sections.push(`
 ### React / JSX
 
 - Prefer function components over class components
@@ -288,7 +385,7 @@ const generateSkillContent = (features, format) => {
 `);
   }
   if (frameworks.includes("Next.js")) {
-    frameworkSections.push(`
+    sections.push(`
 ### Next.js
 
 - Follow App Router conventions (Server Components by default, \`"use client"\` when needed)
@@ -297,7 +394,7 @@ const generateSkillContent = (features, format) => {
 `);
   }
   if (frameworks.includes("Vue")) {
-    frameworkSections.push(`
+    sections.push(`
 ### Vue
 
 - Prefer Composition API (\`<script setup>\`) over Options API
@@ -305,14 +402,14 @@ const generateSkillContent = (features, format) => {
 `);
   }
   if (frameworks.includes("Svelte")) {
-    frameworkSections.push(`
+    sections.push(`
 ### Svelte
 
 - Virtual \`*.svelte/*.ts\` files are handled by the ESLint config \u2014 do not manually adjust \`allowDefaultProject\`
 `);
   }
   if (frameworks.includes("Astro")) {
-    frameworkSections.push(`
+    sections.push(`
 ### Astro
 
 - Virtual \`*.astro/*.ts\` files are handled by the ESLint config
@@ -320,13 +417,67 @@ const generateSkillContent = (features, format) => {
 `);
   }
   if (frameworks.includes("Angular")) {
-    frameworkSections.push(`
+    sections.push(`
 ### Angular
 
 - Follow the Angular style guide component, directive, and service naming conventions
 - Use standalone components by default; avoid NgModule unless required
 `);
   }
+  return sections;
+};
+const wrapWithFormat = (body, format) => {
+  if (format === "frontmatter") {
+    return `---
+name: eslint-standards
+description: >
+  Code quality standards enforced by @santi020k/eslint-config-basic. Follow these
+  conventions whenever writing or editing code in this project.
+trigger: always_on
+---
+
+${body}`;
+  }
+  if (format === "cursor") {
+    return `---
+description: >
+  ESLint code standards for this project. Apply these conventions when writing
+  or editing any source file.
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.vue"
+  - "**/*.svelte"
+  - "**/*.astro"
+alwaysApply: true
+---
+
+${body}`;
+  }
+  if (format === "kiro") {
+    return `---
+inclusion: always
+---
+
+${body}`;
+  }
+  return body;
+};
+const generateSkillContent = (features, format) => {
+  const { frameworks, libraries, lintCommand, testing, tools, typescript } = features;
+  const summaryLines = buildSummaryLines(features);
+  const tsSection = typescript ? `
+### TypeScript
+
+- Use explicit type annotations on all exported functions and values
+- Use \`import type\` for type-only imports
+- Avoid \`any\` \u2014 prefer \`unknown\` with type guards
+- Prefer \`const\` over \`let\` whenever the binding is not reassigned
+- Return types must be explicit on exported functions
+` : "";
+  const frameworkSections = buildFrameworkSections(frameworks);
   const testingSections = [];
   if (testing.some((t) => t === "Vitest" || t === "Jest")) {
     testingSections.push(`
@@ -364,7 +515,8 @@ const generateSkillContent = (features, format) => {
   }
   const body = `# ESLint Code Standards
 
-This project uses [\`@santi020k/eslint-config-basic\`](https://github.com/santi020k/eslint-config-basic) \u2014 a composable ESLint 9/10+ Flat Config package.
+This project uses [\`@santi020k/eslint-config-basic\`](https://github.com/santi020k/eslint-config-basic) \u2014
+a composable ESLint 10+ Flat Config package.
 
 **Always run \`${lintCommand}\` to validate your changes before finishing any task.**
 
@@ -376,7 +528,7 @@ ${summaryLines.join("\n")}
 ${tsSection}${frameworkSections.join("")}${testingSections.join("")}${toolSections.join("")}
 ### General
 
-- ESLint 9/10 **Flat Config** format only \u2014 no \`.eslintrc\` files
+- ESLint 10 **Flat Config** format only \u2014 no \`.eslintrc\` files
 - Use \`.js\` extensions on relative imports (ESM requirement)
 - Use \`type\` imports for type-only values; regular imports for runtime values
 
@@ -392,36 +544,7 @@ If the command is unavailable, fall back to:
 npx eslint .
 \`\`\`
 `;
-  if (format === "frontmatter") {
-    return `---
-name: eslint-standards
-description: >
-  Code quality standards enforced by @santi020k/eslint-config-basic. Follow these
-  conventions whenever writing or editing code in this project.
-trigger: always_on
----
-
-${body}`;
-  }
-  if (format === "cursor") {
-    return `---
-description: >
-  ESLint code standards for this project. Apply these conventions when writing
-  or editing any source file.
-globs:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.js"
-  - "**/*.jsx"
-  - "**/*.vue"
-  - "**/*.svelte"
-  - "**/*.astro"
-alwaysApply: true
----
-
-${body}`;
-  }
-  return body;
+  return wrapWithFormat(body, format);
 };
 const writeSkillFile = (filePath, content, force) => {
   if (existsSync(filePath) && !force) return false;
@@ -430,70 +553,107 @@ const writeSkillFile = (filePath, content, force) => {
   return true;
 };
 const COPILOT_INSTRUCTIONS_PATH = ".github/copilot-instructions.md";
+const AGENTS_MD_PATH = "AGENTS.md";
 const COPILOT_SECTION_START = "<!-- eslint-standards:start -->";
 const COPILOT_SECTION_END = "<!-- eslint-standards:end -->";
-const handleCopilotInstructions = (cwd, body, force) => {
-  const filePath = join(cwd, COPILOT_INSTRUCTIONS_PATH);
-  if (!existsSync(filePath)) return null;
+const buildGuardedSection = (body) => `${COPILOT_SECTION_START}
+${body}
+${COPILOT_SECTION_END}`;
+const handleGuardedSectionFile = (filePath, body, force, check, createIfMissing = false) => {
+  const section = buildGuardedSection(body);
+  if (!existsSync(filePath)) {
+    if (!createIfMissing || check) return null;
+    writeFileSync(filePath, `# Agent instructions
+
+${section}
+`, "utf-8");
+    return "written";
+  }
   const existing = readFileSync(filePath, "utf-8");
+  if (check) {
+    return existing.includes(section) ? "skipped" : "stale";
+  }
   if (existing.includes(COPILOT_SECTION_START)) {
     if (!force) return "skipped";
-    const updated = existing.replace(
+    const updated = existing.replaceAll(
       new RegExp(`${COPILOT_SECTION_START}[\\s\\S]*?${COPILOT_SECTION_END}`, "g"),
-      `${COPILOT_SECTION_START}
-${body}
-${COPILOT_SECTION_END}`
+      section
     );
     writeFileSync(filePath, updated, "utf-8");
     return "written";
   }
-  writeFileSync(
-    filePath,
-    `${existing}
-${COPILOT_SECTION_START}
-${body}
-${COPILOT_SECTION_END}
-`,
-    "utf-8"
-  );
+  writeFileSync(filePath, `${existing}
+${section}
+`, "utf-8");
   return "written";
 };
+const resolveSkillOptions = (opts) => ({
+  check: opts.check ?? false,
+  createAgentsMd: opts.createAgentsMd ?? false,
+  cwd: opts.cwd ?? process.cwd(),
+  force: opts.force ?? false
+});
 const generateAgentSkills = async (opts = {}) => {
-  const cwd = opts.cwd ?? process.cwd();
-  const force = opts.force ?? false;
+  const { check, createAgentsMd, cwd, force } = resolveSkillOptions(opts);
   const written = [];
   const skipped = [];
+  const stale = [];
   const features = await analyzeEslintConfig(cwd) ?? featuresFromDetection(cwd);
   const plainBody = generateSkillContent(features, "plain");
-  const copilotResult = handleCopilotInstructions(cwd, plainBody, force);
-  if (copilotResult === "written") written.push(join(cwd, COPILOT_INSTRUCTIONS_PATH));
-  else if (copilotResult === "skipped") skipped.push(join(cwd, COPILOT_INSTRUCTIONS_PATH));
+  const recordGuardedResult = (filePath, result) => {
+    switch (result) {
+      case "skipped":
+        skipped.push(filePath);
+        break;
+      case "stale":
+        stale.push(filePath);
+        break;
+      case "written":
+        written.push(filePath);
+        break;
+    }
+  };
+  const copilotPath = join(cwd, COPILOT_INSTRUCTIONS_PATH);
+  recordGuardedResult(copilotPath, handleGuardedSectionFile(copilotPath, plainBody, force, check));
+  const agentsMdPath = join(cwd, AGENTS_MD_PATH);
+  recordGuardedResult(agentsMdPath, handleGuardedSectionFile(agentsMdPath, plainBody, force, check, createAgentsMd));
   for (const target of AGENT_TARGETS) {
     const agentFolder = join(cwd, target.markerFolder);
     if (!existsSync(agentFolder)) continue;
     const subdir = target.skillSubdir === "." ? agentFolder : join(agentFolder, target.skillSubdir);
     const filePath = join(subdir, target.skillFile);
     const content = generateSkillContent(features, target.format);
+    if (check) {
+      const upToDate = existsSync(filePath) && readFileSync(filePath, "utf-8") === content;
+      if (upToDate) skipped.push(filePath);
+      else stale.push(filePath);
+      continue;
+    }
     const didWrite = writeSkillFile(filePath, content, force);
     if (didWrite) written.push(filePath);
     else skipped.push(filePath);
   }
-  return { written, skipped };
+  return { skipped, stale, written };
 };
-const handleGenerateSkill = async (cwd = process.cwd(), force = false) => {
-  console.log("\u{1F50D} Scanning for AI agent folders...");
-  const configFile = findEslintConfig(cwd);
-  if (configFile) {
-    console.log(`\u{1F4C4} Reading config from: ${configFile.replace(cwd + "/", "")}`);
-  } else {
-    console.log("\u26A0\uFE0F  No eslint.config.js found \u2014 falling back to package.json detection.");
-  }
-  const result = await generateAgentSkills({ cwd, force });
-  if (result.written.length === 0 && result.skipped.length === 0) {
-    console.log(
-      "\n\u26A0\uFE0F  No agent folders found (.agent, .agents, .claude, .cursor, .windsurf, .copilot, .aider)."
-    );
-    console.log("   Create one of those folders first, then re-run this command.");
+const resolveGenerateSkillFlags = (flags) => ({
+  check: flags.check ?? false,
+  createAgentsMd: flags.createAgentsMd ?? false
+});
+const outputGenerateSkillResults = (check, result, cwd) => {
+  if (check) {
+    for (const file of result.skipped) {
+      console.log(`\u2705 Up to date: ${file.replace(cwd + "/", "")}`);
+    }
+    for (const file of result.stale) {
+      console.log(`\u274C Stale or missing: ${file.replace(cwd + "/", "")}`);
+    }
+    if (result.stale.length > 0) {
+      console.log(`
+\u26A0\uFE0F  ${result.stale.length} skill file(s) are out of date. Run \`generate-skill --force\` to regenerate them.`);
+      process.exitCode = 1;
+    } else {
+      console.log("\n\u{1F389} All agent skill files are up to date!");
+    }
     return;
   }
   for (const file of result.written) {
@@ -511,6 +671,23 @@ const handleGenerateSkill = async (cwd = process.cwd(), force = false) => {
     console.log("\n\u{1F4A1} Tip: run with --force to overwrite existing skill files.");
   }
 };
+const handleGenerateSkill = async (cwd = process.cwd(), force = false, flags = {}) => {
+  const { check, createAgentsMd } = resolveGenerateSkillFlags(flags);
+  console.log(check ? "\u{1F50D} Checking AI agent skill files..." : "\u{1F50D} Scanning for AI agent folders...");
+  const configFile = findEslintConfig(cwd);
+  if (configFile) {
+    console.log(`\u{1F4C4} Reading config from: ${configFile.replace(cwd + "/", "")}`);
+  } else {
+    console.log("\u26A0\uFE0F  No eslint.config.js found \u2014 falling back to package.json detection.");
+  }
+  const result = await generateAgentSkills({ check, createAgentsMd, cwd, force });
+  if (result.written.length === 0 && result.skipped.length === 0 && result.stale.length === 0) {
+    console.log("\n\u26A0\uFE0F  No agent folders found (.agent, .agents, .claude, .cursor, .windsurf, .copilot, .aider, .gemini, .clinerules, .roo, .kiro) and no AGENTS.md.");
+    console.log("   Create one of those folders first (or re-run with --create to scaffold AGENTS.md).");
+    return;
+  }
+  outputGenerateSkillResults(check, result, cwd);
+};
 export {
   AGENT_TARGETS,
   analyzeEslintConfig,