Claude Code Agent Skills 初体验

Claude Code Agent Skills 初体验

引言：为什么前端团队需要Agent Skills？

痛点：Vue开发中的协作之殇

在Vue前端团队的日常开发中，我们常常被一些看似琐碎、实则影响深远的问题所困扰。这些问题不仅消耗着开发者的精力，更在无形中侵蚀着团队的协作效率和代码质量。

1. 代码审查标准不统一 “这个组件为什么用v-if而不是v-show？” “这里的props命名风格和另一个文件不一致。” “为什么不用Composition API？”

每次代码审查（Code Review）都可能变成一场关于“最佳实践”的辩论。资深开发者有自己的一套标准，新人则可能遵循另一套教程的写法。缺乏统一、可执行的审查标准，导致代码库风格割裂，审查过程耗时且充满主观性。

2. 组件文档缺失或过时 团队内部沉淀了无数优秀的业务组件，但当新成员需要使用时，往往面临困境：

• 文档在哪里？是写在README.md里，还是某个陈旧的Confluence页面？
• props的准确类型和默认值是什么？
• 有没有现成的使用示例？
• 文档描述的功能和组件实际行为是否一致？

“问同事”成为最高效的文档查询方式，但这严重依赖人员稳定性，且知识无法有效沉淀和复用。

3. 重复性任务耗时费力

• 生成组件文档：为每个新组件手动编写格式化的props表格和示例。
• 标准化提交信息：每次git commit都要回想约定的格式。
• 执行重复的代码检查：在Review时，反复人工核对命名规范、Vue特定规则（如v-for的key）等。

这些任务本身技术含量不高，却占据了开发者大量的“心流”时间，导致创造性工作被频繁打断。

破局：Agent Skills——自动化知识传递

上述痛点的核心在于 “知识”与“执行”的脱节。团队的最佳实践、规范、流程（知识）存在于文档、老员工的头脑或零散的脚本中，未能直接赋能到日常开发（执行）的每一个环节。

Agent Skills 正是为解决这一问题而生。它不是一个新工具，而是一种将团队知识封装为可被AI智能体（Agent）自动理解和执行的能力的新范式。

简单来说，你可以创建一个Skill（技能）来教会Claude（或其他AI助手）：

• 如何按照你团队的标准进行代码审查。
• 如何为你的Vue组件生成统一格式的文档。
• 如何执行那些你定义好的、重复性的开发任务。

Agent Skills如何工作：以Vue团队为例

其运作机制非常符合开发者直觉：

1. 知识封装：你将团队规范写成一份SKILL.md文件。例如，创建一个名为vue-code-review的Skill，其中详细定义：

   • 组件必须使用<script setup>语法。
   • Props必须使用TypeScript类型定义。
   • 状态变更优先使用Pinia，而非组件内reactive。
   • 等等...

   ---
   name: vue-code-review
   description: 依据《XX前端团队Vue开发规范》进行代码审查。当用户请求审查代码、查看PR或提及“review”时自动触发。
   ---
   # Vue代码审查规范
   
   ## 组件规范
   1. 所有Vue单文件组件必须使用 `<script setup>` 语法。
   2. Props定义必须使用TypeScript接口或类型字面量...
   

2. 自动触发：当你在IDE中向Claude提出“请审查我当前打开的UserModal.vue文件”时，Claude会自动识别该请求与vue-code-review这个Skill的描述匹配，从而自动加载并应用该Skill中的知识来执行审查。

3. 效率提升：Claude会基于Skill中的规范，逐条检查代码，并生成一份结构化的审查报告，指出不符合规范的地方及其修改建议。审查标准从此统一、即时、自动化。

技能的分层与共享：打造团队知识库

Skills支持分层级配置，完美适配团队协作场景：

技能存放位置	路径	生效范围
个人技能	~/.claude/skills/	仅自己可用
项目技能	.claude/skills/	项目所有贡献者
组织技能	管理后台配置	全组织所有成员

对于Vue团队，你可以：

• 将公司级前端规范（如Git提交规范、基础组件库使用规范）部署为组织技能，全员自动继承。
• 将当前Vue项目的特定约定（如API请求封装方式、特定的状态管理模块使用规则）存放为项目技能，随Git仓库同步，确保任何克隆此项目的人都有一致的开发辅助。
• 开发者可以拥有自己的个人技能，用于个性化的高效操作。

超越简单提示：Skills的强大之处

与简单的聊天提示或静态的CLAUDE.md项目说明不同，Skills是动态、模块化且功能丰富的：

• 渐进式披露：复杂的技能（如“生成完整组件文档”）可以将详细的API参考、示例代码拆分成独立文件，仅在需要时加载，节省上下文空间。
• 工具权限控制：你可以限制某个Skill只能“读取”文件而不能“写入”，确保安全。

  ---
  name: vue-component-analyzer
  description: 分析Vue组件结构，提取props、events等信息。
  allowed-tools: Read, Grep # 只允许读文件，禁止修改
  ---
  

• 集成脚本：Skill可以捆绑Python/Shell脚本。当Claude执行“生成CHANGELOG”技能时，可以直接运行你写好的、逻辑复杂的版本分析脚本，而非尝试自己生成可能出错的代码。
• 子代理上下文：对于特别复杂、多步骤的任务（如“重构整个模块”），可以让Skill在一个独立的上下文中运行，不干扰主会话的聊天历史。

从痛点出发：构建你的第一个Vue团队Skill

让我们从一个最急迫的痛点开始：自动化组件文档生成。

1. 在项目根目录创建技能文件夹：

   mkdir -p .claude/skills/vue-component-doc
   

2. 创建核心技能文件 SKILL.md:

   ---
   name: vue-component-doc
   description: 为Vue单文件组件(SFC)自动生成标准格式的API文档。当用户请求为组件编写文档、生成README或分析组件接口时触发。
   ---
   
   # Vue组件文档生成器
   
   ## 任务
   当我请求你为Vue组件生成文档时，请执行以下步骤：
   
   1.  **分析组件**：读取指定的`.vue`文件，提取以下信息：
       - `<script setup>` 部分中定义的 `props`（包括名称、类型、默认值、是否必需）。
       - 使用 `defineEmits` 声明的事件。
       - 组件暴露的 `ref` 方法（通过 `defineExpose`）。
       - 插槽（Slot）名称和用途（通过注释推断）。
   
   2.  **生成文档**：将上述信息格式化为一个清晰的Markdown表格，结构如下：
   
   ### Props
   | 名称 | 类型 | 默认值 | 必填 | 说明 |
   |------|------|--------|------|------|
   | `modelValue` | `boolean` | `false` | 否 | 控制组件显示/隐藏 |
   
   ### Events
   | 事件名 | 参数 | 说明 |
   |--------|------|------|
   | `close` | `(event: MouseEvent)` | 点击关闭按钮时触发 |
   
   3.  **提供使用示例**：在文档末尾，生成一个简单的组件使用示例代码块。
   
   ## 示例输出
   假设分析 `MyModal.vue`，输出应类似于...
   

3. 立即体验：现在，当你打开一个Vue组件文件，并对Claude说：“请为这个组件生成API文档”，它就会自动运用vue-component-doc技能，快速生成一份标准化、可直接粘贴到项目文档中的内容。

小结

前端开发的演进，正从“工具链的堆砌”走向“知识效能的提升”。Agent Skills代表的正是后一种方向。它允许Vue团队将宝贵的、隐性的协作知识（规范、流程、最佳实践）转化为显性的、可自动执行的数字资产。

通过部署一系列量身定制的Skills，团队不仅能解决代码审查、文档缺失、重复劳动等具体痛点，更能构建起一个持续学习、自我强化的智能协作环境。当新成员加入，他们即刻便能获得与资深开发者同级别的“AI辅助”，极大缩短了上手时间，并保障了团队输出质量的一致性。

这不仅仅是效率工具，这是团队知识管理和工程文化的一次升级。现在，是时候将你的团队规范，转化为智能体的技能了。

核心概念：Skills与其他定制化工具的区别

在Vue项目开发中，我们常常需要借助AI助手（如Claude Code）来提升效率。Claude Code提供了多种定制化工具，包括Skills、Slash Commands、CLAUDE.md、Subagents、Hooks和MCP。理解它们之间的区别，特别是Skills的“模型自动触发”特性，对于为你的Vue项目选择合适的定制方式至关重要。

核心区别：自动触发 vs. 手动触发

所有工具的核心区别在于触发时机。

• Skills（技能）：由模型（Claude）自动触发。你无需手动调用，Claude会根据你当前请求的上下文，自动判断并应用最相关的Skill。这是其最核心的特性。
• Slash Commands（斜杠命令）：由用户手动触发。你需要输入 /command 来显式地执行一个预设的提示或操作。
• CLAUDE.md：在每次对话开始时自动加载。它定义了项目级的通用规则和上下文。
• Subagents（子代理）：可由模型自动委托，或由用户手动调用。它运行在一个独立的上下文中。
• Hooks（钩子）：在特定工具事件发生时自动触发（如保存文件时运行Lint）。
• MCP（模型上下文协议）服务器：由模型按需调用，用于连接外部工具和数据源。

下表清晰地展示了它们的适用场景和触发方式：

工具	当你想要…	触发时机
Skills	赋予Claude特定领域的知识（如“使用我们团队的Vue代码规范审查PR”）	Claude根据请求自动选择
Slash Commands	创建可复用的提示或操作（如 /deploy:staging 部署到预发环境）	用户手动输入 /command
CLAUDE.md	设置项目范围的通用指令（如“使用TypeScript严格模式”、“遵循Vue 3组合式API风格”）	每次对话开始时自动加载
Subagents	将任务委托给一个拥有独立上下文和工具的“专家”（如让一个专门的“测试代理”去编写单元测试）	Claude自动委托，或用户显式调用
Hooks	在特定事件发生时自动运行脚本（如在文件保存后自动格式化代码）	特定工具事件发生时自动触发
MCP	将Claude连接到外部工具和数据源（如连接你的Jira API、内部组件库文档API）	Claude在需要时调用

Skills的独特优势：模型自动触发

Skills的“模型自动触发”特性使其在以下场景中无可替代：

1. 无缝集成到工作流：当你专注于编码，随口问一句“帮我看看这个Composable函数写得规范吗？”，Claude会自动应用你定义的“Vue Composable规范检查”Skill，而无需你记住并输入某个特定命令。
2. 基于上下文的智能匹配：Claude通过读取Skill的description元数据字段来决定是否使用它。一个描述为“根据Vue项目规范生成组件文件，包括<template>, <script setup>, <style scoped>”的Skill，会在你请求“创建一个用户头像组件”时被自动触发。
3. 降低使用门槛：团队新成员无需学习一长串命令，只要按照团队习惯描述任务，就能自动获得符合规范的AI辅助。

如何为Vue项目选择合适的定制方式？

结合Vue项目开发的实际需求，我们可以这样选择：

1. 使用 CLAUDE.md 定义项目基石 这是第一步。在项目根目录的.claude/CLAUDE.md中，放置所有开发者都需要遵守的全局、静态规则。

   # Vue 3 项目开发规范
   
   ## 技术栈
   
   - Vue 3 + Composition API + `<script setup>`
   - TypeScript with strict mode
   - Pinia for state management
   - Vue Router
   - ESLint + Prettier (配置已同步)
   
   ## 组件规范
   
   - 使用 `PascalCase` 命名组件文件，如 `UserAvatar.vue`
   - 使用 `kebab-case` 命名模板中的组件，如 `<user-avatar />`
   - 样式默认使用 `<style scoped>`
     ...
   

2. 使用 Skills 封装领域知识和复杂流程 将特定、可复用的专家级知识或流程封装成Skill，让Claude在相关场景下自动成为你的“专家搭档”。

   • 代码审查：创建 pr-review-vue-standards Skill，教导Claude如何审查Vue组件的Props定义、Emit事件、Composable逻辑拆分等。
   • 组件生成：创建 generate-vue-component Skill，自动按照团队模板生成包含TS类型、基础样式和注释的组件三件套。
   • 状态管理：创建 pinia-store-guide Skill，当用户提到“状态管理”或“Pinia”时，自动指导如何正确设计store模块。

   示例：一个简单的Vue组件生成Skill

   vue-component-generator/
   └── SKILL.md
   

   ---
   name: vue-component-generator
   description: 根据Vue 3项目规范生成标准的单文件组件。当用户请求创建新组件、生成组件模板或提及“Vue component”时使用。
   ---
   # Vue 3 标准组件生成器
   
   ## 指令
   1. 确认组件名称（使用 PascalCase）。
   2. 生成包含以下结构的单文件组件（.vue）：
       - `<template>` 部分：包含一个根元素，并添加基础注释。
       - `<script setup lang="ts">` 部分：使用TypeScript，包含`defineProps`和`defineEmits`的类型定义示例。
       - `<style scoped>` 部分：使用`scoped`属性，并添加基础样式占位符。
   3. 在组件顶部添加文件描述注释。
   
   ## 示例输出结构
   ```vue
   <!-- UserProfile.vue -->
   <template>
     <div class="user-profile">
       <!-- 组件内容 -->
     </div>
   </template>
   
   <script setup lang="ts">
   import { ref } from 'vue';
   
   interface Props {
     userId: number;
     name?: string;
   }
   const props = withDefaults(defineProps<Props>(), {
     name: 'Guest',
   });
   
   const emit = defineEmits<{
     (e: 'update:name', value: string): void;
   }>();
   
   // 组件逻辑
   const internalState = ref('');
   </script>
   
   <style scoped>
   .user-profile {
     /* 组件样式 */
   }
   </style>
   

3. 使用 Slash Commands 创建快捷操作 将你经常执行的、离散的、结果导向的任务固化成一个命令。

   • /build:analyze：运行构建并分析包大小。
   • /test:unit ComponentName：为指定组件生成或运行单元测试。
   • /i18n:extract：自动提取源代码中的待翻译文本。

4. 使用 Hooks 自动化日常任务 将基于事件的、机械的任务交给Hooks。

   • 在保存.vue文件后，自动运行ESLint和Prettier。
   • 在创建新分支后，自动安装项目依赖。

5. 使用 Subagents 处理独立子任务 当某个任务极其复杂或需要完全独立的上下文和工具集时使用。

   • 委托一个“重构代理”去安全地重构一个大型遗留组件，它拥有独立的对话历史，不会干扰你当前的主线开发思路。
   • 启动一个“文档代理”，专门分析代码并生成API文档。

6. 使用 MCP 连接外部系统 当需要Claude与项目外部的工具或数据交互时使用。

   • 连接内部的组件库文档系统，让Claude能查询BaseButton组件的所有可用Props。
   • 连接项目管理工具（如Jira），让Claude能根据任务号获取需求描述。

关键关系辨析

• Skills vs. Subagents：Skills是为当前对话中的Claude添加知识和指导；Subagents是创建一个新的、隔离的Claude实例来处理任务。在Vue开发中，用Skill教Claude如何写更好的computed属性；用Subagent将“为整个项目添加单元测试覆盖率”这个大型任务委派出去。
• Skills vs. MCP：Skills告诉Claude “如何” 做事（例如，“如何按照我们的规范组织Vuex/Pinia模块”）；MCP为Claude “提供” 做事的工具（例如，提供一个能读取真实后端API接口文档的工具）。两者可以结合：通过MCP连接你的设计系统Token API，再通过一个Skill教导Claude如何将这些Token应用到Vue组件的样式变量中。

总结

对于Vue前端架构师而言，有效利用这些定制化工具可以极大提升团队开发的一致性和效率。CLAUDE.md是项目的宪法，Skills是各部门的专家手册，Slash Commands是快捷指令，Hooks是自动化流水线，Subagents是特种任务小组，MCP则是外部联络官。

核心决策流：优先考虑是否需要自动触发。如果需要Claude智能地、无缝地在特定场景下应用特定知识，请选择Skills。如果只是一个需要手动执行的快捷操作，则选择Slash Commands。通过分层、组合使用这些工具，你可以为你的Vue项目构建一个强大而智能的AI辅助开发环境。