acreadiness-generate-instructions

/acreadiness-generate-instructions — 编写 AI Agent 指令

当用户想要创建、重新生成或刷新其用于 AI 编码 Agent（Copilot、Claude 等）的自定义指令时，使用此技能。这是 AgentRC 的衡量 → 生成 → 维护循环中的生成步骤，也是 AI Tooling 支柱中杠杆效应最高的单一操作。

输出选项

VS Code 可识别多种指令文件类型——AgentRC 会生成最常见的几种：

文件	作用范围	何时使用
.github/copilot-instructions.md	始终生效，整个工作区	默认 — VS Code Copilot 的原生指令文件
AGENTS.md	始终生效，整个工作区	多 Agent 仓库（Copilot + Claude + 其他）
.github/instructions/*.instructions.md	由 applyTo glob 限定范围	monorepo 中按区域 / 按语言的规则
CLAUDE.md	Claude 专用	通过 --claude-md 添加（仅嵌套模式）

策略

• flat （默认） — 在所选路径下生成单个 .github/copilot-instructions.md。简单，易于审阅。
• nested — 在 .github/copilot-instructions.md 设置中心文件 + 在 .github/instructions/<topic>.instructions.md 设置按主题划分的详情文件，每个文件都带有一个 applyTo glob，以便 VS Code 仅在相关时加载该主题。更适合大型或多技术栈仓库。

为什么是 .github/instructions/ 而不是 .agents/？ AgentRC 默认的嵌套布局会写入 .agents/，对于与 Agent 无关的仓库（Copilot + Claude + Cursor 都读取 AGENTS.md）来说，这是正确的归属位置。但具体到 VS Code Copilot，原生位置是带 applyTo frontmatter 的 .github/instructions/ —— 这正是 Copilot 会自动发现的位置。当主输出为 .github/copilot-instructions.md 时，此技能会将 AgentRC 的嵌套输出重写到 VS Code 原生的位置。如果你改为选择 --output AGENTS.md，嵌套模式会保留 AgentRC 默认的 .agents/ 布局。

对于 monorepo，使用 --areas、--area <name> 或 --areas-only 生成按区域限定范围的指令。区域在 agentrc.config.json 中定义。按区域的输出会写为带 applyTo glob 的 VS Code .instructions.md 文件（见下文）。

主题 .instructions.md 文件与区域 .instructions.md 文件

两者最终都位于 .github/instructions/，但它们回答的是不同的问题：

类型	文件名示例	applyTo 示例	来源
主题（嵌套）	testing.instructions.md	**/*.{test,spec}.{ts,tsx,js}	AgentRC --strategy nested 的主题拆分
区域（monorepo）	frontend.instructions.md	apps/frontend/**	agentrc.config.json 区域 + --areas

你可以同时拥有两者：一组嵌套的主题文件，外加 monorepo 的按区域文件。

带 applyTo 的按区域文件

当用户选择启用区域时，在 .github/instructions/<area>.instructions.md 为每个区域生成一个 VS Code 原生的 .instructions.md 文件。每个文件必须以声明规则适用 glob 的 frontmatter 开头：

---
applyTo: "apps/frontend/**"
---

# Frontend area instructions

…AgentRC-generated content for this area…

工作流：

1. 读取 agentrc.config.json 以发现声明的区域及其 paths / glob。如果缺少 paths，向用户询问 glob（例如 src/api/**）。
2. 运行 agentrc instructions --areas（或 --area <name>）以生成按区域的正文内容。
3. 将每个区域的内容包裹在 .github/instructions/<area>.instructions.md 中，并使用取自该区域 paths 的 applyTo frontmatter。如果用户在单区域调用中传入了 --apply-to <glob>，则原样使用该 glob。
4. 不要改动主文件 —— 根目录的 .github/copilot-instructions.md 仍作为始终生效的指令；.instructions.md 文件仅对匹配的路径生效。

命名：小写，区域名使用 kebab-case。示例：.github/instructions/frontend.instructions.md、.github/instructions/api.instructions.md、.github/instructions/infra.instructions.md。

步骤

1. 选择目标文件。默认使用 .github/copilot-instructions.md。 仅当用户提到多 Agent / Claude / Cursor 支持时，才切换到 AGENTS.md。
2. 始终询问使用哪种策略——flat 或 nested——除非用户已在消息中或通过 --strategy 指定了其中一种。简要说明权衡：
   • Flat （默认）——一个 .github/copilot-instructions.md。简单，易于在单个 PR 中审查。最适合单一技术栈的中小型仓库。
   • Nested——中心 .github/copilot-instructions.md + 按主题划分的 .github/instructions/<topic>.instructions.md 文件（每个文件带有一个 applyTo glob，以便 VS Code 仅在相关时加载它们）。最适合大型或多技术栈仓库。添加 --claude-md 可同时生成 CLAUDE.md。 当仓库有超过 5 个顶层目录、多个技术栈，或已使用 monorepo 工具（turbo/nx/pnpm workspaces）时，主动推荐 nested。
3. 通过读取 agentrc.config.json 检测 monorepo 区域。如果存在区域，询问用户是否希望在根文件之外还生成带 applyTo 的按区域 .instructions.md 文件。当 agentrc.config.json 声明了区域时，默认选择“是”。
4. 先运行 dry-run，以便用户预览：

   npx -y github:microsoft/agentrc instructions --output <file> --strategy <flat|nested> [--areas|--area <name>] [--claude-md] --dry-run
   

5. 显示简短摘要，说明将发生的更改——将被创建或覆盖的文件、区域数量 + 其 applyTo glob、使用的模型（默认 claude-sonnet-4.6）。
6. 确认后，运行相同命令但不带 --dry-run（如果文件已存在，可选带 --force）。
7. 为 Copilot 输出后处理布局：
   • 如果 --output 以 copilot-instructions.md 结尾且策略为 nested：将 AgentRC 的 .agents/<topic>.md 文件移动/重写为 .github/instructions/<topic>.instructions.md。为每个文件添加带有适当 applyTo glob 的 frontmatter（见下方“主题 applyTo 默认值”）。删除现已为空的 .agents/ 目录。
   • 如果使用了 --areas：还为每个区域写入 .github/instructions/<area>.instructions.md，使用 agentrc.config.json 中每个区域的 paths 作为 applyTo glob（单区域调用可用 --apply-to 覆盖）。
   • 如果选择了 --output AGENTS.md：对于 nested，保留 AgentRC 原生的 .agents/ 布局——与 Agent 无关的读取器期望它在那里。 如果 .github/instructions/ 目录不存在，则创建它。

主题 applyTo 默认值

将 AgentRC 的 nested 主题文件提升为 .instructions.md 时，除非用户另有指定，否则使用这些默认值：

主题	默认 applyTo
testing	**/*.{test,spec}.{ts,tsx,js,jsx,mjs,cjs}
style / code-quality / formatting	**/*.{ts,tsx,js,jsx,mjs,cjs,py,go,rs,java,kt,cs}
build / ci	**/{package.json,turbo.json,nx.json,.github/workflows/**}
docs	**/*.md
security	**
其他任何内容 / 中心级别	**

8. 验证：读回生成的文件，并向用户展示一段概要：检测到的技术栈、捕获的约定、长度、带其 glob 的 .instructions.md 文件列表。
9. 建议后续步骤：
   • 重新运行 assess 技能，以确认 AI Tooling 支柱得分有所提高。
   • 如果用户已同时拥有 copilot-instructions.md 和 AGENTS.md，建议合并为单一事实来源（AgentRC 在成熟度 Level 2+ 时标记此问题）。

说明

• AgentRC 读取你的实际代码——不使用模板。输出反映检测到的语言、框架和约定。
• --claude-md（仅 nested 策略）还会生成 CLAUDE.md。
• 当活动文件匹配 applyTo 时，VS Code 会自动应用 .instructions.md 文件。根 .github/copilot-instructions.md 始终加载。
• 切勿在 CI 中以非交互方式运行此技能；指令是仓库的一部分，应通过 PR 合入。