Angular Agent Skills 详解：让 AI 编码智能体掌握现代 Angular 开发的最佳实践

Angular 仓库内置了一套面向 AI 编码智能体（如 Gemini CLI、Antigravity 等 agentic 工具）的 Agent Skills——一组专门针对 Angular 领域编写的指令与参考资料集合。它们为智能体提供架构指导、生成符合惯例的 Angular 代码，并帮助按照现代最佳实践搭建新项目。理解这套技能的组成、触发逻辑与参考资料的覆盖范围，能让你在本地环境中正确安装和激活技能，让 AI 智能体始终基于最新的 Angular 约定（如 Signals 响应式模型、独立组件、Signal Forms）来工作。本篇以 agent-skills.md 文档为主体，结合仓库中 skills/dev-skills/ 目录下的真实技能定义文件展开分析。

Agent Skills 是什么

Agent Skills 是为 Gemini CLI 这类 AI 智能体设计的专业化、领域特化的指令与能力集合。根据 agent-skills.md 的描述，其核心价值有两点：

1. 提供架构指导并生成地道的（idiomatic）Angular 代码；
2. 确保智能体掌握 Angular 最新的信息——包括项目约定、响应式模型（如 Signals）、项目结构等，因为框架的惯例随版本快速演进（例如 Signal Forms 在 Angular v22 才稳定）。

智能体在激活某个技能后，会加载该任务所需的特定指令与资源文件，从而在生成代码时遵循官方团队维护的最新规范，而不是依赖训练数据中可能过时的知识。

仓库内置的两个官方技能

Angular 团队维护的官方技能集合会定期更新，以保持与框架最新改进同步。当前仓库 skills/dev-skills/ 目录下提供两个技能：

技能	说明
angular-developer	生成 Angular 代码并提供架构指导。适用于创建组件、服务、HTTP 通信，以及查询响应式（signals、linkedSignal、resource、httpResource）、表单、依赖注入、路由、SSR、无障碍（ARIA）、动画、样式、测试、命名约定或 CLI 工具的最佳实践
angular-new-app	使用 Angular CLI 创建新的 Angular 应用，提供有效搭建和结构化现代 Angular 应用的重要准则

两个技能各由一个带 YAML frontmatter 的 SKILL.md 文件定义核心指令，angular-developer 还附带了一个 references/ 目录存放 37 篇细粒度参考文档。下面分别深入分析。

angular-developer：生成代码与架构指导技能

技能定义见 angular-developer/SKILL.md。其 frontmatter 声明了技能名称、触发描述（Trigger when creating projects, components, services...）、许可证（MIT）与版本元数据。智能体依据 description 字段判断何时激活该技能。

三条硬性工作规则

SKILL.md 开头给出了三条必须遵守的规则：

1. 先分析项目 Angular 版本——不同版本的最佳实践和可用特性差异很大；若用 CLI 创建新项目，除非用户指定，否则不要指定版本；
2. 遵循 Angular 风格指南——使用 Angular CLI 脚手架化组件、服务、指令、管道和路由，保证一致性；
3. 生成代码后必须运行 ng build 确认没有构建错误，若有错误需分析并修复后才能继续——该步骤被明确标注为不可跳过。

ng new 的三步执行决策规则

技能对创建新项目给出了严格的执行规则（Execution Rules），体现了"先探测环境、再决定命令"的智能体工作流：

第 1 步：检查用户是否指定了版本。 若用户请求特定版本（如 Angular 15），绕过本地安装，严格使用 npx：

npx @angular/cli@<requested_version> new <project-name>

第 2 步：检查是否已有 Angular 安装。 若未指定版本，先运行 ng version：命令成功返回版本则直接使用本地/全局安装：

ng new <project-name>

第 3 步：回退到最新版。 若未指定版本且 ng version 失败（系统无 Angular 安装），使用 npx 拉取最新版：

npx @angular/cli@latest new <project-name>

37 篇参考资料：按主题索引的知识库

angular-developer 技能的核心设计是主题化参考文档索引——智能体根据任务类型按需读取对应的 references/ 文档。SKILL.md 将其组织为以下主题域：

• 组件：基础概念与控制流（components.md）、信号化输入（inputs.md）、输出（outputs.md）、宿主元素（host-elements.md）、命名约定（naming-conventions.md）
• 响应式与数据管理：Signals 概览（signals-overview.md）、依赖状态 linkedSignal（linked-signal.md）、异步响应式 resource（resource.md）、副作用 effect（effects.md）
• HTTP 通信：provideHttpClient、拦截器与 httpResource（http-client.md）
• 表单：新应用优先 Signal Forms（signal-forms.md）；简单表单用模板驱动（template-driven-forms.md）；复杂表单用响应式表单（reactive-forms.md）
• 依赖注入：基础（di-fundamentals.md）、创建服务（creating-services.md）、Provider 定义（defining-providers.md）、注入上下文（injection-context.md）、分层注入器（hierarchical-injectors.md）
• 路由：定义路由、加载策略、路由出口、导航、守卫、数据解析器、路由生命周期事件、渲染策略（CSR/SSG/SSR）、路由过渡动画等 9 篇参考文档
• 样式与动画：Tailwind CSS（tailwind-css.md）、动画（angular-animations.md）、组件样式（component-styling.md）
• 测试：单元测试基础（Vitest + TestBed）、组件 Harness、RouterTestingHarness、E2E 测试
• 工具链：Angular CLI（cli.md）、代码现代化迁移（migrations.md）、MCP 服务器（mcp.md）、环境配置（environment-configuration.md）
• 无障碍：Angular Aria 无头可访问组件（手风琴、列表框、组合框、菜单、标签页、工具栏、树、网格）

参考资料的深度示例

以 signals-overview.md 为例，参考文档给出了可直接复用的代码级指导：signal() 创建可写信号（set/update 更新）、computed() 惰性求值且带记忆化、asReadonly() 暴露只读状态、untracked() 在响应式上下文中读取信号而不建立依赖。文档还特别指出一个易错点：响应式上下文只在同步代码中生效，await 之后的信号读取不会被跟踪，必须始终在异步边界之前读取信号。

再如 resource.md，展示了 resource() 的完整用法：params 计算函数追踪响应式参数变化触发重新获取，loader 中必须把 abortSignal 传给 fetch 以支持参数变化时中止旧请求，以及 value()/hasValue()/isLoading()/reload() 等状态信号 API。这些细节正是"技能让智能体掌握最新框架行为"的具体体现。

cli.md 则给智能体规定了工具使用纪律：始终用 ng add 而非 npm install 添加 Angular 库（因为 ng add 会同时运行初始化 schematics，如配置 angular.json、更新根 providers）；代码生成一律走 ng generate；ng build 默认启用 AOT 编译、压缩和 tree-shaking。

mcp.md 描述了随 Angular CLI 内置的 MCP 服务器：它让 AI 助手直接驱动 CLI，提供 ai_tutor（交互式教程）、devserver.start/stop/wait_for_build（开发服务器控制）、get_best_practices（获取最佳实践指南）、list_projects（读取 angular.json 列出工程）、onpush_zoneless_migration（OnPush 迁移计划）、run_target、search_documentation 等工具。各宿主环境的配置方式为在项目根创建对应配置文件（如 Gemini CLI 的 .gemini/settings.json、Cursor 的 .cursor/mcp.json、VS Code 的 .vscode/mcp.json、Antigravity 的 .antigravity/mcp.json），命令统一为 npx @angular/cli mcp，并支持 --read-only（仅注册不修改项目的工具）与 --local-only（仅注册无需联网的工具）两个选项。

angular-new-app：搭建现代 Angular 应用技能

技能定义见 angular-new-app/SKILL.md，其 frontmatter 声明了兼容性要求（需要 node、npm 与网络访问）。该技能把"创建新应用"固化为 5 步流程：

第 1 步：确认 Angular CLI 存在。 在 *nix 系统上用 which ng，Windows 上用 where ng（PowerShell 用 gcm ng）。若不存在，询问用户是否全局安装：

npm install -g @angular/cli

第 2 步：创建应用。 根据用户提示建议或询问应用名称，然后执行：

npx ng new <app-name> [基于应用描述选择的标志] --interactive=false --ai-config=[agents, claude, copilot, cursor, gemini, jetbrains, none, windsurf]

--ai-config 用于为项目写入对应 AI 工具的最佳实践配置，技能要求优先选 agents，或选择与用户环境匹配的选项（如用户用 Gemini 就选 --ai-config=gemini），并把该 AI 配置内容载入记忆以便后续生成一致符合现代 Angular 实践的代码。常用标志包括：

• --style=scss|css|less — 样式表格式
• --routing — 添加路由模块
• --ssr — 启用服务端渲染
• --prefix=<prefix> — 组件选择器前缀
• --skip-tests — 仅在用户明确要求时跳过测试

第 3 步：先构建功能再启动应用。 未完成部分功能前不要启动应用，可随时运行 npx ng build 检查并修复错误。

第 4 步：用 CLI 脚手架化所有新构件。 技能明确列出了生成命令：npx ng generate component|service|pipe|directive|interface|guard|interceptor|resolver|enum|class <name>，并强调要记录 generate 命令返回的路径以准确定位新文件——先用 CLI 生成代码，再针对应用需求增强代码。

第 5 步：添加 Tailwind CSS。 运行 npx ng add tailwindcss 后即可直接使用 Tailwind 类，遵循 Tailwind v4 的最佳实践。

技能还两次强调：CLI 内置的 MCP 服务器提供 get_best_practices 工具，是构建高质量 Angular 应用的重要信息源。

在本地环境中使用 Agent Skills

Agent Skills 设计用于与 Gemini CLI、Antigravity 等 agentic 编码工具配合。激活技能即加载该任务所需的特定指令与资源。在自有环境中使用时，可遵循具体工具的说明，或使用社区工具 skills.sh 一行命令安装：

npx skills add https://github.com/angular/skills

该命令会把 Angular 官方技能仓库安装到本地智能体可识别的位置，之后智能体根据任务上下文自动匹配并激活 angular-developer 或 angular-new-app 技能。

技能的贡献与更新机制

从 skills/dev-skills/README.md 可以看到，这套技能直接在 angular/angular 主仓库的 skills/dev-skills/ 目录中维护，并通过基础设施流程发布到独立的 skills 仓库。贡献需遵循 Angular 标准的 提交信息指南 与 编码规范；遇到 bug 或改进建议则通过 Angular 仓库的 issue tracker 提交。这种"技能与框架同仓维护"的模式，正是文档中"技能定期更新、与框架改进保持同步"这句话的落地机制。

小结

Angular Agent Skills 的本质是把官方团队的领域知识结构化为智能体可消费的技能包：

1. angular-new-app 用 5 步流程固化了"探测环境 → ng new（含 --ai-config）→ 构建验证 → CLI 脚手架 → Tailwind 集成"的建项目标准动作；
2. angular-developer 用"三条硬性规则 + 37 篇主题参考文档"的组合，让智能体在处理组件、Signals、表单、路由、测试、工具链等具体任务时查阅对应权威资料；
3. 两个技能都指向 Angular CLI 内置的 MCP 服务器（get_best_practices 等工具），形成"静态技能文档 + 动态 CLI 能力"的双通道信息供给。

对开发者而言，安装这些技能后即可让智能体生成的代码贴合当前 Angular 版本的信号化响应式模型、独立组件与 Signal Forms 等现代实践；对仓库维护者而言，skills/dev-skills/ 目录下的 SKILL.md 与 references/ 文档是理解 Angular 官方推荐开发范式的现成索引。