/SKILL.md

name, description, argument-hint

name	description	argument-hint
acreadiness-generate-instructions	通过 AgentRC instructions 命令生成量身定制的 AI 智能体指令文件。生成 .github/copilot-instructions.md（默认，推荐用于 VS Code 中的 Copilot），还可为单体仓库生成带有 applyTo glob 的按区域 .instructions.md 文件。在运行 /acreadiness-assess 后使用，以弥补 AI 工具支柱的缺口。	[--output .github/copilot-instructions.md|AGENTS.md] [--strategy flat|nested] [--areas | --area <name>] [--apply-to <glob>] [--claude-md] [--dry-run]

/acreadiness-generate-instructions — 编写 AI 智能体指令

每当用户希望创建、重新生成或刷新针对 AI 编码智能体（Copilot、Claude 等）的自定义指令时，请使用此技能。这是 AgentRC 度量 → 生成 → 维护循环中的生成步骤，也是AI 工具支柱中杠杆率最高的操作。

输出选项

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

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

策略

• flat （默认） —— 在指定路径生成单个 .github/copilot-instructions.md。简单，易于审查。
• nested —— 在 .github/copilot-instructions.md 处生成中心枢纽，同时在 .github/instructions/<topic>.instructions.md 处生成按主题的详细文件，每个文件都带有 applyTo glob，以便 VS Code 仅在相关时加载该主题。适用于大型或多技术栈仓库。

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

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

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

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

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

两者可以并存：一组嵌套的主题文件加上为单体仓库生成的按区域文件。

带有 applyTo 的按区域文件

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

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

# 前端区域指令

……此区域的 AgentRC 生成内容……

工作流程：

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。 仅当用户提到多智能体 / 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 个顶级目录、多个技术栈或已在使用单体仓库工具（turbo/nx/pnpm workspaces）时，主动推荐 nested。
3. 检测单体仓库区域 —— 读取 agentrc.config.json。如果存在区域，询问用户是否希望在根文件之外还生成带有 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：对于嵌套模式，保留 AgentRC 原生的 .agents/ 布局 —— 智能体无关的读者期望指令放在那里。 如果 .github/instructions/ 目录不存在则创建。

主题 applyTo 默认值

当将 AgentRC 的嵌套主题文件提升为 .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. 验证 —— 回读生成的文件，并向用户展示一段简要总结：检测到的技术栈、捕获的约定、长度、.instructions.md 文件列表及其 glob。
9. 建议后续步骤：

• 重新运行 assess 技能以确认 AI 工具支柱得分有所提升。
• 如果用户同时拥有 copilot-instructions.md 和 AGENTS.md，建议整合为单一事实来源（AgentRC 会在成熟度 Level 2+ 时标记这一点）。

注意事项

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