1. 核心概念理解
2. 项目拆分决策框架
3. 实战拆分流程
4. 完整案例示范
5. **实践与常见陷阱

Skills (技能)

• 本质:可复用的能力包,像是”使用说明书”
• 激活方式:Claude 根据描述自动加载,或手动调用
• 上下文:在主对话中执行,共享上下文
• 适用场景:可重复使用的工具函数、标准化流程
• 比喻:像是给 Claude 装备的”工具箱”

Subagents (子代理)

• 本质:独立的 AI 实例,像是”专业同事”
• 激活方式:Claude 委派任务或显式调用
• 上下文:拥有独立的上下文窗口,与主对话隔离
• 适用场景:复杂多步骤任务、需要大量探索的工作
• 比喻:像是团队中的”专业顾问”

问自己三个问题:

1. “这个任务会污染我的主对话上下文吗?” → 是 → 使用 Subagent
2. “这个功能我会在不同场景反复使用吗?” → 是 → 使用 Skill
3. “这个任务需要多步骤决策和独立判断吗?” → 是 → 使用 Subagent

   ---

   以一个文档处理系统为例:

   原始需求: 处理用户上传的 PDF/Word/Excel 文件 → 提取内容 → 分析数据 → 生成报告 → 存档 

   模块	类型	原因
   文档格式转换	Skill	纯工具函数,可复用
   内容深度分析	Subagent	需要大量阅读,会污染上下文
   报告生成	Skill	遵循固定模板
   数据验证	Subagent	需要多步骤验证和决策

   用户请求 ↓ 主对话 Claude ↓ 调用 document-converter (Skill) ↓ 转换成功 启动 content-analyzer (Subagent) ↓ 分析完成 调用 report-generator (Skill) ↓ 返回给用户 

   ---

   your-project/ ├── .claude/ │ ├── CLAUDE.md # 项目全局配置 │ ├── skills/ # Skills 目录 │ │ ├── document-converter/ │ │ │ ├── SKILL.md │ │ │ └── scripts/ │ │ │ └── convert.py │ │ └── report-generator/ │ │ └── SKILL.md │ └── agents/ # Subagents 目录 │ ├── content-analyzer.md │ └── data-validator.md 

   # 文档处理系统

项目概述

这是一个自动化文档处理系统,处理多种格式的文档并生成分析报告。

核心约定

• 所有文件处理必须保留原始文件
• 报告必须包含数据来源追踪
• 错误处理:失败时保存部分结果

目录结构

• /uploads: 用户上传文件
• /processed: 处理后的文本文件
• /reports: 生成的报告
• /archive: 已完成任务的存档

工作流程

1. 文档转换 → 使用 document-converter skill
2. 内容分析 → 委派给 content-analyzer subagent
3. 报告生成 → 使用 report-generator skill

   文件:
   .claude/skills/document-converter/SKILL.md
   
   
   
   

   — name: document-converter description: 将 PDF、Word、Excel 文档转换为文本。当需要读取文档附件、分析文件或从文档中提取内容时使用。 —

文档转换 Skill

功能

将多种格式的文档转换为纯文本,方便后续分析。

支持格式

• PDF (.pdf)
• Word (.docx, .doc)
• Excel (.xlsx, .xls)

使用方法

转换单个文件

“bash python scripts/convert.py

python scripts/convert.py --batch 
   
    
      
       
     

转换后的文本文件,保留基本结构和格式。

• 不支持的格式:返回错误提示
• 损坏的文件:尝试部分恢复,记录日志
• 加密文件:提示需要密码

输入: contract.pdf 输出: contract.txt (包含合同全文)

配套脚本:.claude/skills/document-converter/scripts/convert.py`

”`python #!/usr/bin/env python3 import sys import mammoth from pypdf import PdfReader import pandas as pd

def convert_pdf(input_path, output_path):

"""转换 PDF 为文本""" reader = PdfReader(input_path) text = "\n\n".join([page.extract_text() for page in reader.pages]) with open(output_path, 'w', encoding='utf-8') as f: f.write(text) 

def convert_docx(input_path, output_path):

"""转换 Word 为文本""" with open(input_path, "rb") as docx_file: result = mammoth.extract_raw_text(docx_file) with open(output_path, 'w', encoding='utf-8') as f: f.write(result.value) 

def convert_excel(input_path, output_path):

"""转换 Excel 为文本""" df = pd.read_excel(input_path) with open(output_path, 'w', encoding='utf-8') as f: f.write(df.to_string()) 

if name == “main”:

input_file = sys.argv[1] output_file = sys.argv[2] if input_file.endswith('.pdf'): convert_pdf(input_file, output_file) elif input_file.endswith('.docx'): convert_docx(input_file, output_file) elif input_file.endswith('.xlsx'): convert_excel(input_file, output_file) else: print(f"不支持的格式: {input_file}") sys.exit(1) 

文件:
.claude/agents/content-analyzer.md

— name: content-analyzer description: 深度分析文档内容,提取关键信息、数据统计和见解。当需要分析大量文本、提取模式或进行内容理解时使用。

tools: Read, Grep, Glob, Bash

内容分析专家

你是一位专业的内容分析师,擅长从大量文本中提取有价值的信息。

你的职责

1. 内容理解

• 阅读并理解文档的整体结构
• 识别主要主题和次要主题
• 提取关键论点和结论

2. 数据提取

• 识别并提取:
  • 数字和统计数据
  • 日期和时间线
  • 人名、地名、组织
  • 关键术语和定义

3. 模式识别

• 查找重复出现的概念
• 识别异常或矛盾
• 发现潜在的关联关系

4. 质量评估

• 检查信息完整性
• 标记模糊或缺失的数据
• 评估内容的可信度

工作流程

1. 初步扫描
   • 使用 Glob 找到所有相关文件
   • 使用 Read 读取文件内容
   • 构建文档结构图
2. 深度分析
   • 使用 Grep 搜索关键模式
   • 提取结构化数据
   • 建立实体关系
3. 综合报告
   • 汇总主要发现
   • 列出关键指标
   • 提出改进建议

输出格式

”`json { “summary”: “文档主要内容概述”, “key_findings”: [

"发现1", "发现2" 

], “statistics”: {

"total_words": 5000, "key_terms": {...} 

}, “concerns”: [

"需要关注的问题" 

], “recommendations”: [

"建议1", "建议2" 

] }

• 只读分析,不修改任何文件
• 如遇加密或损坏文件,记录并跳过
• 分析时长超过 5 分钟时,提供中间进度更新

阶段 5: 创建协同工作的 Skill

文件: .claude/skills/report-generator/SKILL.md

”`markdown

name: report-generator

description: 根据分析结果生成标准化的 Markdown 或 HTML 报告。当内容分析完成后需要生成报告时使用。

报告生成器

功能

将分析结果转换为专业的报告文档。

报告模板

标准分析报告

”`markdown

文档分析报告

生成时间: {timestamp} 分析文档: {filename}

执行摘要

{summary}

关键发现

{key_findings}

统计数据

{statistics}

需要关注的问题

{concerns}

建议

{recommendations}

本报告由 Claude Code 自动生成

python generate_report.py –input analysis.json –output report.md 

python generate_report.py –input analysis.json –output report.html –format html

• –template: 使用自定义模板
• –style: 应用样式表 (仅 HTML)
• –lang: 报告语言 (zh/en)

完整案例示范

场景:技术文档审查系统

需求: 自动审查技术文档,检查代码示例、验证链接、评估写作质量

1. 项目拆分方案

CLAUDE.md (项目规范) ↓ Skills (可复用工具):

• code-formatter: 格式化代码片段
• link-checker: 验证文档中的链接
• style-checker: 检查写作风格 ↓ Subagents (专业审查员):
• technical-reviewer: 审查技术准确性
• docs-editor: 审查写作质量和一致性
• code-reviewer: 审查代码示例

# 2. 实现代码

CLAUDE.md: “`markdown

技术文档审查系统

审查标准

• 代码必须可执行且有注释
• 所有链接必须有效
• 遵循 Google 开发者文档风格指南

审查流程

1. 运行 link-checker skill → 验证所有 URL
2. 运行 code-formatter skill → 标准化代码格式
3. 启动 technical-reviewer subagent → 审查技术内容
4. 启动 docs-editor subagent → 审查写作质量
5. 汇总所有发现 → 生成审查报告

质量等级

• Critical: 必须修复才能发布
• Warning: 建议修复
• Info: 可选改进

  Skill 示例 -
  .claude/skills/link-checker/SKILL.md:
  
  
  
  

  — name: link-checker description: 验证文档中的所有 HTTP/HTTPS 链接是否有效。当需要检查文档链接有效性时使用。 allowed-tools: Read, Bash —

链接检查器

检查内容

• HTTP/HTTPS 链接有效性
• 锚点链接是否指向存在的章节
• 相对路径文件是否存在

使用

”`bash

检查单个文件

python check_links.py

检查整个目录

python check_links.py –recursive

{ “valid_links”: [”https://example.com”], “broken_links”: [

{ "url": "https://broken.com", "location": "line 45", "error": "404 Not Found" } 

"Anchor #section-3 not found in document" 

Subagent 示例 - .claude/agents/docs-editor.md:

# Skill 描述要简洁 description: 转换 PDF 为文本

# 不要做:

# ❌ 糟糕的描述 description: 处理文件

问题:在主对话中让 Claude 阅读大量文件进行分析 结果:上下文窗口被污染,后续对话质量下降

你有一个任务需要完成:

↓ 

├─ 一次性 → 直接让 Claude 在主对话中完成 └─ 可重复 → 继续 ↓ 任务需要读取大量文件吗? ├─ 是 → 使用 Subagent └─ 否 → 继续 ↓ 任务是纯工具函数还是复杂决策? ├─ 工具函数 → 使用 Skill └─ 复杂决策 → 使用 Subagent 

# Claude 可以同时运行多个 Subagent “启动三个并行 subagent: