Skills实战案例

前面分别讲了 Skills 的结构、触发机制和资源使用。本篇用一个完整的实战项目串起所有概念：构建一个博客写作 Skill 套件。

1. 需求分析

我们要为博客写作建立一套 Skill，让 Claude 能：

根据主题生成文章大纲
按既定风格写文章初稿
对已有文章做编辑润色
检查文章的 SEO 友好度
生成配套的元信息（描述、标签、封面文案）

每个能力都是一个独立 Skill，协作完成完整工作流。

2. 项目结构

~/.claude/skills/
├── blog-outline/              # 生成文章大纲
│   └── SKILL.md
├── blog-writer/               # 写文章初稿
│   ├── SKILL.md
│   ├── reference/
│   │   └── style-guide.md
│   └── templates/
│       └── article.md.tpl
├── blog-editor/               # 编辑润色
│   └── SKILL.md
├── blog-seo/                  # SEO 检查
│   ├── SKILL.md
│   └── scripts/
│       └── seo_check.py
└── blog-meta/                 # 元信息生成
    └── SKILL.md

3. Skill 1：blog-outline（生成大纲）

~/.claude/skills/blog-outline/SKILL.md：

---
name: blog-outline
description: 当用户提出博客主题、想法、要写一篇文章时使用，生成结构清晰的大纲
---

# 博客大纲生成器

根据用户提供的主题，生成一份适合个人技术博客的大纲。

## 步骤

1. 询问主题（如果用户没说清）
2. 询问目标读者（初学者 / 进阶 / 专家）
3. 确认文章定位（教程 / 经验分享 / 深度分析）
4. 输出三层大纲

## 大纲结构

# 标题（2-3 个备选）

## 引言
- 钩子：1 句话引起兴趣
- 核心价值：读完能获得什么

## 主体（3-5 个二级标题）
### 章节 1：xxx
- 要点 1
- 要点 2

### 章节 2：xxx
...

## 总结
- 3-5 个要点

## 推荐字数：xxxx 字

## 写作建议

- 每个章节给 2-3 个具体要点，方便后续展开
- 标题要具体，避免"概述"、"简介"这种模糊词
- 给 2-3 个备选标题，让用户选择

4. Skill 2：blog-writer（写初稿）

~/.claude/skills/blog-writer/SKILL.md：

---
name: blog-writer
description: 当用户提供大纲或主题要求"写一篇博客"、"生成初稿"、"展开成文章"时使用，按个人技术博客风格输出 Markdown
---

# 博客初稿生成器

根据大纲或主题，生成一篇可发布的博客文章初稿。

## 步骤

1. 如果用户没提供大纲，先调用 `blog-outline` skill 生成
2. 按 [reference/style-guide.md](reference/style-guide.md) 的风格规范写作
3. 使用 [templates/article.md.tpl](templates/article.md.tpl) 作为基础模板
4. 输出完整 Markdown，含 frontmatter

## 风格速览

- **口吻**：朋友间分享经验，不端架子
- **段落**：3-5 行最佳，避免大段
- **代码**：每个核心概念配 1 个最小可运行代码
- **小标题**：用数字开头（### 1. xxx），便于扫读

## 输出要求

- frontmatter 包含 title、date、tags
- 文章末尾有"总结"，3-5 个要点
- 不出现 emoji（除非用户要求）

reference/style-guide.md：

# 博客写作风格指南

## 语气

- 用"我们"代替"你"，营造共同探索的感觉
- 避免"实际上"、"显而易见"这种态度词
- 直接给结论，不要绕弯子

## 段落

- 每段 3-5 行
- 每段一个观点
- 用过渡词（接下来、然后、不过）让上下文衔接

## 代码示例

- 优先用真实场景而非 foo/bar
- 代码不超过 30 行，太长拆分
- 关键行加注释解释"为什么"，不解释"做什么"

## 表格

- 列名简洁
- 优先用表格替代长列表
- 不要超过 4 列

## 标题

- ### 1. 简洁有力
- ### 2. 含数字、动词更好
- ❌ "关于 XXX 的一些思考"
- ✅ "为什么 XXX 比 YYY 快 10 倍"

templates/article.md.tpl：

---
title: {{title}}
date: {{date}}
tags: [{{tags}}]
---

{{开场白：1-2 句话点明文章核心价值}}

### 1. {{第一个章节标题}}

{{正文}}

```{{language}}
{{代码示例}}
```

### 2. {{第二个章节标题}}

{{正文}}

...

### 总结

- {{要点 1}}
- {{要点 2}}
- {{要点 3}}

5. Skill 3：blog-editor（编辑润色）

~/.claude/skills/blog-editor/SKILL.md：

---
name: blog-editor
description: 当用户要求"润色"、"改一改"、"优化文字"、"看看哪里写得不好" 已有博客文章时使用
---

# 博客编辑器

对已写好的博客文章进行润色和改进。

## 检查清单

按以下维度逐项检查：

### 1. 标题
- [ ] 是否具体（不是"关于 XXX 的一些思考"）
- [ ] 是否吸引人（有数字、问题、对比）
- [ ] 是否准确反映内容

### 2. 开篇
- [ ] 第一段是否说清楚"读这篇能得到什么"
- [ ] 是否有钩子（数据、故事、争议）
- [ ] 不超过 3 段

### 3. 段落
- [ ] 每段是否聚焦一个观点
- [ ] 是否有过长的段落（> 6 行）
- [ ] 段落之间是否有过渡

### 4. 代码
- [ ] 示例是否真实可运行
- [ ] 是否过长可以拆分
- [ ] 关键逻辑是否有注释

### 5. 词汇
- [ ] 有无重复用词
- [ ] 有无 AI 写作味（如"实际上"、"显而易见"、"让我们"）
- [ ] 中文标点是否正确

### 6. 结尾
- [ ] 是否有总结
- [ ] 总结是否在 3-5 个要点

## 输出格式

```
## 总体评价
（1-2 句话）

## 修改建议
1. [位置] 原文 → 改为 → 原因
2. ...

## 修改后版本
（完整修改后的 Markdown）
```

6. Skill 4：blog-seo（SEO 检查）

~/.claude/skills/blog-seo/SKILL.md：

---
name: blog-seo
description: 检查博客文章的 SEO 友好度时使用，包括标题、描述、关键词、可读性等
---

# 博客 SEO 检查

对文章的 SEO 维度进行客观检查，给出优化建议。

## 步骤

1. 读取用户提供的 Markdown 文件
2. 执行检查脚本：

   ```bash
   python <skill-dir>/scripts/seo_check.py <文件路径>
   ```

3. 根据脚本输出（JSON 格式），整理成可读报告

## 检查项目

- 标题长度（推荐 30-60 字符）
- meta description 长度（推荐 120-160 字符）
- H1 标签数量（应该 1 个）
- H2/H3 层级是否合理
- 内链数量（>= 2 个推荐）
- 图片是否有 alt
- 关键词密度
- Markdown 链接格式

## 输出

每项给出：✅ 符合 / ⚠️ 警告 / ❌ 严重问题

最后给一个综合分数（满分 100）和**最优先**的 3 个改进点。

scripts/seo_check.py：

import sys
import re
import json
from pathlib import Path

def check_seo(file_path):
    content = Path(file_path).read_text(encoding="utf-8")

    # 提取 frontmatter
    fm_match = re.search(r"^---\n(.*?)\n---", content, re.DOTALL)
    frontmatter = fm_match.group(1) if fm_match else ""
    body = content[fm_match.end():] if fm_match else content

    # 标题
    title_match = re.search(r"^title:\s*(.+)$", frontmatter, re.MULTILINE)
    title = title_match.group(1).strip() if title_match else ""

    # 描述
    desc_match = re.search(r"^description:\s*(.+)$", frontmatter, re.MULTILINE)
    description = desc_match.group(1).strip() if desc_match else ""

    # 标题层级
    h1_count = len(re.findall(r"^# ", body, re.MULTILINE))
    h2_count = len(re.findall(r"^## ", body, re.MULTILINE))
    h3_count = len(re.findall(r"^### ", body, re.MULTILINE))

    # 链接
    internal_links = len(re.findall(r"\[.+?\]\((?!http)", body))
    external_links = len(re.findall(r"\[.+?\]\(https?://", body))

    # 图片
    images = re.findall(r"!\[(.*?)\]\(", body)
    images_no_alt = sum(1 for alt in images if not alt.strip())

    # 字数
    word_count = len(re.findall(r"[一-龥]", body)) + len(re.findall(r"\b\w+\b", body))

    return {
        "title": {"value": title, "length": len(title)},
        "description": {"value": description, "length": len(description)},
        "headings": {"h1": h1_count, "h2": h2_count, "h3": h3_count},
        "links": {"internal": internal_links, "external": external_links},
        "images": {"total": len(images), "missing_alt": images_no_alt},
        "word_count": word_count,
    }

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(json.dumps({"error": "请提供文件路径"}))
        sys.exit(1)
    result = check_seo(sys.argv[1])
    print(json.dumps(result, ensure_ascii=False, indent=2))

7. Skill 5：blog-meta（元信息生成）

~/.claude/skills/blog-meta/SKILL.md：

---
name: blog-meta
description: 当文章写完后用户需要生成元信息（描述、标签、SEO description、社交媒体文案）时使用
---

# 博客元信息生成

为已完成的博客文章生成各种元信息。

## 输入

- 完整的文章内容（Markdown）

## 输出

```yaml
# 用于 frontmatter
title: {{保留原标题或优化}}
description: {{120-160 字符的 SEO 描述}}
tags: [{{3-5 个标签}}]
keywords: [{{5-8 个关键词}}]

# 用于社交媒体
twitter:
  text: {{推文，280 字符内，含 1-2 个相关 hashtag}}

# 封面建议
cover:
  type: {{抽象/截图/示意图}}
  prompt: {{如果是 AI 生成图，给出 prompt}}
```

## 要求

- description 要有 hook，不是简单总结
- tags 用读者会搜的词，不是自定义词
- twitter 文案要有诱因，不剧透核心内容

8. 实际使用流程

配置好 5 个 Skill 后，写一篇博客的流程：

步骤 1：启动

我想写一篇关于 Python 协程性能的博客

Claude 触发 blog-outline，输出大纲方案。

步骤 2：确认大纲后展开

大纲不错，按这个写吧

Claude 触发 blog-writer，按风格指南输出完整初稿（Markdown）。

步骤 3：编辑

看看哪里写得不够好，帮我润色

Claude 触发 blog-editor，按检查清单逐项分析，输出修改建议和润色后版本。

步骤 4：SEO 检查

把文件保存为 post.md，再检查一下 SEO

Claude 保存文件，然后触发 blog-seo，运行 seo_check.py，给出报告。

步骤 5：生成元信息

帮我加上 frontmatter 和社交媒体文案

Claude 触发 blog-meta，生成完整元信息。

9. 协作模式的好处

观察这个例子，每个 Skill 都很专一：

blog-outline 只管大纲
blog-writer 只管初稿
blog-editor 只管编辑
blog-seo 只管检查
blog-meta 只管元信息

这样设计的好处：

好处	说明
复用性强	写其他文章也能用其中几个
触发准确	description 范围明确，不互相干扰
维护容易	改写作风格只动 blog-writer，不影响其他
协作灵活	可以只用大纲不用初稿，按需组合

10. 进阶扩展

这套 Skill 还能继续完善：

1. 多语言支持

加 blog-translator Skill，从中文翻译成英文（或反向），用于 GitHub Pages、海外发布。

2. 系列文章管理

加 blog-series Skill，管理"X 系列教程"中的多篇文章关联。

3. 引用检查

加 blog-fact-check Skill，检查引用的版本号、官方链接是否仍然有效。

4. 配图生成

加 blog-illustration Skill，调用 DALL-E / Midjourney API 生成配图。

5. 发布自动化

加 blog-publish Skill，配合 git Tool 自动 commit + push 到博客仓库。

11. 项目级 Skill

如果你的博客本身是个 git 项目，可以把这些 Skill 放进项目的 .claude/skills/ 中：

my-blog-repo/
├── .claude/
│   └── skills/
│       ├── blog-outline/
│       ├── blog-writer/
│       └── ...
└── posts/
    └── ...

提交到 git 后：

团队成员 clone 后立即可用
不会污染个人 Skill 目录
项目特定的风格只在该项目下生效

12. 经验总结

1. 拆分粒度

每个 Skill 解决一类问题，不要做"万能 Skill"。粒度太粗会让 description 写不清楚，触发不精准。

2. 利用协作

主 Skill 调用其他 Skill 是常见模式（blog-writer 调用 blog-outline），用 ## 步骤 显式说明。

3. 脚本承担计算

需要客观数据的部分（SEO 字符数、链接统计）一定用脚本，不要让模型估算。

4. 风格指南独立

把"写作风格"这种相对稳定的内容放 reference/，主 SKILL.md 引用。改风格只动一个文件。

5. 模板是底线

模板提供"最差也不至于太离谱"的兜底，让产出有下限保证。

总结

复杂场景下用 多 Skill 协作 比 单 Skill 大而全 更好
拆分原则：每个 Skill 一个明确的任务，description 范围清晰
通过 ## 步骤 让 Skill 之间协作（如先调大纲再写正文）
用脚本承担确定性计算（SEO 字符数、统计），用 reference 沉淀稳定知识
项目级 Skill（.claude/skills/）适合团队共享，可提交到 git
设计完后用真实工作流走一遍，验证触发是否准确、输出是否符合预期