Agent Skills 高级实践指南

# 不好的做法 - 单个文件过大
/skills/frontend/SKILL.md  (15KB - 包含所有框架)
- React 最佳实践 (3000 行)
- Vue 最佳实践 (3000 行)
- Angular 最佳实践 (3000 行)
- 通用规范 (2000 行)

# 好的做法 - 拆分成多个专精的 Skills
/skills/react-enterprise/SKILL.md     (5KB)
/skills/vue3-enterprise/SKILL.md      (5KB)
/skills/angular-modern/SKILL.md       (5KB)
/skills/frontend-common/SKILL.md      (3KB)

## Trigger Conditions
- 用户提到前端
- 任何代码相关的问题

## Trigger Conditions
MUST trigger when:
- 用户明确提到 "Vue3 组件"
- 文件扩展名为 .vue
- 用户要求创建 "Composition API" 代码
- 提到 "Pinia store" 或 "composable"

SHOULD NOT trigger when:
- 一般性的前端问题（由 frontend-common skill 处理）
- React/Angular 相关问题
- 只是提到 "Vue" 但没有版本号（可能是 Vue2）

# ❌ 完整示例 (500 行)
```typescript
// 包含所有细节，但太长了
import { ref, computed, watch, onMounted, onUnmounted } from 'vue'
import { useRouter, useRoute } from 'vue-router'
import { storeToRefs } from 'pinia'
// ... 省略 50 行导入

export default defineComponent({
  // ... 500 行完整代码
})
```text

**改为:**

```markdown
## ✅ 核心模式 (50 行) + 完整示例链接
```typescript
// 核心模式：组合式 API 组件结构
import { ref, computed } from 'vue'

export function useFeature() {
  const state = ref(initialValue)
  const derived = computed(() => transform(state.value))
  const action = () => { /* 核心逻辑 */ }

  return { state, derived, action }
}

---

## 2. Skills 调试技巧

### 2.1 验证 Skill 是否被加载

创建一个测试脚本:

```bash
#!/bin/bash
## test-skill-loading.sh

echo "测试 Skill 加载..."

## 1. 检查文件是否存在
if [ -f "/mnt/skills/user/vue3-enterprise/SKILL.md" ]; then
    echo "✓ Skill 文件存在"
else
    echo "✗ Skill 文件不存在"
    exit 1
fi

## 2. 检查文件权限
if [ -r "/mnt/skills/user/vue3-enterprise/SKILL.md" ]; then
    echo "✓ Skill 文件可读"
else
    echo "✗ Skill 文件不可读"
    exit 1
fi

## 3. 检查文件大小
SIZE=$(wc -c < "/mnt/skills/user/vue3-enterprise/SKILL.md")
echo "文件大小: ${SIZE} 字节"

if [ $SIZE -gt 10240 ]; then
    echo "⚠ 警告: 文件大小超过 10KB，可能需要拆分"
fi

## 4. 检查必需部分
REQUIRED_SECTIONS=("Description" "Trigger Conditions" "Instructions")
for section in "${REQUIRED_SECTIONS[@]}"; do
    if grep -q "## $section" "/mnt/skills/user/vue3-enterprise/SKILL.md"; then
        echo "✓ 包含 $section 部分"
    else
        echo "✗ 缺少 $section 部分"
    fi
done

echo "测试完成"
```text

### 2.2 添加调试标记

在 SKILL.md 中添加版本和调试信息:

```markdown
## Vue3 Enterprise Skill

<!--
VERSION: 2.1.0
LAST_UPDATED: 2024-02-05
AUTHOR: 团队名称
DEBUG: 如果看到这条信息，说明 skill 已被正确加载
-->

## Description
...
```text

### 2.3 使用模板验证

创建 Skill 验证模板:

```markdown
## Skill Quality Checklist

在发布 skill 前检查:

## 结构检查
- [ ] 有 Description 部分
- [ ] 有明确的 Trigger Conditions
- [ ] 有 Instructions 部分
- [ ] 有至少一个代码示例
- [ ] 文件大小 < 8KB

## 内容检查
- [ ] 触发条件足够具体
- [ ] 代码示例可直接运行
- [ ] 包含错误处理说明
- [ ] 有性能优化建议
- [ ] 列出了依赖项

## 测试检查
- [ ] 用真实场景测试过
- [ ] 生成的代码符合规范
- [ ] 没有明显的 bug
- [ ] 与其他 skills 没有冲突
```text

---

## 3. 团队协作 Skills 管理

### 3.1 Skill 版本控制策略

**目录结构:**

```plain
company-skills/
├── .git/
├── skills/
│   ├── frontend/
│   │   ├── vue3-enterprise/
│   │   │   ├── SKILL.md
│   │   │   ├── CHANGELOG.md
│   │   │   ├── templates/
│   │   │   └── examples/
│   │   └── react-enterprise/
│   ├── backend/
│   └── devops/
├── scripts/
│   ├── validate-skill.sh
│   └── deploy-skill.sh
└── README.md
```text

**CHANGELOG.md 示例:**

```markdown
## Changelog - Vue3 Enterprise Skill

## [2.1.0] - 2025-11-05

### Added
- 支持 Vue 3.4 新特性 defineModel
- 添加虚拟滚动最佳实践
- 新增性能监控示例

### Changed
- 更新 TypeScript 类型定义规范
- 优化组件命名约定

### Fixed
- 修复 Pinia store 示例中的类型错误
- 更正 Composable 返回值类型

## [2.0.0] - 2025-11-15

### Breaking Changes
- 移除 Vue 2 兼容代码
- 更新为 Composition API only

...
```text

### 3.2 Skill 审查流程

**Pull Request 模板:**

```markdown
## Skill 变更说明

### 变更类型
- [ ] 新增 Skill
- [ ] 更新现有 Skill
- [ ] 修复 Bug
- [ ] 性能优化

### 变更内容
简要说明改动内容...

### 测试场景
- [ ] 场景 1: 创建基础组件
- [ ] 场景 2: 创建复杂表单
- [ ] 场景 3: 状态管理集成

### 代码示例
提供测试用的提示词和预期输出...

### 影响范围
- [ ] 仅影响此 Skill
- [ ] 可能影响其他 Skills: [列出相关 Skills]
- [ ] 需要更新文档

### Checklist
- [ ] 通过 Skill 验证脚本
- [ ] 更新了 CHANGELOG
- [ ] 添加了测试用例
- [ ] 代码示例可运行
- [ ] 审查人员已测试
```text

### 3.3 Skill 命名规范

```plain
✅ 好的命名:
- vue3-enterprise-components
- python-fastapi-restful
- aws-lambda-serverless
- docker-microservices

❌ 差的命名:
- my-skill
- frontend
- coding
- utils
```text

**命名公式:**

```plain
{技术栈}-{具体领域}-{可选的特定用途}

示例:
- react-18-hooks-advanced
- nodejs-express-middleware
- postgresql-query-optimization
```text

---

## 4. 高级 Skills 模式

### 4.1 组合式 Skills

**场景**: 大型项目需要多个 skills 协同工作

**skills/project-init/SKILL.md:**

```markdown
## Project Initialization Skill

## Description
初始化完整的企业级项目，协调多个专项 skills

## Related Skills
此 skill 会调用:
- `vue3-enterprise`: 前端框架配置
- `typescript-strict`: TypeScript 严格模式配置
- `vite-optimization`: 构建优化
- `eslint-prettier`: 代码规范
- `vitest-testing`: 测试配置

## Workflow
1. 调用 `vue3-enterprise` 创建基础项目结构
2. 调用 `typescript-strict` 配置 tsconfig.json
3. 调用 `vite-optimization` 优化构建配置
4. 调用 `eslint-prettier` 设置代码规范
5. 调用 `vitest-testing` 配置测试环境
6. 生成项目 README 和开发文档

## Instructions
按顺序读取并应用以下 skills:
```bash
view /mnt/skills/user/vue3-enterprise/SKILL.md
view /mnt/skills/user/typescript-strict/SKILL.md
view /mnt/skills/user/vite-optimization/SKILL.md
view /mnt/skills/user/eslint-prettier/SKILL.md
view /mnt/skills/user/vitest-testing/SKILL.md

### 4.2 条件式 Skills

**场景**: 根据用户环境选择不同的实现

**skills/database-orm/SKILL.md:**
```markdown
## Database ORM Skill

## Trigger Conditions
- 用户提到 "ORM" 或 "数据库映射"
- 需要生成数据模型代码

## Environment Detection
首先检测用户的技术栈:

```python
# 检测依赖
dependencies = read_package_json()

if "prisma" in dependencies:
    use_skill("prisma-orm")
elif "typeorm" in dependencies:
    use_skill("typeorm-orm")
elif "sequelize" in dependencies:
    use_skill("sequelize-orm")
else:
    # 询问用户偏好
    ask_user_preference()

// 生成 Prisma Schema
model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  posts     Post[]
  createdAt DateTime @default(now())
}

// 生成 TypeORM Entity
@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ unique: true })
  email: string;

  @Column({ nullable: true })
  name?: string;

  @OneToMany(() => Post, post => post.user)
  posts: Post[];

  @CreateDateColumn()
  createdAt: Date;
}

### 4.3 增量式 Skills

**场景**: 随着对话深入，逐步提供更高级的功能

**skills/vue3-progressive/SKILL.md:**
```markdown
## Vue3 Progressive Skill

## Skill Levels

### Level 1: 基础组件 (首次触发)
提供基础的组件结构:
- Props/Emits 定义
- 基础响应式数据
- 简单的方法

### Level 2: 中级功能 (用户要求更多功能时)
检测到以下关键词时升级:
- "性能优化"
- "复杂交互"
- "状态管理"

提供:
- Computed 优化
- Watch 高级用法
- Lifecycle hooks

### Level 3: 高级模式 (专业需求)
检测到以下关键词时升级:
- "大规模数据"
- "虚拟滚动"
- "微前端"

提供:
- 虚拟列表
- 动态组件
- 异步组件
- 性能监控

## 触发机制
```markdown
用户: "创建一个表格组件"
→ Level 1: 基础表格

用户: "需要支持 10000 行数据"
→ Level 3: 虚拟滚动表格

用户: "要能排序和筛选"
→ Level 2: 添加交互功能

---

## 5. Skills 与 RAG 深度集成

### 5.1 混合检索架构

```python
## hybrid-retrieval.py
from typing import List, Dict
import chromadb
from pathlib import Path

class HybridSkillRetrieval:
    def __init__(self):
        # 向量数据库存储 skill 元数据
        self.chroma = chromadb.Client()
        self.collection = self.chroma.create_collection("skills")

    def index_skills(self, skill_dir: Path):
        """索引所有 skills 的元数据"""
        for skill_path in skill_dir.glob("*/SKILL.md"):
            metadata = self._extract_metadata(skill_path)

            # 向量化 skill 描述和触发条件
            self.collection.add(
                documents=[metadata['description']],
                metadatas=[{
                    'path': str(skill_path),
                    'name': metadata['name'],
                    'triggers': ','.join(metadata['triggers'])
                }],
                ids=[metadata['name']]
            )

    def retrieve_relevant_skills(self, query: str, top_k: int = 3) -> List[str]:
        """根据查询检索相关 skills"""
        results = self.collection.query(
            query_texts=[query],
            n_results=top_k
        )

        # 返回 skill 文件路径
        return [meta['path'] for meta in results['metadatas'][0]]

    def _extract_metadata(self, skill_path: Path) -> Dict:
        """提取 skill 元数据"""
        content = skill_path.read_text()

        # 解析 markdown 提取关键信息
        metadata = {
            'name': skill_path.parent.name,
            'description': self._extract_section(content, 'Description'),
            'triggers': self._extract_triggers(content)
        }
        return metadata

## 使用示例
retrieval = HybridSkillRetrieval()
retrieval.index_skills(Path("/mnt/skills/user"))

## 用户查询
user_query = "如何创建一个支持拖拽排序的表格组件?"

## 1. RAG 检索相关 skills
relevant_skills = retrieval.retrieve_relevant_skills(user_query, top_k=2)
## 结果: ['vue3-enterprise/SKILL.md', 'dnd-components/SKILL.md']

## 2. Claude 读取这些 skills
for skill_path in relevant_skills:
    skill_content = read_file(skill_path)
    # Claude 获得完整指引

## 3. Claude 综合所有 skills 生成代码
```text

### 5.2 知识图谱增强

```python
## skill-knowledge-graph.py
from typing import Dict, List, Set
import networkx as nx

class SkillGraph:
    def __init__(self):
        self.graph = nx.DiGraph()

    def build_graph(self, skills_dir: Path):
        """构建 skills 依赖图"""
        for skill_path in skills_dir.glob("*/SKILL.md"):
            skill_name = skill_path.parent.name
            content = skill_path.read_text()

            # 添加节点
            self.graph.add_node(skill_name, path=str(skill_path))

            # 解析依赖关系
            related = self._extract_related_skills(content)
            for related_skill in related:
                self.graph.add_edge(skill_name, related_skill)

    def get_skill_chain(self, start_skill: str) -> List[str]:
        """获取完整的 skill 依赖链"""
        if start_skill not in self.graph:
            return [start_skill]

        # 使用拓扑排序获取正确的加载顺序
        try:
            chain = list(nx.topological_sort(
                self.graph.subgraph(
                    nx.descendants(self.graph, start_skill) | {start_skill}
                )
            ))
            return chain
        except nx.NetworkXError:
            # 有循环依赖，返回直接依赖
            return list(self.graph.successors(start_skill))

    def recommend_skills(self, current_skill: str) -> List[str]:
        """推荐相关 skills"""
        if current_skill not in self.graph:
            return []

        # 找到相邻的 skills
        neighbors = set(self.graph.successors(current_skill)) | \
                   set(self.graph.predecessors(current_skill))

        return list(neighbors)

## 使用示例
graph = SkillGraph()
graph.build_graph(Path("/mnt/skills/user"))

## 场景: 用户要初始化项目
skill_chain = graph.get_skill_chain("project-init")
## 结果: ['typescript-strict', 'eslint-prettier', 'vite-optimization', 'project-init']

## Claude 按顺序加载这些 skills
for skill in skill_chain:
    load_skill(skill)
```text

---

## 6. 真实场景：Skills 解决的问题

### 场景 1: 跨团队代码规范统一

**问题:**

- 前端团队 10 人，每人代码风格不同
- Code Review 争论不休
- 新人不知道怎么写

**传统方案:**

- 写一份 30 页的编码规范文档
- 新人看不完，老人记不住
- 规范文档很快过时

**Skills 方案:**

```markdown
## Company Frontend Standards Skill

## Description
公司前端代码标准，自动生成符合规范的代码

## Code Style Rules

### 组件命名
- 文件名: PascalCase (UserProfile.vue)
- 组件名: 与文件名一致
- Props: camelCase
- Events: kebab-case

### 文件结构顺序
```vue
<script setup lang="ts">
// 1. 类型定义
// 2. Props/Emits
// 3. 依赖注入
// 4. 响应式数据
// 5. Computed
// 6. Methods
// 7. Lifecycle
</script>

<template>
  <!-- 模板 -->
</template>

<style scoped>
  /* 样式 */
</style>

**效果:**
- 所有人生成的代码自动符合规范
- 新人上手快，不需要记忆规范
- 规范更新后，下次生成自动应用新规范

### 场景 2: 复杂业务逻辑封装

**问题:**
- 公司有复杂的权限系统
- 需要频繁实现权限检查
- 每个人实现方式不同，容易出错

**传统方案:**
```typescript
// 每次都要写一遍，容易遗漏
if (user.role === 'admin' || user.role === 'editor') {
  if (resource.ownerId === user.id || user.permissions.includes('edit_all')) {
    // 允许编辑
  }
}
```text

**Skills 方案:**

```markdown
## Company Permission Skill

## Permission Patterns

### 基础权限检查
```typescript
import { usePermission } from '@/composables/usePermission'

const { can, cannot } = usePermission()

// 检查权限
if (can('edit', resource)) {
  // 执行操作
}

// 在模板中
<button v-if="can('delete', item)">删除</button>

const { can } = usePermission()
const { user } = useUserStore()

const canEdit = computed(() =>
  can('edit', {
    type: 'resource',
    ownerId: resource.value.ownerId
  })
)

**效果:**
- 权限逻辑统一，减少 bug
- 自动生成标准化代码
- 权限规则变更时，更新 skill 即可

### 场景 3: 性能优化自动化

**问题:**
- 团队经常忘记性能优化
- 不知道何时该用 `shallowRef`，何时用 `ref`
- 虚拟滚动实现各异

**Skills 方案:**

```markdown
## Vue3 Performance Skill

## Trigger Conditions
检测到以下场景自动应用优化:
- 数组长度 > 100 → 建议虚拟滚动
- 大对象 (> 1000 keys) → 使用 shallowRef
- 频繁更新 (watch 回调 < 16ms) → 使用 debounce

## Automatic Optimizations

### 大列表检测
```typescript
// 用户写的代码
const items = ref([...]) // 10000 条数据

// Skill 自动建议
import { useVirtualList } from '@vueuse/core'

const { list, containerProps, wrapperProps } = useVirtualList(
  items,
  { itemHeight: 50 }
)

// 检测到大对象
const largeData = ref({ /* 1000+ keys */ })

// 自动建议
import { shallowRef } from 'vue'
const largeData = shallowRef({ /* 1000+ keys */ })

// 检测到昂贵的计算
const result = computed(() => {
  return expensiveOperation(data.value) // 耗时 > 10ms
})

// 自动添加缓存提示
const result = computed(() => {
  // 💡 此计算较耗时，已自动缓存
  return expensiveOperation(data.value)
})

---

## 7. Skills 最佳实践总结

### ✅ DO - 应该做的

1. **保持 Skill 专注**
   - 一个 Skill 只解决一类问题
   - 明确的边界和职责

2. **提供可运行的示例**
   - 示例代码应该可以直接复制使用
   - 包含必要的导入和配置

3. **文档化决策理由**
   ```markdown
   ## Why Not X?
   我们选择 Y 而不是 X 因为:
   - 性能更好 (benchmark 数据)
   - 类型安全
   - 团队更熟悉
```text

1. **版本化和变更日志**
    - 维护 CHANGELOG.md
    - 重大变更要标注 BREAKING CHANGE
2. **测试驱动**
    - 包含测试场景
    - 提供预期输出示例

### ❌ DON'T - 不应该做的

1. **不要写成教程**
    - Skill 是参考手册，不是入门教程
    - 假设用户有基础知识
2. **不要包含过时的信息**
    - 定期更新
    - 移除废弃的 API
3. **不要过度抽象**

```markdown
❌ "遵循 SOLID 原则生成代码"
✅ 提供具体的代码模板和检查清单
```text

1. **不要忽略边缘情况**

```markdown
## Edge Cases
- 空数组处理
- null/undefined 检查
- 网络失败重试
```text

1. **不要硬编码配置**

```markdown
❌ API_URL = "https://api.example.com"
✅ 使用环境变量: process.env.VITE_API_URL
```text

---

## 8. Skills 生态系统构建

### 8.1 公共 Skills 仓库

```bash
## GitHub 结构
awesome-claude-skills/
├── frontend/
│   ├── react/
│   ├── vue/
│   └── angular/
├── backend/
│   ├── nodejs/
│   ├── python/
│   └── java/
├── devops/
│   ├── docker/
│   ├── kubernetes/
│   └── cicd/
└── docs/
    ├── contributing.md
    └── skill-template.md
```text

### 8.2 Skill 市场

未来可能的发展方向:

```typescript
// skill-marketplace.ts
interface SkillPackage {
  name: string
  version: string
  author: string
  description: string
  downloads: number
  rating: number
  dependencies: string[]
  tags: string[]
}

// 安装 skill
const installer = new SkillInstaller()
await installer.install('vue3-enterprise@2.1.0')

// 发布 skill
const publisher = new SkillPublisher()
await publisher.publish('./my-skill', {
  private: false,
  license: 'MIT'
})
```text

### 8.3 Skills 分析工具

```python
## skill-analyzer.py
class SkillAnalyzer:
    def analyze_usage(self, skill_name: str):
        """分析 skill 使用情况"""
        return {
            'total_uses': 1250,
            'success_rate': 0.94,
            'avg_response_time': '1.2s',
            'common_errors': [
                'Missing dependency X',
                'Version conflict with Y'
            ],
            'user_feedback': {
                'positive': 1100,
                'negative': 150
            }
        }

    def suggest_improvements(self, skill_name: str):
        """建议优化方向"""
        return [
            'Add example for async operations',
            'Update TypeScript to 5.0',
            'Simplify error handling section'
        ]
```text

---

## 9. 下一代 Skills 展望

### 9.1 自适应 Skills

```markdown
## Adaptive Skill (概念)

## Context Awareness
自动检测:
- 用户技术水平 (初学者/专家)
- 项目规模 (小型/企业级)
- 时间压力 (快速原型/生产就绪)

## Dynamic Content
根据上下文调整输出:
- 初学者 → 详细注释 + 解释
- 专家 → 简洁代码 + 高级模式
- 快速原型 → 最小可用代码
- 生产就绪 → 完整错误处理 + 测试
```text

### 9.2 AI 生成 Skills

```python
## 未来可能: 从代码仓库自动生成 skill
def generate_skill_from_repo(repo_url: str) -> Skill:
    """分析代码仓库，提取最佳实践"""

    # 1. 克隆仓库
    repo = clone_repository(repo_url)

    # 2. 分析代码模式
    patterns = analyze_code_patterns(repo)

    # 3. 提取组件结构
    components = extract_components(repo)

    # 4. 生成 SKILL.md
    skill = generate_markdown(
        patterns=patterns,
        components=components,
        examples=extract_examples(repo)
    )

    return skill
```text

### 9.3 协作式 Skills

```markdown
## Collaborative Skill

## Multi-Agent Collaboration
不同 AI agents 协作:
- Design Agent: 负责 UI/UX 设计
- Code Agent: 生成代码实现
- Test Agent: 编写测试用例
- Review Agent: 代码审查

## Workflow
1. Design Agent 读取 design-system skill
2. Code Agent 读取 vue3-enterprise skill
3. Test Agent 读取 vitest-testing skill
4. Review Agent 读取 code-review skill

每个 agent 专注自己的领域，协作完成任务
```text

---

这个高级指南涵盖了 Skills 的实战技巧、团队协作、深度集成和未来展望。

结合前面的基础指南和 Vue3 Demo，你现在应该对 Agent Skills 有了全面深入的理解。