Skills 实战:让 AI 成为你的领域专家

你: "帮我分析这个 BigQuery 数据,记住要排除测试账户,使用 user_metrics 表..."
Claude: "好的,我来分析..."
 
[第二天]
你: "再帮我分析一次销售数据,还是那个表,记得排除测试账户..."
Claude: "好的,我来分析..."  # 😓 又要重复一遍

你: "帮我处理这个 PDF 表单,PDF 的表单字段结构是..."
Claude: "明白了"
 
[一周后]
你: "再处理一个 PDF 表单..."
Claude: "请告诉我 PDF 表单的结构"  # 😓 忘记了

你: "生成 API 文档,记得包含请求示例、响应格式、错误码..."
Claude: "好的" # ✅ 这次做得很好
 
[下次]
你: "再生成一份 API 文档"
Claude: [生成的文档] # ❌ 这次忘记了错误码部分

假设你有 10 个 Skills,每个包含 5000 tokens 的详细指导...
总共: 50,000 tokens
 
但你可能只需要使用其中 1-2 个 Skill!
浪费: 40,000+ tokens(80% 的上下文窗口!)

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
             Use when working with PDF files or when the user mentions PDFs, forms,
             or document extraction.
---

# PDF Processing
 
## Quick start
 
Use pdfplumber to extract text from PDFs:
 
\`\`\`python
import pdfplumber
 
with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`
 
For advanced form filling, see [FORMS.md](FORMS.md).

pdf-skill/
├── SKILL.md          # 主指令文件(第二级)
├── FORMS.md          # 表单填写指南(按需读取)
├── REFERENCE.md      # 详细 API 参考(按需读取)
└── scripts/
    └── fill_form.py  # 工具脚本(执行时不加载代码)

┌─────────────────────────────────────────┐
│ 步骤 1: Claude 检查所有 Skill 的元数据 │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│ 匹配到 pdf-processing Skill             │
│ description 包含 "Extract text from PDF"│
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│ 步骤 2: 加载 SKILL.md 的指令内容        │
│ (~3k tokens)                            │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│ 步骤 3: Claude 发现需要表单填写         │
│ 读取 FORMS.md (~2k tokens)              │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│ 总 Token 消耗: 约 5k tokens             │
│ 其他 9 个 Skills: 0 tokens(未加载)      │
└─────────────────────────────────────────┘

❌ 传统方式: 10 个 Skills × 5k = 50k tokens
✅ 渐进式披露: 只加载 1 个 Skill = 5k tokens
节省: 45k tokens (90% 的上下文!)

my-skill/
└── SKILL.md          # 唯一必需的文件

---
name: code-review-checklist
description: Provides a code review checklist for pull requests. Use when reviewing code or when the user asks for code review guidelines.
---
 
# Code Review Checklist
 
When reviewing code, check:
 
1. **Functionality**: Does the code do what it's supposed to?
2. **Readability**: Is the code easy to understand?
3. **Tests**: Are there appropriate tests?
4. **Performance**: Are there any obvious performance issues?
5. **Security**: Are there any security vulnerabilities?
 
For each item, provide specific feedback with examples.

pdf-processing-skill/
├── SKILL.md              # 核心指令(必需)
├── FORMS.md              # 表单填写详细指南
├── REFERENCE.md          # PDF 库 API 参考
├── EXAMPLES.md           # 常见用例示例
└── scripts/
    ├── analyze_form.py   # 分析表单工具
    ├── fill_form.py      # 填写表单工具
    └── validate.py       # 验证输出工具

---
name: skill-name              # 必填
description: Skill description # 必填
---

processing-pdfs
analyzing-spreadsheets
reviewing-code
managing-databases

helper          # 太模糊
utils           # 不知道干什么
tool            # 功能不明确

系统提示: "You are Claude, an AI assistant..."
Skill description: "I can help you process PDFs"  # ❌ 第一人称,视角冲突!

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
             Use when working with PDF files or when the user mentions PDFs, forms,
             or document extraction.
---

❌ description: I can help you process Excel files  # 第一人称
❌ description: You can use this to process Excel   # 第二人称
❌ description: Helps with documents                # 过于模糊

mkdir my-bigquery-skill
cd my-bigquery-skill
touch SKILL.md

---
name: bigquery-analytics
description: Analyze BigQuery data from the user_metrics and sales tables. Use when the user asks about data analysis, metrics, or BigQuery queries. Always exclude test accounts and apply standard 
    date filters.
---

# BigQuery Analytics
 
## Database Schema
 
### user_metrics table
- user_id (STRING): Unique user identifier
- event_date (DATE): Event date
- metrics_value (FLOAT): Metric value
- account_type (STRING): "production" or "test"
 
### sales table
- order_id (STRING): Order identifier
- user_id (STRING): User ID (foreign key to user_metrics)
- amount (FLOAT): Order amount
- order_date (DATE): Order date
 
## Standard Filtering Rules
 
**Always apply these filters:**
1. Exclude test accounts: `WHERE account_type = 'production'`
2. Date range: Default to last 30 days unless specified
3. Remove null values: `WHERE metrics_value IS NOT NULL`
 
## Query Patterns
 
### Pattern 1: User activity analysis
\`\`\`sql
SELECT
  event_date,
  COUNT(DISTINCT user_id) as active_users,
  AVG(metrics_value) as avg_metric
FROM user_metrics
WHERE account_type = 'production'
  AND event_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
GROUP BY event_date
ORDER BY event_date;
\`\`\`
 
### Pattern 2: Sales analysis
\`\`\`sql
SELECT
  DATE_TRUNC(order_date, MONTH) as month,
  COUNT(*) as order_count,
  SUM(amount) as total_revenue
FROM sales s
JOIN user_metrics u ON s.user_id = u.user_id
WHERE u.account_type = 'production'
GROUP BY month
ORDER BY month;
\`\`\`
 
## Important Notes
 
- **Performance**: Always use partitioned date fields in WHERE clause
- **Costs**: Preview query cost before running on large datasets
- **Timezone**: All dates are in UTC

## Extract PDF Text
 
Use pdfplumber for text extraction:
 
\`\`\`python
import pdfplumber
 
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`

## Extract PDF Text
 
PDF(便携式文档格式)是一种常见的文件格式,包含文本、图像等内容。
要从 PDF 中提取文本,你需要使用一个库。有很多 PDF 处理库可用,
但我们推荐 pdfplumber,因为它易于使用且能处理大多数情况。
首先,你需要使用 pip 安装它。然后你可以使用下面的代码...

## Code Review Process
 
1. Analyze code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify compliance with project standards

## Generate Report
 
Use this template and customize as needed:
 
\`\`\`python
def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
    # Optionally include visualizations
\`\`\`

## Database Migration
 
Execute this script strictly:
 
\`\`\`bash
python scripts/migrate.py --verify --backup
\`\`\`
 
Do not modify the command or add extra parameters.

SKILL.md (简要指南)
   ↓ 引用
[FORMS.md] [REFERENCE.md] [EXAMPLES.md]

# PDF Processing
 
## Quick Start
 
Use pdfplumber to extract text:
\`\`\`python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`
 
## Advanced Features
 
**Form Filling**: See [FORMS.md](FORMS.md) for complete guide
**API Reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

bigquery-skill/
├── SKILL.md              # 概述和导航
└── reference/
    ├── finance.md        # 财务指标
    ├── sales.md          # 销售数据
    ├── product.md        # 产品分析
    └── marketing.md      # 营销活动

# BigQuery Analytics
 
## Domain Reference
 
- **Finance Metrics**: See [reference/finance.md](reference/finance.md)
- **Sales Data**: See [reference/sales.md](reference/sales.md)
- **Product Analytics**: See [reference/product.md](reference/product.md)
- **Marketing Campaigns**: See [reference/marketing.md](reference/marketing.md)

# DOCX Processing
 
## Create Documents
 
Use docx-js to create new documents. See [DOCX-JS.md](DOCX-JS.md).
 
## Edit Documents
 
For simple edits, modify XML directly.
 
**Track Changes**: See [REDLINING.md](REDLINING.md)
**OOXML Details**: See [OOXML.md](OOXML.md)

## PDF Form Filling Workflow
 
Copy this checklist and track progress:
 
\`\`\`
Task Progress:
- [ ] Step 1: Analyze form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
\`\`\`
 
**Step 1: Analyze Form**
 
Run: `python scripts/analyze_form.py input.pdf`
 
This extracts form fields and their locations, saving to `fields.json`.
 
**Step 2: Create Field Mapping**
 
Edit `fields.json` to add values for each field.
 
**Step 3: Validate Mapping**
 
Run: `python scripts/validate_fields.py fields.json`
 
Fix any validation errors before proceeding.
 
**Step 4: Fill Form**
 
Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
 
**Step 5: Verify Output**
 
Run: `python scripts/verify_output.py output.pdf`
 
If validation fails, return to Step 2.

## Document Editing Flow
 
1. Make edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
   - Review error messages carefully
   - Fix issues in XML
   - Run validation again
4. **Only proceed when validation passes**
5. Repack: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test output document

如果你在 2025 年 8 月之前做这件事,使用旧 API。
2025 年 8 月之后,使用新 API。

## Current Method
 
Use v2 API endpoint: `api.example.com/v2/messages`
 
## Legacy Patterns
 
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
 
v1 API uses: `api.example.com/v1/messages`
 
This endpoint is no longer supported.
</details>

def process_file(path):
    """处理文件,如果不存在则创建。"""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # 创建默认内容而非失败
        print(f"文件 {path} 未找到,创建默认文件")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # 提供替代方案而非失败
        print(f"无法访问 {path},使用默认值")
        return ''

def process_file(path):
    # 直接失败,让 Claude 自己想办法
    return open(path).read()

## Tool Scripts
 
**analyze_form.py**: Extract all form fields from PDF
 
\`\`\`bash
python scripts/analyze_form.py input.pdf > fields.json
\`\`\`
 
Output format:
\`\`\`json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
\`\`\`
 
**validate_boxes.py**: Check for boundary box overlaps
 
\`\`\`bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
\`\`\`
 
**fill_form.py**: Apply field values to PDF
 
\`\`\`bash
python scripts/fill_form.py input.pdf fields.json output.pdf
\`\`\`

分析 → 创建计划文件 → 验证计划 → 执行 → 验证输出

## Bulk Form Update Workflow
 
**Step 1: Analyze**
- Extract current form fields
- Save to `current_fields.json`
 
**Step 2: Create Change Plan**
- Based on spreadsheet, create `changes.json`:
  \`\`\`json
  {
    "field_updates": [
      {"field": "customer_name", "value": "John Doe"},
      {"field": "order_total", "value": "1250.00"}
    ]
  }
  \`\`\`
 
**Step 3: Validate Plan**
- Run: `python scripts/validate_changes.py changes.json`
- Script checks:
  - All referenced fields exist
  - Values are in correct format
  - No conflicts
- **Only proceed if validation passes**
 
**Step 4: Execute**
- Apply changes: `python scripts/apply_changes.py changes.json`
 
**Step 5: Verify Output**
- Run: `python scripts/verify_output.py output.pdf`

❌ 模糊: "Validation failed"
✅ 清晰: "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed"

ServerName:tool_name

## Query Database Schema
 
Use the BigQuery:bigquery_schema tool to retrieve table schema.
 
\`\`\`
Use tool: BigQuery:bigquery_schema
Parameters: {"table": "user_metrics"}
\`\`\`
 
## Create GitHub Issue
 
Use the GitHub:create_issue tool to create an issue.
 
\`\`\`
Use tool: GitHub:create_issue
Parameters: {"title": "Bug report", "body": "Description"}
\`\`\`

参见 scripts\helper.py
参见 reference\guide.md

参见 scripts/helper.py
参见 reference/guide.md

你可以使用 pypdf,或 pdfplumber,或 PyMuPDF,或 pdf2image,
或 pikepdf,或 PyPDF2,或 pdfrw,或 pdfminer...

使用 pdfplumber 进行文本提取:
\`\`\`python
import pdfplumber
\`\`\`
 
对于需要 OCR 的扫描 PDF,改用 pdf2image 配合 pytesseract。

SKILL.md → advanced.md → details.md → examples.md

SKILL.md
  ↓ 直接引用
[ADVANCED.md] [DETAILS.md] [EXAMPLES.md]

PDF(Portable Document Format,便携式文档格式)是 Adobe 公司
开发的一种文件格式,可以在不同操作系统上保持一致的显示效果。
PDF 文件包含文本、图像、矢量图形等多种内容类型...

使用 pdfplumber 提取 PDF 文本。

description: I can help you process Excel files and generate reports.

description: Process Excel files and generate reports. Use when working with spreadsheets or when the user mentions Excel, CSV, or data analysis.