# https://github.com/BrightSiteHQ/skills 项目说明书

生成时间：2026-06-01 01:07:07 UTC

## 目录

- [项目概述](#page-overview)
- [安装指南](#page-installation)
- [MCP服务器集成](#page-mcp-integration)
- [批量SEO审计技能](#page-bulk-seo-audit)
- [程序化SEO页面生成](#page-generate-location-pages)
- [CSV重定向映射](#page-redirect-map)
- [WordPress博客迁移](#page-migrate-wordpress)
- [大纲转博客文章](#page-blog-post-from-outline)
- [客户端交接检查清单](#page-client-handoff)
- [贡献指南](#page-contributing)

<a id='page-overview'></a>

## 项目概述

### 相关页面

相关主题：[安装指南](#page-installation), [MCP服务器集成](#page-mcp-integration)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/BrightSiteHQ/skills/blob/main/CONTRIBUTING.md)
- [skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)
- [skills/client-handoff-checklist/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/client-handoff-checklist/SKILL.md)
- [skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md)
- [skills/generate-location-pages/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/generate-location-pages/SKILL.md)
- [skills/redirect-map-from-csv/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/redirect-map-from-csv/SKILL.md)
</details>

# 项目概述

## 项目简介

BrightSite Skills 是一个面向数字营销代理商的开源 Claude Skills 集合，专注于简化和自动化 BrightSite 网站平台上的日常运营任务。该项目托管于 GitHub 仓库 `BrightSiteHQ/skills`，旨在将重复性的网站管理工作转化为可重复执行的自动化工作流。

每个 Skill 都是一个 Markdown 格式的指令文件，当 AI 助手（如 Claude Code、Claude Desktop 或 Cursor）加载后，能够自动引导完成特定的业务流程，包括博客内容生成、SEO 审计、客户端站点交接检查等。

资料来源：[README.md:1-15]()

## 核心定位与价值

BrightSite Skills 的设计理念围绕三个核心价值主张展开：

**工作流自动化** — 项目将复杂的网站管理操作封装为可执行的标准化流程。例如，从 WordPress 导出文件导入到 BrightSite、批量生成地理位置页面、或执行站点发布前的完整质量检查。这些工作流原本需要多次手动操作，现在可以一键触发。

**质量保障** — 每个 Skill 都内置了反模式检查（Anti-patterns），帮助 AI 避免常见的执行错误。资料表明，项目特别强调“防止模型犯错的类别”，这是 Skill 设计中最有价值的部分。资料来源：[CONTRIBUTING.md:14]()

**客户端交付标准化** — 通过 client-handoff-checklist 等 Skill，代理商可以在站点上线前执行系统化的 QA 检查，确保所有关键配置项（站点标识、SEO 元数据、表单设置等）都已正确完成。

## 技术架构

### MCP 集成架构

BrightSite Skills 的运行依赖于 BrightSite MCP（Model Context Protocol）服务器的集成。MCP 是一个标准化的协议，允许 AI 助手与外部工具和服务进行交互。

```mermaid
graph TD
    A[用户请求] --> B[Claude AI 助手]
    B --> C{已安装的 Skill}
    C -->|匹配触发短语| D[加载 SKILL.md]
    D --> E[解析工作流指令]
    E --> F[MCP 工具调用]
    F --> G[BrightSite MCP Server]
    G --> H[BrightSite API]
    H --> I[执行操作]
    I --> J[返回结果给用户]
```

MCP 服务器作为托管服务运行，无需本地部署。用户只需在 BrightSite 平台注册账号，然后按照安装指南将 MCP 服务器连接到选定的 AI 客户端工具即可。

资料来源：[README.md:28-35]()

### Skill 文件结构

每个 Skill 以统一的 YAML frontmatter 开头，包含元数据定义：

```yaml
---
name: skill-name
description: 技能描述，包含自然语言触发短语列表
---
```

Skill 文件的主体部分包含以下标准章节：

| 章节名称 | 说明 |
|---------|------|
| `# Skill 标题` | 技能的名称和用途 |
| `## When to use this` | 使用场景和触发条件 |
| `## Inputs you need from the user` | 执行所需的用户输入参数 |
| `## Workflow` | 详细的分步操作流程 |
| `## Anti-patterns to avoid` | 需要避免的错误模式 |
| `## Tools used` | 依赖的 MCP 工具列表 |

资料来源：[CONTRIBUTING.md:17-28]()

## 现有 Skill 一览

### 内容创作类

**blog-post-from-outline** 是专门用于将结构化大纲转换为可发布博客文章草稿的 Skill。该 Skill 的设计理念强调“需要用户已完成思考工作”，而非从零开始生成内容。其核心工作流程包括：

1. 确认大纲结构和目标关键词
2. 按照 SEO 最佳实践起草文章
3. 生成元标题、元描述和摘要
4. 向用户展示草稿预览
5. 经用户批准后创建草稿文章

该 Skill 明确禁止自动发布，必须经用户确认后才将内容写入 BrightSite。资料来源：[skills/blog-post-from-outline/SKILL.md:1-85]()

### SEO 优化类

**bulk-seo-audit** 提供批量站点审计功能，可同时检查所有页面和文章的关键 SEO 指标。审计项目按照严重程度分为三个级别：

| 严重级别 | 检查项目 | 影响 |
|---------|---------|------|
| Critical（严重） | meta_title 为空或超过60字符、meta_description 缺失、slug 包含非法字符 | 直接影响搜索引擎排名 |
| Warning（警告） | meta_title 少于30字符、meta_description 长度超出范围 | 可能影响点击率 |
| Info（信息） | slug 过长或包含停用词 | 次要优化项 |

资料来源：[skills/bulk-seo-audit/SKILL.md:1-80]()

**generate-location-pages** 面向程序化 SEO 场景，允许用户通过 CSV 数据批量生成地理位置落地页。该 Skill 特别强调内容质量控制，要求每个页面至少包含 2-3 个地点特定的替换内容，而非简单的城市名称替换，以避免 Google 的低质量内容惩罚。

资料来源：[skills/generate-location-pages/SKILL.md:1-100]()

### 站点管理类

**client-handoff-checklist** 是站点上线前的必执行 QA 工具，涵盖以下检查维度：

- 站点身份配置（标题、Logo、业务类型）
- 页面状态检查（首页标识、草稿状态、未发布变更）
- SEO 元数据完整性
- 错误页面配置
- 博客设置验证
- 表单配置和收件人设置
- 重定向规则
- 分析工具集成

资料来源：[skills/client-handoff-checklist/SKILL.md:1-90]()

**redirect-map-from-csv** 用于批量创建 URL 重定向规则。当网站发生迁移或 URL 结构变更时，该 Skill 可快速将电子表格中的旧 URL 映射到新 URL。

### WordPress 迁移类

项目中包含专门的 WordPress 迁移 Skill，用于将 WordPress 博客导出文件转换为 BrightSite 格式并批量创建文章。该工作流通常包括数据转换、内容清洗、媒体处理和批量导入等步骤。

## 工作流设计模式

### 确认-执行-审批模式

BrightSite Skills 普遍采用「确认后再执行」的工作流设计。对于任何可能产生不可逆影响（如生成大量页面、发布内容）的操作，Skill 都会先展示预览结果，等待用户明确批准后才继续执行。

以 generate-location-pages 为例，其标准工作流程为：

1. 展示将创建的页面数量和 CSV 首行数据
2. 渲染第一个页面的 HEEx 模板、meta 标题和 slug
3. 等待用户回复「yes, generate them」
4. 仅生成第一个样本页面供审核
5. 用户确认后批量生成其余页面

资料来源：[skills/generate-location-pages/SKILL.md:25-45]()

### 草稿优先模式

所有涉及内容创建或页面生成的 Skill 都遵循「草稿优先」原则。即使用户明确要求立即发布，Skill 也会建议先创建草稿，让用户在编辑器中预览和调整后再手动发布。这种设计体现了对内容质量的重视，避免了 AI 错误生成的内容被直接公开。

## 安全与限制

### 边界限制

项目文档明确指出，某些质量检查因 MCP 工具能力限制而无法完全自动化。例如，表单的送达配置和接收人设置等字段目前无法通过 API 读取或修改。对于这类检查，Skill 会明确告知用户需要手动在 UI 中验证。

资料来源：[README.md:20-22]()

### 数据保护

所有 Skill 都以内置的方式强调不要自动修复问题，而是作为检查工具呈现发现的问题，由用户决定如何处理。这避免了 AI 在未授权情况下修改客户网站内容的风险。

## 社区生态

根据社区反馈，Claude Skills 已成为 AI 辅助开发和工作流程自动化的热门方向。社交媒体上关于"50+ Claude skills"、"100+ agentic skills"的讨论热度持续上升，表明这类工作流封装工具在开发者社区中获得了广泛认可。

BrightSite Skills 作为专注于网站运营管理的垂直领域 Skill 集合，其设计思路强调：

- 真实工作流编码而非假设性场景
- 基于现有 MCP 工具实现
- 明确的反模式检查机制

资料来源：[CONTRIBUTING.md:5-12]()

## 快速入门

### 前置要求

1. 拥有 BrightSite 平台账号
2. 在支持的 AI 客户端中配置 BrightSite MCP 连接

### 安装步骤

1. 访问 [onbrightsite.com/mcp](https://onbrightsite.com/mcp) 获取安装指南
2. 按照说明将 MCP 服务器连接到 Claude Code、Claude Desktop 或 Cursor
3. 安装所需的 Skill 文件到对应的 skills 目录
4. 开始使用自然语言触发 Skill 执行任务

### 账户 ID 说明

BrightSite 账户 ID 是未前缀的 NanoID 格式（如 `8fd2k3jq91pn`），可从仪表板 URL 或「设置 → API」页面获取。在执行任何 Skill 时，都需要提供正确的账户 ID。

资料来源：[README.md:52-54]()

## 贡献指南

项目欢迎社区贡献，但设置了明确的准入门槛：

- 必须编码真实执行过的工作流（非假设场景）
- 必须映射到当前 MCP 工具支持的功能
- 必须包含反模式检查部分
- 必须在真实或测试账户上验证

贡献流程：Fork 仓库 → 创建 `skills/<skill-name>/SKILL.md` → 添加 README.md 表格行 → 提交 Pull Request。资料来源：[CONTRIBUTING.md:29-45]()

## 总结

BrightSite Skills 项目为数字营销代理商提供了一个结构化的 AI 辅助工作流框架。通过将常见的网站管理任务封装为可执行的 Skill，代理商能够更高效地管理客户站点，同时确保操作质量和一致性。项目的设计理念强调用户控制、草稿优先和质量保障，是 AI 辅助网站运营领域的优秀实践案例。

---

<a id='page-installation'></a>

## 安装指南

### 相关页面

相关主题：[项目概述](#page-overview), [MCP服务器集成](#page-mcp-integration)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/BrightSiteHQ/skills/blob/main/CONTRIBUTING.md)
- [skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)
- [skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md)
- [skills/client-handoff-checklist/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/client-handoff-checklist/SKILL.md)
- [skills/generate-location-pages/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/generate-location-pages/SKILL.md)

</details>

# 安装指南

本指南涵盖如何安装、配置和使用 BrightSite Skills 技能库，帮助开发者和代理商快速上手并集成到 Claude Code 工作流程中。

## 概述

BrightSite Skills 是一个面向 BrightSite CMS 平台的 Claude Code 技能集合，旨在自动化网站内容管理、SEO 优化和客户交接等常见工作流程。

| 组件 | 说明 |
|------|------|
| 技能数量 | 5+ 个可复用工作流 |
| 依赖项 | Claude Code + BrightSite MCP 服务 |
| 账户标识 | NanoID 格式（如 `8fd2k3jq91pn`） |

资料来源：[README.md:1-18]()

## 前置条件

### 必需环境

| 环境要求 | 版本/说明 |
|---------|-----------|
| Claude Code | 最新版本 |
| BrightSite 账户 | 有效账户（含 Account ID） |
| MCP 连接 | 已配置 `mcp__brightsite__*` 工具 |

### 获取 Account ID

BrightSite Account ID 是未前缀的 NanoID 格式，用于 API 调用身份验证。

获取方式：
1. 登录 BrightSite Dashboard，查看 URL 中的账户标识
2. 或进入 **Settings → API** 查看

资料来源：[README.md:28-29]()

## 安装步骤

### 方式一：克隆仓库

```bash
git clone https://github.com/BrightSiteHQ/skills.git
cd skills
```

仓库结构如下：

```
skills/
├── README.md
├── CONTRIBUTING.md
├── skills/
│   ├── blog-post-from-outline/
│   │   └── SKILL.md
│   ├── bulk-seo-audit/
│   │   └── SKILL.md
│   ├── client-handoff-checklist/
│   │   └── SKILL.md
│   ├── generate-location-pages/
│   │   └── SKILL.md
│   └── redirect-map-from-csv/
│       └── SKILL.md
```

资料来源：[README.md:1-15]()

### 方式二：直接使用技能描述

Claude Code 会自动识别技能的 `description` 字段。当用户使用自然语言描述需求时，系统会根据描述自动触发对应技能。

**触发示例：**

| 用户输入 | 触发技能 |
|---------|---------|
| "Generate location pages for these 40 cities" | generate-location-pages |
| "Run an SEO audit on this site" | bulk-seo-audit |
| "draft a blog post from this outline" | blog-post-from-outline |
| "create a redirect map from CSV" | redirect-map-from-csv |

资料来源：[README.md:20-27]()

## 技能配置

### MCP 工具权限

每个技能依赖特定的 BrightSite MCP 工具。确保以下工具已启用：

| 工具名称 | 用途 |
|---------|------|
| `mcp__brightsite__create_post` | 创建博客草稿 |
| `mcp__brightsite__list_posts` | 列出所有文章 |
| `mcp__brightsite__get_post` | 获取单篇文章详情 |
| `mcp__brightsite__update_post` | 更新文章内容 |
| `mcp__brightsite__create_page` | 创建页面 |
| `mcp__brightsite__list_pages` | 列出所有页面 |
| `mcp__brightsite__get_page` | 获取页面详情 |
| `mcp__brightsite__update_page` | 更新页面内容 |
| `mcp__brightsite__get_site_identity` | 获取站点配置 |
| `mcp__brightsite__publish_post` | 发布文章 |

资料来源：[skills/blog-post-from-outline/SKILL.md:4-11]()

### 环境变量配置

部分技能需要设置账户 ID 参数：

```bash
# 设置默认账户 ID
export BRIGHTSITE_ACCOUNT_ID="your_nanoid_here"
```

或在使用时直接传递：

```
Account ID: 8fd2k3jq91pn
```

资料来源：[README.md:28-29]()

## 可用技能速览

### 1. 博客文章生成

| 属性 | 值 |
|-----|---|
| 技能名 | blog-post-from-outline |
| 输入 | 提纲 + 目标关键词 + 受众描述 |
| 输出 | 带有元数据的草稿文章 |
| 状态 | 始终创建为草稿，不自动发布 |

资料来源：[skills/blog-post-from-outline/SKILL.md:1-3]()

### 2. 批量 SEO 审计

| 属性 | 值 |
|-----|---|
| 技能名 | bulk-seo-audit |
| 输入 | 账户 ID + 审计范围 |
| 输出 | 分级问题报告（Critical/Warning/Info） |
| 支持 | 页面 + 文章双重检查 |

资料来源：[skills/bulk-seo-audit/SKILL.md:1-6]()

### 3. 客户交接清单

| 属性 | 值 |
|-----|---|
| 技能名 | client-handoff-checklist |
| 输入 | 站点身份验证 |
| 输出 | 上线就绪状态报告 |
| 检查项 | 品牌标识、错误页面、分析配置等 |

资料来源：[skills/client-handoff-checklist/SKILL.md:1-5]()

### 4. 地理位置页面生成

| 属性 | 值 |
|-----|---|
| 技能名 | generate-location-pages |
| 输入 | CSV 文件（城市、地区数据） |
| 输出 | 每个城市一个草稿页面 |
| 适用场景 | 程序化 SEO（pSEO）批量建站 |

资料来源：[skills/generate-location-pages/SKILL.md:1-6]()

## 工作流程图

### 技能调用流程

```mermaid
graph TD
    A[用户输入自然语言需求] --> B{Claude Code 匹配技能}
    B -->|匹配成功| C[加载 SKILL.md]
    B -->|无匹配| D[常规对话处理]
    C --> E[收集必需输入]
    E --> F{输入完整?}
    F -->|否| G[请求补充信息]
    G --> E
    F -->|是| H[调用 MCP 工具]
    H --> I[处理响应]
    I --> J[生成输出报告]
    J --> K[返回用户确认]
```

### 博客文章创建流程

```mermaid
graph LR
    A[用户提供提纲] --> B[确认理解: H2结构、关键词、CTA]
    B --> C{用户确认}
    C -->|否| D[调整参数]
    D --> B
    C -->|是| E[撰写文章草稿]
    E --> F[生成元数据]
    F --> G[预览给用户]
    G --> H{用户批准}
    H -->|否| I[迭代修改]
    I --> G
    H -->|是| J[创建草稿文章]
    J --> K[返回文章ID]
```

资料来源：[skills/blog-post-from-outline/SKILL.md:46-77]()

## 验证安装

### 运行交接清单

安装完成后，运行客户端交接清单验证配置：

```
运行客户端交接检查，账户 ID 为 YOUR_ACCOUNT_ID
```

该技能会检查：
- 站点身份是否完整（标题、Logo）
- 必填页面是否存在（首页、404页）
- SEO 元数据配置状态
- 草稿内容占位符问题

资料来源：[skills/client-handoff-checklist/SKILL.md:1-15]()

### 测试 MCP 连接

使用列出工具验证连接：

```bash
# 列出账户下所有页面
mcp__brightsite__list_pages --account_id "YOUR_ACCOUNT_ID"

# 列出账户下所有文章
mcp__brightsite__list_posts --account_id "YOUR_ACCOUNT_ID"
```

## 常见问题

### Q: 技能未触发怎么办？

确保使用自然语言描述需求，技能通过 `description` 字段的关键词匹配触发。

资料来源：[README.md:20-27]()

### Q: Account ID 格式是什么？

BrightSite Account ID 是未前缀的 NanoID，长度约 10-11 字符，例如 `8fd2k3jq91pn`。

资料来源：[README.md:28-29]()

### Q: 如何贡献新技能？

1. Fork 仓库
2. 创建 `skills/<技能名>/SKILL.md` 文件
3. 使用标准 frontmatter 格式
4. 测试通过后提交 PR
5. 更新 README.md 表格

资料来源：[CONTRIBUTING.md:1-18]()

### Q: 技能创建的页面会直接发布吗？

不会。所有技能默认创建草稿状态，用户需在 BrightSite 编辑器中手动审核并发布。

## 下一步

| 任务 | 相关文档 |
|-----|---------|
| 学习贡献流程 | [CONTRIBUTING.md](https://github.com/BrightSiteHQ/skills/blob/main/CONTRIBUTING.md) |
| 浏览全部技能 | [README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md) |
| 快速开始 | 使用任何自然语言需求触发技能 |

---

<a id='page-mcp-integration'></a>

## MCP服务器集成

### 相关页面

相关主题：[项目概述](#page-overview), [安装指南](#page-installation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md)
- [skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)
- [skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md)
- [skills/generate-location-pages/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/generate-location-pages/SKILL.md)
- [skills/client-handoff-checklist/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/client-handoff-checklist/SKILL.md)
- [CONTRIBUTING.md](https://github.com/BrightSiteHQ/skills/blob/main/CONTRIBUTING.md)
</details>

# MCP服务器集成

## 概述

MCP（Model Context Protocol）服务器集成是BrightSite Skills项目的核心基础设施。该项目为运行BrightSite客户端站点的代理公司提供Claude Skills集合，每个技能都通过BrightSite托管的MCP服务器与外部系统进行交互。

MCP服务器作为桥梁，允许AI助手（如Claude Code、Claude Desktop或Cursor）通过标准化协议访问BrightSite平台的各项功能，包括页面管理、博客文章操作、SEO审计和站点配置等。资料来源：[README.md:1-15]()

## 架构设计

### 整体架构

```mermaid
graph TD
    A[用户 / AI助手] --> B[Claude Skills]
    B --> C[BrightSite MCP Server<br/>onbrightsite.com/mcp]
    C --> D[BrightSite API]
    D --> E[客户端网站数据]
    
    F[Skill: blog-post-from-outline] --> C
    G[Skill: bulk-seo-audit] --> C
    H[Skill: generate-location-pages] --> C
    I[Skill: client-handoff-checklist] --> C
```

### MCP工具命名规范

所有MCP工具采用统一的命名格式：`mcp__brightsite__<tool_name>`。这种命名约定确保了技能文件中的工具引用保持一致性。资料来源：[CONTRIBUTING.md:20-22]()

## 可用MCP工具

### 页面管理工具

| 工具名称 | 功能描述 | 关键参数 |
|---------|---------|---------|
| `mcp__brightsite__list_pages` | 获取站点所有页面列表 | `account_id` |
| `mcp__brightsite__get_page` | 获取单个页面详情 | `account_id`, `page_id` |
| `mcp__brightsite__create_page` | 创建新页面（草稿模式） | `account_id`, `title`, `slug`, `heex`, `meta_title`, `meta_description`, `status` |
| `mcp__brightsite__update_page` | 更新现有页面 | `account_id`, `page_id`, 更新字段 |
| `mcp__brightsite__publish_page` | 发布页面 | `account_id`, `page_id` |

资料来源：[skills/generate-location-pages/SKILL.md:50-65]()

### 博客文章工具

| 工具名称 | 功能描述 | 关键参数 |
|---------|---------|---------|
| `mcp__brightsite__list_posts` | 获取博客文章列表 | `account_id` |
| `mcp__brightsite__get_post` | 获取文章详情 | `account_id`, `post_id` |
| `mcp__brightsite__create_post` | 创建新文章（草稿模式） | `account_id`, `title`, `slug`, `content`, `excerpt`, `meta_title`, `meta_description`, `status` |
| `mcp__brightsite__update_post` | 更新现有文章 | `account_id`, `post_id`, 更新字段 |

资料来源：[skills/blog-post-from-outline/SKILL.md:85-95]()

### 站点配置工具

| 工具名称 | 功能描述 |
|---------|---------|
| `mcp__brightsite__get_site_identity` | 获取站点标识信息（logo、favicon、业务类型等） |
| `mcp__brightsite__get_blog_settings` | 获取博客设置（URL前缀等） |

资料来源：[skills/blog-post-from-outline/SKILL.md:93-95]()

## 连接配置

### 前置条件

1. 拥有有效的BrightSite账户
2. 在[onbrightsite.com/mcp](https://onbrightsite.com/mcp)完成MCP服务器安装
3. 将MCP服务器注册为`brightsite`名称

### 安装步骤

1. 访问BrightSite MCP安装页面获取安装代码片段
2. 将代码片段配置到目标AI助手（Claude Code、Claude Desktop或Cursor）
3. 验证连接状态

安装完成后，技能文件中的所有`mcp__brightsite__<tool>`引用将正常工作。资料来源：[README.md:25-35]()

## 账户ID管理

### 账户ID格式

BrightSite账户ID采用未前缀的NanoID格式，示例：`8fd2k3jq91pn`。

### 获取方式

- 仪表板URL中直接可见
- **设置 → API** 页面中可查看

### 使用规范

所有需要账户ID的MCP工具调用都必须提供正确的账户ID作为参数。技能文件中的`YOUR_ACCOUNT_ID`占位符需要替换为实际ID。资料来源：[README.md:50-55]()

## 工具调用限制与最佳实践

### 速率限制

批量操作时建议节流处理，推荐并发量为5个请求/秒，避免触发服务端速率限制。资料来源：[skills/generate-location-pages/SKILL.md:56-58]()

### 避免的错误模式

| 错误模式 | 正确做法 |
|---------|---------|
| 一次请求所有实体（在大型账户上） | 分批处理，每批5个请求 |
| 自动修复而不确认 | 展示变更前后对比，获取明确批准 |
| 信任`has_unpublished_changes: false` | 实际检查内容状态 |
| 生成页面后立即发布大量页面 | 分批发布，数天内完成 |

资料来源：[skills/bulk-seo-audit/SKILL.md:75-80]()

## 内容版本管理

### 页面版本

页面返回两个HEEx版本：
- `heex`：当前线上版本
- `heex_staged`：最新未发布的暂存版本

### 文章版本

文章返回两个内容版本：
- `content`：当前线上内容
- `content_staged`：暂存内容

### 审计策略

审计操作必须同时检查线上版本和暂存版本，因为暂存版本将在下次发布时生效。资料来源：[skills/bulk-seo-audit/SKILL.md:12-20]()

## 元数据字段说明

### 页面元数据

| 字段 | 限制 | 说明 |
|-----|------|------|
| `meta_title` | ≤60字符 | 搜索引擎结果页标题 |
| `meta_description` | 70-155字符 | 搜索结果摘要 |
| `slug` | kebab-case | URL路径段 |

### 文章元数据

| 字段 | 限制 | 说明 |
|-----|------|------|
| `meta_title` | ≤60字符 | SEO标题 |
| `meta_description` | 130-155字符 | 包含目标关键词 |
| `excerpt` | 1-2句 | 博客列表页显示摘要 |
| `slug` | kebab-case, ≤60字符 | 文章URL |

资料来源：[skills/blog-post-from-outline/SKILL.md:60-75]()

## 技能与工具映射

### blog-post-from-outline

此技能将结构化大纲转换为完整的博客文章草稿，调用以下工具：

- `mcp__brightsite__create_post`：创建草稿文章
- `mcp__brightsite__list_posts`：查找内部链接机会
- `mcp__brightsite__list_pages`：同上
- `mcp__brightsite__get_blog_settings`：确认博客URL前缀

资料来源：[skills/blog-post-from-outline/SKILL.md:83-95]()

### bulk-seo-audit

批量审计站点SEO状态，调用以下工具：

- `mcp__brightsite__list_pages`
- `mcp__brightsite__list_posts`
- `mcp__brightsite__get_page`
- `mcp__brightsite__get_post`
- `mcp__brightsite__update_page`
- `mcp__brightsite__update_post`

资料来源：[skills/bulk-seo-audit/SKILL.md:65-72]()

### generate-location-pages

程序化SEO生成工具，调用以下工具：

- `mcp__brightsite__get_page`：读取模板页面
- `mcp__brightsite__create_page`：创建每个位置页面
- `mcp__brightsite__list_pages`：检查slug冲突

资料来源：[skills/generate-location-pages/SKILL.md:49-52]()

### client-handoff-checklist

客户端交接前质量检查，调用以下工具：

- `mcp__brightsite__get_site_identity`：获取站点标识
- `mcp__brightsite__list_pages`
- `mcp__brightsite__get_page`
- `mcp__brightsite__list_posts`
- `mcp__brightsite__get_post`

资料来源：[skills/client-handoff-checklist/SKILL.md:8-18]()

## 安全与权限

### 元数据更新风险

SEO元数据字段（`meta_title`、`meta_description`、`meta_robots`、`canonical_url`、`og_image_id`）的更新不是暂存的，这意味着修改会直接影响线上元数据。执行此类更新前必须获得明确批准。资料来源：[skills/bulk-seo-audit/SKILL.md:70-75]()

### 内容检查限制

由于MCP协议未暴露所有字段（如表单投递/接收者配置），某些QA检查在技能层面会有限制。这种情况下会提示用户在UI中验证。资料来源：[README.md:18-22]()

## 常见问题排查

### MCP连接问题

1. 确认安装代码片段已正确配置
2. 验证BrightSite账户处于活跃状态
3. 检查MCP服务器注册名称是否为`brightsite`

### 工具调用失败

1. 验证账户ID正确性
2. 检查请求参数是否完整
3. 确认操作权限（草稿模式vs发布模式）

### 批量操作超时

- 降低并发量至3-5请求/秒
- 分批次处理大量数据
- 使用进度报告监控执行状态

## 扩展开发指南

### 新增技能规范

1. 技能文件命名采用kebab-case格式
2. 目录结构：`skills/<skill-name>/SKILL.md`
3. 使用标准frontmatter格式（`name`和`description`）
4. MCP工具引用必须使用规范名称`mcp__brightsite__<tool>`
5. 测试通过后方可提交

资料来源：[CONTRIBUTING.md:12-22]()

### 工具扩展请求

如果工作流程需要尚不存在的工具，应在项目仓库中提交issue，而不是在技能中虚构工具。MCP工具的扩展由BrightSite平台决定。资料来源：[CONTRIBUTING.md:8-11]()

## 相关资源

- [BrightSite官网](https://onbrightsite.com)
- [MCP服务器安装指南](https://onbrightsite.com/mcp)
- [项目贡献指南](./CONTRIBUTING.md)
- [技能列表](./README.md#技能列表)

---

<a id='page-bulk-seo-audit'></a>

## 批量SEO审计技能

### 相关页面

相关主题：[程序化SEO页面生成](#page-generate-location-pages), [客户端交接检查清单](#page-client-handoff)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md)
- [skills/client-handoff-checklist/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/client-handoff-checklist/SKILL.md)
- [README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md)
</details>

# 批量SEO审计技能

批量SEO审计技能（Bulk SEO Audit）是一个自动化工作流，用于全面扫描 BrightSite 网站上的所有页面和文章，检测页面级 SEO 问题并生成按严重程度分组的修复建议列表。该技能通过调用 BrightSite MCP 接口获取网站内容，并基于预定义规则进行系统性检查。

## 功能概述

该技能的核心目标是帮助代理商在以下场景中执行高效的 SEO 质量检查：

| 使用场景 | 说明 |
|---------|------|
| 客户网站移交前 | 作为最终 QA 检查，确保交付质量 |
| 流量下降排查 | 排除页面级 SEO 问题导致的影响 |
| 网站迁移后 | WordPress 导入或域名变更后的校验 |
| 定期维护 | 每 30-90 天对线上网站进行例行检查 |

资料来源：[skills/bulk-seo-audit/SKILL.md:1-20]()

> 注意：该技能专注于页面级 SEO 检查，不包含外链分析、Core Web Vitals 评估或排名追踪等功能。

## 审计范围与检查项

### 严重级别（Critical）

以下问题会直接影响搜索引擎表现，必须修复：

| 检查项 | 问题描述 | 影响 |
|--------|---------|------|
| `meta_title` 为空 | 标题在搜索结果中缺失 | 降低点击率 |
| `meta_title` 超过 60 字符 | 搜索结果中被截断 | 标题不完整 |
| `meta_description` 为空 | Google 自动生成描述 | 描述内容不可控 |
| `slug` 包含空格/大写/特殊字符 | URL 格式不规范 | 影响索引和分享 |
| 多个实体共享相同 slug | URL 重复 | 潜在 canonical 冲突 |
| 内容体为空或少于 300 字符 | 内容过少 | 被判定为低质量页面 |

资料来源：[skills/bulk-seo-audit/SKILL.md:57-65]()

### 警告级别（Warning）

以下问题应予以修复，但不紧急：

| 检查项 | 问题描述 |
|--------|---------|
| `meta_title` 少于 30 字符 | 标题过短，可能缺少关键词 |
| `meta_description` 少于 70 字符 | 描述不够完整 |
| `meta_description` 超过 155 字符 | 搜索结果中被截断 |

资料来源：[skills/bulk-seo-audit/SKILL.md:66-68]()

### 信息级别（Info）

优化建议，非必须修复：

| 检查项 | 问题描述 |
|--------|---------|
| `slug` 超过 60 字符 | URL 过长 |
| `slug` 包含停用词 | URL 不够简洁 |
| `meta_description` 未包含标题关键词 | 元描述与标题关联性弱 |
| 文章缺少封面图 | 影响社交分享效果 |

## 工作流程

```
graph TD
    A[用户输入 Account ID] --> B{网站实体数量}
    B -->|超过 200 个| C[请求用户确认]
    B -->|200 个以内| D[拉取网站清单]
    C -->|确认后| D
    D --> E[获取所有页面列表<br/>list_pages]
    D --> F[获取所有文章列表<br/>list_posts]
    E --> G[遍历实体]
    F --> G
    G --> H[调用 get_page 或 get_post]
    H --> I{检测问题}
    I -->|发现 Critical| J[标记为严重问题]
    I -->|发现 Warning| K[标记为警告]
    I -->|发现 Info| L[标记为信息]
    J --> M[生成问题汇总]
    K --> M
    L --> M
    M --> N[输出 Markdown 报告]
    N --> O[询问用户是否自动修复]
    O -->|用户同意| P[逐项展示修复方案]
    O -->|用户拒绝| Q[流程结束]
    P --> R[获取用户逐项确认]
    R -->|确认单个修复| S[调用 update_page/update_post]
    R -->|拒绝| Q
    S --> T{还有待修复项?}
    T -->|是| R
    T -->|否| Q
```

### 步骤详解

#### 第一步：拉取网站清单

技能首先获取网站的完整实体列表：

- 调用 `mcp__brightsite__list_pages` 获取所有页面
- 调用 `mcp__brightsite__list_posts` 获取所有文章

如果实体数量超过 200 个，技能会提示用户并请求确认，避免意外执行大规模审计。

资料来源：[skills/bulk-seo-audit/SKILL.md:48-53]()

#### 第二步：获取并评估每个实体

对于每个页面或文章，调用对应的详情接口：

- `mcp__brightsite__get_page` — 获取页面详情
- `mcp__brightsite__get_post` — 获取文章详情

页面返回 `heex`（线上版本）和 `heex_staged`（未发布草稿）；文章返回 `content` 和 `content_staged`。**审计会同时检查两个版本**，因为草稿中的问题会在下次发布时生效。

资料来源：[skills/bulk-seo-audit/SKILL.md:55-56]()

#### 第三步：生成报告

检查完成后，按严重程度和实体类型分组输出 Markdown 表格格式的报告：

```
--- DRAFT PREVIEW ---
Title: ...
Slug: ...
Meta title: ...
Meta description: ...
Excerpt: ...

[Full post body in markdown]
--- END PREVIEW ---
```

报告格式包含：

- `[!]` — 严重问题标记
- `[~]` — 警告问题标记
- `[i]` — 信息问题标记
- 实体类型和标题
- 具体问题描述
- 建议修复方案
- 页面/文章 ID（便于在编辑器中定位）

资料来源：[skills/bulk-seo-audit/SKILL.md:70-82]()

报告末尾包含汇总块：

```
Audit summary
-------------
Pages audited: 42
Posts audited: 118
Critical issues: 4
Warnings: 23
Info: 31

Top 3 fixes by impact:
1. 4 pages missing meta_description — generate descriptions for: [list]
2. 7 posts have meta_title > 60 chars — shorten: [list]
3. 2 pages share the slug "/services" — rename one
```

#### 第四步：提供修复选项

报告生成后，询问用户是否自动修复严重问题：

> Want me to auto-fix the critical issues? I can generate meta descriptions and trim long titles. I'll show you each change before saving.

如果用户同意，技能会：

1. 使用 `mcp__brightsite__update_page` 更新页面
2. 使用 `mcp__brightsite__update_post` 更新文章

**重要**：每个修改都会以 diff 格式展示（`旧值 → 新值`），并需要用户明确确认后才能执行。因为 SEO 元数据字段的更新会**立即影响线上元数据**，而不只是暂存。

资料来源：[skills/bulk-seo-audit/SKILL.md:83-91]()

## 输入参数

| 参数 | 必需 | 默认值 | 说明 |
|------|------|--------|------|
| `account_id` | 是 | — | 要审计的 BrightSite 账户 ID |
| `scope` | 否 | both | 审计范围：pages / posts / both |
| `severity_threshold` | 否 | all | 显示级别：all / critical+warnings |

## 调用工具列表

| 工具 | 用途 |
|------|------|
| `mcp__brightsite__list_pages` | 获取所有页面列表 |
| `mcp__brightsite__list_posts` | 获取所有文章列表 |
| `mcp__brightsite__get_page` | 获取单个页面详情（含草稿） |
| `mcp__brightsite__get_post` | 获取单个文章详情（含草稿） |
| `mcp__brightsite__update_page` | 更新页面（修复时使用） |
| `mcp__brightsite__update_post` | 更新文章（修复时使用） |

资料来源：[skills/bulk-seo-audit/SKILL.md:93-100]()

## 使用示例

### 基础审计

```
Run a full SEO audit on account `YOUR_ACCOUNT_ID`. Both pages and posts. Show me everything.
```

### 仅检查页面

```
Run SEO audit on account `YOUR_ACCOUNT_ID`. Pages only.
```

### 仅显示严重和警告问题

```
Audit account `8fd2k3jq91pn` for SEO issues. Show me critical and warning level only.
```

## 反模式与注意事项

### 避免自动修复未获批准

技能文档明确要求：**不要在未经用户逐项批准的情况下自动修复严重问题**。自动生成的 meta_description 如果与页面内容不符，效果可能比没有描述更差。

### 避免将风格偏好标记为问题

以下内容**不是**SEO问题：

- 标题没有使用"力量词汇"
- 描述语气不够吸引人
- 缺少号召性用语的特定措辞

这些都是文案风格偏好，不属于技术 SEO 范畴。审计应保持客观。

### 避免无限制并发请求

在拥有数百个页面的账户上，**不要无限制并发获取所有实体**。建议使用小批量并发（每次 5 个）以避免触发限流。

### 不要信任 has_unpublished_changes

即使 `has_unpublished_changes: false`，已发布的页面也可能存在过时的 meta 信息。该字段不能作为正确性的证明。

## 与其他技能的协同

### 客户端移交清单

在执行客户端移交检查时，SEO 审计是其中一环。客户端移交清单技能会复用 SEO 审计的检查逻辑来验证页面元数据：

- `[FAIL]` 任何页面缺少 `meta_title` 或 `meta_description`
- `[WARN]` 任何页面的 `canonical_url` 设置为与公开 URL 不同的域名

资料来源：[skills/client-handoff-checklist/SKILL.md:18-23]()

### 建议的后续操作

| 操作 | 说明 |
|------|------|
| 修复报告中的严重问题 | 按修复建议逐一处理 |
| 运行客户端移交检查 | 确保网站其他配置完整 |
| 逐步发布修复后的页面 | 避免一次性发布 50+ 页面 |

## 社区反馈

从社区讨论来看，Claude Skills 生态系统中，SEO 相关的技能受到代理商和独立开发者的高度关注。主要使用场景包括：

- 客户网站移交前的批量检查
- 网站重构后的 SEO 健康度评估
- 定期网站维护流程的一部分

用户反馈表明，批量操作能力（一次性检查/修复多个页面）是提升工作效率的关键特性。

资料来源：[社区上下文 - Twitter/X 讨论]()

## 限制说明

该技能存在以下已知限制：

| 限制 | 说明 |
|------|------|
| MCP 不暴露所有字段 | 例如表单配置、发送目标等信息无法通过 MCP 检查 |
| 不包含外链分析 | 无法检测指向外部网站的链接质量 |
| 不包含 Core Web Vitals | 无法评估页面加载性能指标 |
| 不包含排名追踪 | 无法展示关键词排名变化 |

> **提示**：对于 MCP 无法检查的配置项（如表单投递设置），技能会在检查报告中说明需要用户在 UI 中手动验证。

资料来源：[README.md:18-21]()

---

<a id='page-generate-location-pages'></a>

## 程序化SEO页面生成

### 相关页面

相关主题：[批量SEO审计技能](#page-bulk-seo-audit), [CSV重定向映射](#page-redirect-map)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/generate-location-pages/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/generate-location-pages/SKILL.md)
- [skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md)
- [skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)
- [skills/client-handoff-checklist/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/client-handoff-checklist/SKILL.md)
- [README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md)
</details>

# 程序化SEO页面生成

## 概述

程序化SEO页面生成（Programmatic SEO，简称pSEO）是一种大规模创建针对特定地理位置优化的落地页面的技术。该功能允许用户通过CSV数据源批量生成符合SEO规范的BrightSite页面，每个页面针对 `[服务] + [城市]` 格式的关键词进行优化。

此技能的主要目的是帮助代理商为客户提供能够覆盖数十甚至数百个地理区域的SEO内容，适用于HVAC、管道维修牙科、房地产、法律、健身等服务行业。

资料来源：[skills/generate-location-pages/SKILL.md:1-5]()

## 核心工作流程

程序化SEO页面生成采用四阶段工作流程，确保在大规模生成前进行充分的预览和确认。

```mermaid
graph TD
    A[用户输入] --> B[Step 1: 确认范围]
    B --> C[Step 2: 生成单页示例]
    C --> D{用户审核}
    D -->|通过| E[Step 3: 批量生成]
    D -->|拒绝| F[调整参数]
    F --> B
    E --> G[Step 4: 输出摘要]
    G --> H[运行SEO审计]
```

### Step 1: 确认生成范围

在调用任何创建工具之前，系统会向用户展示以下信息进行确认：

| 预览项 | 说明 |
|--------|------|
| 生成数量 | 将创建的页面总数 |
| CSV首行数据 | 第一行数据预览 |
| 渲染后的HEEx | 模板替换后的页面内容预览 |
| 元标题 | 每个页面的meta_title预览 |
| 元描述 | 每个页面的meta_description预览 |
| URL路径 | 每个页面将生成的slug和路径 |

系统明确要求用户输入 "yes, generate them" 确认后才能执行批量创建，以防止意外生成大量页面。

资料来源：[skills/generate-location-pages/SKILL.md:45-55]()

### Step 2: 生成单页示例

系统首先调用 `mcp__brightsite__create_page` 仅创建第一行数据的页面。创建完成后返回的响应包含 `path` 字段（完整URL路径），用户需在BrightSite编辑器中预览并确认页面质量后再继续。

此阶段是防止批量错误的关键检查点，确保模板变量替换和SEO配置正确。

资料来源：[skills/generate-location-pages/SKILL.md:56-62]()

### Step 3: 批量生成

用户确认示例页面后，系统遍历CSV剩余数据行，调用 `mcp__brightsite__create_page` 创建每个页面。创建参数包括：

```markdown
- account_id       # BrightSite账户ID
- title            # 页面标题，格式："{服务} in {城市}, {州}"
- slug             # URL别名，kebab-case格式
- heex             # 模板内容，变量替换后的HEEx代码
- meta_title       # SEO标题，60字符以内
- meta_description # SEO描述，155字符以内
- status           # 固定为 "draft"，不以草稿模式创建
- layout_id        # 指定布局ID（如有）
```

生成过程中实施限流策略：约5页/秒，避免触发API速率限制。每生成10页输出一次进度报告。

资料来源：[skills/generate-location-pages/SKILL.md:63-74]()

### Step 4: 输出摘要

批量创建完成后，系统输出包含以下内容的摘要报告：

- 成功创建的页面总数及失败数量
- 创建的草稿页面URL列表
- 建议的后续操作

资料来源：[skills/generate-location-pages/SKILL.md:75-80]()

## 输入参数详解

### CSV数据源要求

CSV文件是程序化SEO的核心数据源，其列结构直接影响页面质量。

| 列名 | 必需性 | 说明 |
|------|--------|------|
| city | 必需 | 城市名称 |
| slug | 必需 | URL别名，kebab-case格式 |
| state | 建议 | 州/省份名称 |
| population | 建议 | 城市人口数据 |
| nearest_highway | 建议 | 最近的公路/高速公路 |
| local_landmark | 建议 | 地标建筑名称 |
| phone | 建议 | 本地联系电话 |
| address | 建议 | 实体店铺地址 |

CSV列越丰富，生成的页面内容差异化程度越高，可有效避免Google因内容过于相似而降低排名。

资料来源：[skills/generate-location-pages/SKILL.md:20-27]()

### 模板页面

模板页面是程序化生成的基础，可以通过以下两种方式指定：

1. **页面ID克隆**：提供现有页面的ID，系统复制其结构和布局
2. **HEEx代码**：直接提供HEEx模板代码及结构描述

模板中的变量占位符格式与CSV列名对应，系统自动进行替换。

资料来源：[skills/generate-location-pages/SKILL.md:28-31]()

## 使用场景

### 适用场景

程序化SEO页面生成最适合以下情况：

- 客户业务具有地域属性（如紧急管道维修、牙科诊所、律师事务所）
- 目标关键词为 `[服务] in [城市]` 格式
- 需要覆盖10个以上地理位置
- 竞争对手已在使用程序化SEO

### 不适用场景

对于少于约10个地点的情况，手动创建的页面转换效果更好，因为：

- 可针对每个地点进行深度定制
- 无需额外的CSV准备成本
- 内容差异化程度更高

资料来源：[skills/generate-location-pages/SKILL.md:13-18]()

## SEO最佳实践

### 内容差异化要求

Google对"内容过薄"的程序化页面会采取去索引措施。每个页面必须包含至少2-3个地点特定的变量替换内容，而非仅更换城市名称。

| 反面示例 | 正面示例 |
|----------|----------|
| 标题：紧急管道维修<br>内容：仅城市名改为Austin/Houston/Dallas | 标题：紧急管道维修<br>内容：包含当地地标、人口规模、社区特点 |

资料来源：[skills/generate-location-pages/SKILL.md:88-91]()

### 元描述配置

每个程序化页面必须配置独立的meta_description。空白元描述会浪费该页面的搜索排名机会。

元描述应符合以下规范：
- 长度：130-155字符
- 包含目标服务关键词
- 包含城市名称
- 采用行动导向的表述

资料来源：[skills/generate-location-pages/SKILL.md:101-103]()

### 发布节奏建议

对于新域名，不建议一次性发布50个以上页面。建议分批次发布，每批间隔数天，让网站地图提交显得自然。

| 域名年龄 | 建议发布策略 |
|----------|--------------|
| 新域名 (< 6个月) | 每天5-10页，持续发布 |
| 成熟域名 (> 1年) | 可加速至每天20-30页 |

资料来源：[skills/generate-location-pages/SKILL.md:95-98]()

## 后续步骤

### SEO审计

批量创建完成后，建议运行 `bulk-seo-audit` 技能对所有新页面进行SEO检查，验证：

- meta_title长度是否合规（≤60字符）
- meta_description是否完整
- 页面slug是否符合规范
- 内部链接结构是否正确

资料来源：[skills/bulk-seo-audit/SKILL.md:1-15]()

### 客户端交接检查

在将程序化页面交付客户前，建议运行 `client-handoff-checklist` 进行预发布QA检查：

- 确认所有页面已设置正确的meta_title和meta_description
- 验证页面status状态
- 检查是否存在未发布内容（has_unpublished_changes）

资料来源：[skills/client-handoff-checklist/SKILL.md:1-20]()

## 使用的MCP工具

| 工具名称 | 用途 |
|----------|------|
| `mcp__brightsite__get_page` | 读取模板页面内容 |
| `mcp__brightsite__create_page` | 创建每个地点页面 |
| `mcp__brightsite__list_pages` | 检查slug是否与现有页面冲突 |

资料来源：[skills/generate-location-pages/SKILL.md:104-107]()

## 常见反模式

| 反模式 | 说明 | 正确做法 |
|--------|------|----------|
| 内容仅更换城市名 | Google会识别为低质量内容 | 每个页面至少2-3个地点特定变量 |
| 虚构本地事实 | 损害品牌信誉 | 无本地数据时省略该内容区块 |
| 一次性发布大量页面 | 可能触发垃圾内容算法 | 分批次发布，控制节奏 |
| 跳过meta_description | 浪费排名机会 | 为每个页面生成独立描述 |

资料来源：[skills/generate-location-pages/SKILL.md:88-103]()

## 调用示例

```
I have a CSV at ~/clients/acme-hvac/locations.csv with columns city,state,slug,population,landmark. The client is Acme HVAC and they do emergency furnace repair. Account ID is YOUR_ACCOUNT_ID. Generate location pages, draft mode, using the template at page ID 8fd2k3jq91pn.
```

此示例展示了完整的输入格式，包括CSV路径、数据列、服务描述和账户ID。

资料来源：[skills/generate-location-pages/SKILL.md:108-111]()

## 与其他技能的关系

程序化SEO页面生成通常作为更大工作流的一部分：

```mermaid
graph LR
    A[generate-location-pages] --> B[bulk-seo-audit]
    B --> C[client-handoff-checklist]
    C --> D[发布页面]
```

这种组合确保了大批量生成的内容同时满足SEO标准和客户交付质量要求。

---

<a id='page-redirect-map'></a>

## CSV重定向映射

### 相关页面

相关主题：[WordPress博客迁移](#page-migrate-wordpress), [客户端交接检查清单](#page-client-handoff)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/redirect-map-from-csv/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/redirect-map-from-csv/SKILL.md) *(项目主文件)*
- [README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md) *(项目概览)*
- [skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md) *(SEO审计相关)*
- [skills/generate-location-pages/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/generate-location-pages/SKILL.md) *(程序化SEO相关)*
- [skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md) *(博客发布相关)*
- [skills/client-handoff-checklist/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/client-handoff-checklist/SKILL.md) *(客户端交接相关)*
</details>

# CSV重定向映射

## 概述

**CSV重定向映射**（redirect-map-from-csv）是 BrightSite Skills 工具包中的一个自动化技能，用于将电子表格格式的旧URL到新URL的映射关系批量转换为 BrightSite 平台的重定向规则。

该技能属于网站迁移工作流的关键环节，在网站重构、域名变更或URL结构优化场景中发挥重要作用。通过批量处理机制，代理商可以一次性为数十甚至数百个页面创建精确的重定向规则，避免手动操作的遗漏和错误。

资料来源：[README.md:skills列表](https://github.com/BrightSiteHQ/skills/blob/main/README.md)

---

## 核心功能

### URL映射转换

该技能的核心能力是将用户提供的CSV格式重定向映射表自动解析并创建为BrightSite平台的重定向记录。每个CSV行代表一组源URL到目标URL的映射关系，技能会自动处理：

- **源URL解析**：识别CSV中的旧URL路径
- **目标URL解析**：识别对应的新URL路径
- **重定向类型设置**：支持301（永久重定向）和302（临时重定向）
- **批量创建**：一次性处理整个CSV文件

### 批量处理机制

与逐个手动创建重定向的传统方式不同，该技能采用批量处理模式。代理在执行迁移任务时，只需提供CSV文件路径和账户ID，技能即可自动完成所有重定向规则的创建，显著提升工作效率。

资料来源：[skills/generate-location-pages/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/generate-location-pages/SKILL.md) *(批量处理模式参考)*

---

## 使用场景

### 网站迁移

当客户从旧平台（如WordPress）迁移到BrightSite时，原有页面的URL结构往往无法完全保留。CSV重定向映射技能可以将迁移前后的URL对应关系批量导入，确保：

- 旧链接自动跳转到新页面
- 搜索引擎索引的权重能够传递
- 用户访问旧书签不会得到404错误

### URL结构重构

网站进行URL规范化或SEO优化时，可能需要更改大量页面的路径。该技能允许代理商提前规划新的URL结构，然后通过CSV批量创建重定向规则。

### 域名变更

客户更换域名后，所有旧域名下的页面都需要重定向到新域名。CSV映射可以清晰记录每个旧URL与新URL的对应关系，确保迁移过程平滑无错。

资料来源：[skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md) *(内容迁移参考)*

---

## 工作流程

```mermaid
graph TD
    A[用户提供CSV文件] --> B[确认账户ID和映射范围]
    B --> C[解析CSV内容]
    C --> D{验证映射关系}
    D -->|发现问题| E[列出需要确认的项]
    E --> B
    D -->|验证通过| F[批量创建重定向规则]
    F --> G[输出创建结果摘要]
    G --> H[建议后续SEO审计]
```

### 第一步：准备CSV文件

用户需要准备包含重定向映射的CSV文件，标准格式如下：

| 列名 | 说明 | 示例 |
|------|------|------|
| `source_url` | 旧URL路径 | `/old-page-about-us` |
| `target_url` | 新URL路径 | `/about` |
| `redirect_type` | 重定向类型 | `301` 或 `302` |
| `status` | 状态标识 | `active` 或 `inactive` |

**注意**：CSV文件应使用UTF-8编码，确保中文字符正确解析。

### 第二步：确认账户信息

在执行批量创建前，需要确认：

- **Account ID**：BrightSite账户的唯一标识符（NanoID格式）
- **映射范围**：确认是否需要为所有CSV行创建重定向
- **重定向类型**：确认默认使用301还是302

### 第三步：预览和确认

在批量创建前，技能会先展示：
- 将创建的重定向总数
- 前5条映射预览
- 任何检测到的潜在问题

**必须等待用户明确确认后才会执行创建操作**。

### 第四步：批量创建

确认后，技能调用BrightSite MCP工具批量创建重定向规则。每批处理量会根据系统限制自动调整，避免API超时。

### 第五步：结果报告

创建完成后，技能输出包含以下信息的摘要：

- 成功创建的重定向数量
- 失败的重定向及原因
- 创建后的重定向URL列表

资料来源：[skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md) *(结果报告格式参考)*

---

## MCP工具依赖

该技能依赖以下BrightSite MCP工具：

| 工具名称 | 功能 | 调用方式 |
|----------|------|----------|
| `mcp__brightsite__create_redirect` | 创建单个重定向规则 | 根据CSV行逐条调用 |
| `mcp__brightsite__list_redirects` | 列出现有重定向 | 用于冲突检测 |
| `mcp__brightsite__get_site_identity` | 获取网站标识 | 验证目标网站 |

资料来源：[skills/client-handoff-checklist/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/client-handoff-checklist/SKILL.md) *(MCP工具依赖模式)*

---

## 反模式与注意事项

### 必须避免的问题

| 问题类型 | 描述 | 后果 |
|----------|------|------|
| **源URL错误** | CSV中包含不存在或格式错误的URL | 创建的重定向无法生效 |
| **目标URL缺失** | 指向的新URL尚未创建 | 用户访问时仍会404 |
| **循环重定向** | A→B, B→A 的闭环 | 浏览器报错死循环 |
| **链式重定向** | A→B→C 多级跳转 | 降低页面权重传递效率 |

### 最佳实践

1. **提前验证目标URL**：确保所有目标页面在创建重定向前已经存在
2. **使用301永久重定向**：除非明确需要临时跳转，优先使用301
3. **避免过长的重定向链**：最多保持两级跳转（A→B→C）
4. **创建后进行SEO审计**：运行 `bulk-seo-audit` 技能验证重定向效果
5. **保留原始CSV文件**：作为迁移记录存档，便于日后排查问题

资料来源：[skills/bulk-seo-audit/SKILL.md:反模式](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md) *(SEO最佳实践参考)*

---

## 与其他技能的协同

### 典型工作流

```mermaid
graph LR
    A[迁移WordPress博客] --> B[migrate-wordpress-blog]
    B --> C[redirect-map-from-csv]
    C --> D[bulk-seo-audit]
    D --> E[client-handoff-checklist]
    
    F[程序化SEO] --> G[generate-location-pages]
    G --> C
```

### 协同场景

**场景一：WordPress迁移后URL映射**

1. 使用 `migrate-wordpress-blog` 导入文章内容
2. 使用 `redirect-map-from-csv` 创建旧URL到新URL的重定向
3. 使用 `bulk-seo-audit` 检查新站点的SEO状态
4. 使用 `client-handoff-checklist` 进行上线前最终检查

**场景二：程序化SEO页面批量重定向**

1. 使用 `generate-location-pages` 创建城市页面
2. 后续URL结构调整时，使用 `redirect-map-from-csv` 创建重定向规则

资料来源：[skills/generate-location-pages/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/generate-location-pages/SKILL.md) *(pSEO工作流参考)*

---

## 常见问题排查

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 重定向不生效 | 目标页面状态为draft | 在BrightSite中先将目标页面发布 |
| 404错误仍出现 | 源URL格式与实际访问不匹配 | 检查URL前导斜杠和大小写 |
| 创建失败 | 账户ID错误 | 确认从BrightSite仪表板复制正确的NanoID |
| 批量处理中断 | CSV编码问题 | 确保文件保存为UTF-8编码 |

---

## 相关资源

- [BrightSite Skills 官方仓库](https://github.com/BrightSiteHQ/skills)
- [MCP工具文档](https://github.com/BrightSiteHQ/skills#mcp-tools)
- [贡献指南](./CONTRIBUTING.md) — 如何为Skills项目贡献新技能

---

<a id='page-migrate-wordpress'></a>

## WordPress博客迁移

### 相关页面

相关主题：[CSV重定向映射](#page-redirect-map), [批量SEO审计技能](#page-bulk-seo-audit)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/migrate-wordpress-blog/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/migrate-wordpress-blog/SKILL.md) *(文档中未获取到具体内容，仅从README.md引用)*
- [README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/BrightSiteHQ/skills/blob/main/CONTRIBUTING.md)
- [skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)
- [skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md)
</details>

# WordPress博客迁移

## 概述

WordPress博客迁移（migrate-wordpress-blog）是BrightSite技能库中的一个核心工具，用于将内容从WordPress平台迁移到BrightSite。该技能专门处理WordPress XML导出文件，将帖子内容批量导入目标账户，同时保留原始URL结构并在必要时生成301重定向以维护SEO价值。

资料来源：[README.md:30]()

## 核心功能

| 功能 | 说明 |
|------|------|
| XML解析 | 解析WordPress WXR格式导出文件 |
| 内容迁移 | 将帖子标题、正文、分类、标签等元数据导入BrightSite |
| Slug保留 | 尽可能保持原始URL结构 |
| 301重定向 | 对URL发生变化的帖子自动生成重定向规则 |
| 草稿模式 | 所有导入内容以草稿状态创建，便于审核后再发布 |

资料来源：[README.md:29]()

## 工作流程

```mermaid
graph TD
    A[用户提供WordPress XML导出文件] --> B[解析XML结构]
    B --> C[提取帖子内容、元数据、原始slug]
    C --> D{检查slug冲突}
    D -->|无冲突| E[直接创建草稿帖子]
    D -->|有冲突| F[生成新slug]
    F --> G[创建草稿帖子]
    E --> H[生成301重定向映射]
    G --> H
    H --> I[输出迁移报告]
    I --> J[用户审核后手动发布]
```

## 使用场景

该技能适用于以下情况：

- **平台迁移项目**：代理商需要将客户从WordPress迁移到BrightSite时使用
- **批量内容导入**：需要一次性迁移大量博客文章而非手动复制粘贴
- **SEO保护需求**：迁移后需确保搜索引擎仍能正确索引旧URL对应的内容

资料来源：[CONTRIBUTING.md:8-10]()

## 输入要求

用户在调用此技能时需要提供：

| 参数 | 必需 | 说明 |
|------|------|------|
| Account ID | 是 | BrightSite目标账户ID（NanoID格式，如 `8fd2k3jq91pn`） |
| XML文件路径 | 是 | WordPress导出的XML文件路径或内容 |
| 发布状态 | 否 | 默认以草稿模式导入 |

资料来源：[README.md:42-44]()

## 注意事项

### SEO保护机制

迁移过程中最重要的考量是SEO价值维护。当原WordPress站点的帖子slug与BrightSite现有内容冲突，或因格式化需求需要调整slug时，技能会自动生成301永久重定向。

> ⚠️ **重要提示**：301重定向对于保持搜索引擎排名至关重要。BrightSite使用 `mcp__brightsite__create_redirect` 工具来创建重定向规则。

资料来源：[skills/blog-post-from-outline/SKILL.md:89-91]()

### 草稿优先策略

与其他BrightSite技能一致，该迁移工具**始终以草稿模式创建内容**，从不自动发布。这确保了：

1. 迁移后的内容需要人工审核
2. 图片、内链等资源可以重新校验
3. 格式问题可以在发布前修复

资料来源：[skills/bulk-seo-audit/SKILL.md:71-73]()

## 技能集成

迁移完成后，建议结合使用以下技能进行后续操作：

| 技能 | 用途 |
|------|------|
| `bulk-seo-audit` | 审计迁移后所有帖子的SEO元数据完整性 |
| `client-handoff-checklist` | 在将迁移完成的网站交付客户前进行最终检查 |
| `blog-post-from-outline` | 如需创建新的迁移后博客内容 |

资料来源：[README.md:27-32]()

## 社区实践

根据社区反馈，WordPress迁移是代理商在接手新客户时最常见的任务之一。社交媒体上有关于Claude Code Skills的讨论中多次提到内容迁移是AI辅助数字营销的关键场景之一。

资料来源：社区上下文（Twitter/X讨论）

## 相关文件结构

技能安装后的目录结构：

```text
~/.claude/skills/migrate-wordpress-blog/SKILL.md
~/.claude/skills/generate-location-pages/SKILL.md
~/.claude/skills/bulk-seo-audit/SKILL.md
~/.claude/skills/redirect-map-from-csv/SKILL.md
~/.claude/skills/client-handoff-checklist/SKILL.md
~/.claude/skills/blog-post-from-outline/SKILL.md
```

资料来源：[README.md:63-70]()

## 扩展阅读

如需创建自定义技能，请参考 [CONTRIBUTING.md](CONTRIBUTING.md) 中的规范：

- 技能必须基于真实工作流场景
- 必须映射到现有的BrightSite MCP工具
- 必须包含"Anti-patterns to avoid"反模式章节以防止常见错误

资料来源：[CONTRIBUTING.md:8-18]()

---

<a id='page-blog-post-from-outline'></a>

## 大纲转博客文章

### 相关页面

相关主题：[客户端交接检查清单](#page-client-handoff), [批量SEO审计技能](#page-bulk-seo-audit)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)
- [README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/BrightSiteHQ/skills/blob/main/CONTRIBUTING.md)
- [skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md)
- [skills/client-handoff-checklist/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/client-handoff-checklist/SKILL.md)
</details>

# 大纲转博客文章

`大纲转博客文章`（blog-post-from-outline）是一个 Claude 技能（Skill），用于将结构化的大纲转换为 BrightSite 平台的完整博客文章草稿。该技能遵循严格的内容创作工作流，确保生成的博客文章具备良好的 SEO 优化结构、元数据配置和可发布质量。

## 功能概述

### 核心用途

该技能的主要功能是将用户提供的outline（包含bullet points、H2/H3标题和关键论点）转化为结构完整、格式规范的博客文章草稿。技能特别强调内容质量而非泛泛生成——它要求用户已完成思考过程，提供具体的大纲和目标关键词，而非仅仅给出一个宽泛的主题。

### 适用场景

| 场景类型 | 具体说明 |
|---------|---------|
| 机构内容创作 | 代理机构需要根据客户的内容简报快速生成草稿 |
| 专家内容转化 | 领域专家通过语音备忘录或Loom录制内容，机构获取转录后生成outline |
| 写作辅助 | 作者拥有结构化outline但不擅长撰写连接性散文 |

### 不适用场景

该技能**不适用于**以下情况：
- 仅提供标题或主题时的泛泛生成（输出质量较低）
- 长篇支柱内容（>2000词）——建议分段迭代完成

资料来源：[skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)

## 工作流程

该技能采用五步工作流程，确保每一步都经过用户确认，避免生成不符合预期的内容。

```mermaid
graph TD
    A[用户提供大纲] --> B[步骤1: 确认理解]
    B --> C{用户确认?}
    C -->|需要更多信息| D[返回询问细节]
    D --> B
    C -->|确认| E[步骤2: 起草文章]
    E --> F[步骤3: 生成元数据]
    F --> G[步骤4: 展示草稿预览]
    G --> H{用户审核?}
    H -->|需要修改| I[迭代修订]
    I --> G
    H -->|批准| J[步骤5: 创建草稿]
    J --> K[返回文章ID]
```

### 步骤1：确认理解

在起草之前，技能会向用户回显以下关键信息并等待确认：

- **H2结构**：将使用的标题层级
- **目标关键词**：及其放置位置（标题、H1、前100词、一个H2、meta）
- **行动号召（CTA）**：文章末尾的行动请求
- **目标语气**：正在模仿的参考风格

> 注意：如果任何信息不清晰，必须返回询问而非直接起草。

资料来源：[skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)

### 步骤2：起草文章

文章起草遵循严格的结构约束：

| 元素 | 要求 |
|-----|------|
| **标题** | 60字符以内，自然包含目标关键词，行动/利益导向 |
| **首段** | 2-3句吸引读者，提及目标关键词一次，设定后续内容预期 |
| **H2结构** | 匹配用户提供的大纲，每个H2包含具体收获、示例或证据 |
| **语气** | 短句、主动语态、无流行语（utilize、leverage、synergy） |
| **行动号召** | 文章末尾一段，直接请求而非委婉暗示 |
| **内部链接** | 如用户提及相关文章或页面，自然融入1-2个内部链接 |
| **长度** | 目标字数±15%范围内 |

### 步骤3：生成元数据

文章元数据包含四个关键字段：

| 字段 | 字符限制 | 说明 |
|-----|---------|------|
| `meta_title` | < 60字符 | 通常与标题相同，但可更精简以利于搜索 |
| `meta_description` | 130-155字符 | 包含目标关键词，描述利益而非摘要 |
| `excerpt` | 1-2句 | 用于博客列表页面，促使用户点击 |
| `slug` | < 60字符 | 标题的kebab-case版本，移除停用词 |

### 步骤4：展示草稿预览

完整草稿以Markdown格式展示，预览格式如下：

```
--- DRAFT PREVIEW ---
Title: ...
Slug: ...
Meta title: ...
Meta description: ...
Excerpt: ...

[完整文章Markdown正文]
--- END PREVIEW ---
```

等待用户批准或请求修改。常见修订请求包括：语气偏差、某个H2较弱、CTA需要调整等。

### 步骤5：创建草稿

用户批准后，将Markdown正文转换为纯HTML，调用 `mcp__brightsite__create_post` 接口创建草稿：

- `account_id`：账户ID
- `title`：文章标题
- `slug`：URL slug
- `content`：HTML正文（纯HTML，不支持HEEx或Phoenix模板）
- `excerpt`：摘要
- `meta_title`：元标题
- `meta_description`：元描述
- `status: "draft"`：始终创建为草稿

> 技能返回文章ID及提示：`Draft created: post ID 8fd2k3jq91pn. Open it in the BrightSite editor to add a feature image, internal links, and publish when ready.`

资料来源：[skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)

## 用户输入要求

### 必需参数

| 参数 | 说明 | 示例 |
|-----|------|-----|
| **Account ID** | BrightSite账户ID | `8fd2k3jq91pn` |
| **Outline** | 子弹点、H2/H3标题、关键论点 | 结构化程度越高越好 |
| **Target Keyword** | 文章主关键词 | "small business HVAC marketing" |
| **Audience** | 一句话描述目标读者 | "small business owners evaluating CRMs" |
| **Voice/Tone Reference** | 参考文章链接或语气描述 | "conversational, no fluff, US English" |
| **Word Count** | 目标字数，默认800-1200词 | 1000 |
| **CTA** | 读者末尾应采取的行动 | "book a strategy call" |

资料来源：[skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)

## 反模式与质量控制

该技能定义了明确的行为边界，避免常见的AI生成内容问题。

### 必须避免的行为

| 反模式 | 说明 | 风险 |
|-------|------|-----|
| **自动发布** | 即使用户要求"发布"，也创建为草稿 | 让用户审核后再发布 |
| **无大纲生成** | 仅给主题时询问大纲而非直接生成 | 避免泛泛内容 |
| **凑字数** | 自然长度不足时硬凑 | 损害SEO和跳出率 |
| **AI语气** | 使用"dive into"、"unleash"、"in today's..."等 | 降低专业度 |
| **虚构数据** | 概要提到统计数字时询问来源 | 避免虚假信息 |

### 质量标准

> "不要评判风格偏好为问题。'标题没有使用有力词汇'不是SEO问题，是文案观点。保持审核客观。"

资料来源：[skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md)

## 使用的工具

| 工具名称 | 用途 |
|---------|------|
| `mcp__brightsite__create_post` | 创建博客文章草稿 |
| `mcp__brightsite__list_posts` | 查找内部链接机会（可选） |
| `mcp__brightsite__list_pages` | 查找内部链接机会（可选） |
| `mcp__brightsite__get_blog_settings` | 确认博客URL前缀（可选） |

> 注意：文章正文只支持纯HTML，不支持HEEx、Phoenix模板助手或页面组件。

资料来源：[skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)

## 调用示例

```
Account `YOUR_ACCOUNT_ID`. Target keyword: "small business HVAC marketing." 
Audience: HVAC company owners with 5-20 employees. 
Voice: like the post at /blog/hvac-seo-basics on the same site. 1000 words. 
CTA: book a strategy call.

Outline:
- Most HVAC marketing fails because it's interchangeable
- 3 things that actually work: Google Business Profile reviews, neighborhood-specific landing pages, seasonal email follow-up
- For each: why it works, one example, how to start this week
- Wrap with: pick one, do it for 90 days
```

## 与其他技能的关系

该技能是BrightSite技能库内容工作流的一部分，与以下技能协同：

| 技能 | 关系说明 |
|-----|---------|
| **bulk-seo-audit** | 草稿创建后，可运行SEO审核检查元数据质量 |
| **client-handoff-checklist** | 最终交付前验证所有配置是否完整 |
| **generate-location-pages** | 批量生成落地页后可使用本技能为每个页面撰写博客内容 |

资料来源：[README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md)

## 技能开发规范

如果您希望为该项目贡献新的技能，需遵循以下原则：

1. **编码真实工作流** - 必须是在客户站点实际运行过的，而非假设性的
2. **映射到现有MCP工具** - 引用 `mcp__brightsite__<tool>` 格式的规范工具名
3. **防止模型犯错** - 反模式部分是任何技能最有价值的章节

> "如果工作流需要的工具不存在，先开issue而非写技能——我们会考虑添加该工具。"

资料来源：[CONTRIBUTING.md](https://github.com/BrightSiteHQ/skills/blob/main/CONTRIBUTING.md)

## 总结

`大纲转博客文章`技能通过结构化的五步工作流程，将用户提供的outline转化为高质量、可发布的博客文章草稿。其核心价值在于：

- **质量优先**：要求用户先完成思考，避免泛泛生成
- **用户控制**：每步确认，不自动发布，尊重用户决策
- **SEO优化**：内置元数据规范和关键词放置策略
- **批量协作**：可与SEO审核、客户端交接清单等技能协同工作

该技能特别适合内容代理机构、专业博客运营者和需要高效内容生产流程的团队使用。

---

<a id='page-client-handoff'></a>

## 客户端交接检查清单

### 相关页面

相关主题：[批量SEO审计技能](#page-bulk-seo-audit), [项目概述](#page-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/client-handoff-checklist/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/client-handoff-checklist/SKILL.md)
- [skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md)
- [skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)
- [skills/generate-location-pages/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/generate-location-pages/SKILL.md)
- [README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md)
</details>

# 客户端交接检查清单

## 概述

客户端交接检查清单（Client Handoff Checklist）是 BrightSite Skills 仓库中的一个核心技能模块，专为网站上线前的质量保证（QA）而设计。该技能通过系统化的检查流程，验证网站身份、错误页面、博客设置、表单配置和分析工具是否正确配置，确保在正式交付给客户之前排除所有关键问题。

资料来源：[skills/client-handoff-checklist/SKILL.md:1-1]()

### 核心目标

| 目标类别 | 描述 |
|---------|------|
| **完整性检查** | 确保所有必要的页面和配置项已创建 |
| **正确性检查** | 验证元数据、SEO 配置和内容质量的正确性 |
| **一致性检查** | 确认暂存版本与线上版本保持一致 |
| **可发布性检查** | 确认网站满足上线条件 |

### 定位与范围

该检查清单是 **BrightSite 代理工作流** 中的最后一道质量门关。它不执行修复操作，仅提供问题诊断和报告功能。这与 `bulk-seo-audit` 技能形成互补——后者专注于 SEO 问题审计，而本清单覆盖更广泛的站点配置问题。

资料来源：[skills/bulk-seo-audit/SKILL.md:1-1]()

---

## 检查流程架构

### 工作流图

```mermaid
graph TD
    A[开始交接检查] --> B[检查站点身份]
    B --> C[检查页面配置]
    C --> D[检查博客设置]
    D --> E[检查内容质量]
    E --> F[检查表单和分析工具]
    F --> G{是否存在 FAIL 项?}
    G -->|是| H[输出 NOT READY 报告]
    G -->|否| I[输出 READY 报告]
    H --> J[修复问题后重新检查]
    I --> K[可以交付]
```

### MCP 工具依赖

| 工具名称 | 用途 |
|---------|------|
| `mcp__brightsite__get_site_identity` | 获取站点基本信息 |
| `mcp__brightsite__list_pages` | 列出所有页面 |
| `mcp__brightsite__get_page` | 获取单个页面详情 |
| `mcp__brightsite__list_posts` | 列出所有博客文章 |
| `mcp__brightsite__get_post` | 获取单篇文章详情 |

---

## 详细检查项

### 1. 站点身份检查

使用 `mcp__brightsite__get_site_identity` 获取站点配置信息。

#### 检查标准

| 状态标记 | 检查条件 | 严重程度 |
|---------|---------|---------|
| `[FAIL]` | `title` 为空或仍为 "Untitled Site" / 默认值 | 关键 |
| `[FAIL]` | `logo_id` 为 null | 关键 |
| `[WARN]` | `icon_id`（网站图标/favicon）为 null | 警告 |
| `[FAIL]` | `business_type` 为 null | 关键 |
| `[WARN]` | `business_description` 缺失 | 警告 |
| `[WARN]` | `email` 或 `phone` 缺失 | 警告 |
| `[WARN]` | 本地企业的地址字段缺失或 `geo_lat`/`geo_lng` 为 null | 警告 |
| `[WARN]` | `social_profiles` 为空 | 警告 |

#### 状态标记说明

- `[OK]` - 检查通过
- `[WARN]` - 警告，存在潜在问题但不影响上线
- `[FAIL]` - 失败，存在必须修复的关键问题

资料来源：[skills/client-handoff-checklist/SKILL.md:1-16]()

### 2. 页面配置检查

使用 `mcp__brightsite__list_pages` 获取所有页面列表，然后对每个页面调用 `mcp__brightsite__get_page`。

#### 检查标准

| 状态标记 | 检查条件 | 严重程度 |
|---------|---------|---------|
| `[FAIL]` | 没有页面设置 `is_home_page: true` | 关键 |
| `[FAIL]` | 任何页面状态为 `draft` 且从首页链接 | 关键 |
| `[WARN]` | 任何页面 `has_unpublished_changes: true` | 警告 |
| `[FAIL]` | 页面缺失 `meta_title` 或 `meta_description` | 关键 |
| `[WARN]` | 页面 `canonical_url` 与公网 URL 域名不同 | 警告 |

#### 关键注意事项

暂存内容（`*_staged`）会在用户下次发布时上线，必须同时检查线上版本和暂存版本。

资料来源：[skills/client-handoff-checklist/SKILL.md:18-26]()

### 3. 内容质量检查

扫描已获取的 `content`/`content_staged` 字符串，检查是否存在占位符文本。

#### 需标记的子字符串（不区分大小写）

| 子字符串 | 说明 |
|---------|------|
| `lorem ipsum` | 拉丁占位文本 |
| `TODO` | 未完成的标记 |
| `FIXME` | 需要修复的标记 |
| `test test` | 测试内容 |
| `placeholder` | 占位符标记 |
| `xxx` | 独立单词时的占位符 |

报告内容包括：实体 ID、受影响的版本（线上 vs 暂存）、匹配的子字符串。

资料来源：[skills/client-handoff-checklist/SKILL.md:28-36]()

---

## 输出格式规范

### 检查结果标记

每项检查使用 `[OK]`、`[WARN]` 或 `[FAIL]` 标记，并附一行简要说明。必须使用纯文本标记，除非用户明确要求使用 emoji。

### 未就绪报告示例

```
Handoff readiness: NOT READY
-----------------------------
[FAIL] 3 critical issues
[WARN] 8 warnings
[OK]  31 checks passed

Critical issues to fix before launch:
1. Home page has no meta_description (page ID 8fd2k3jq91pn)
2. 404 error page does not exist
3. Site identity missing logo

Warnings worth addressing:
- 2 pages have unpublished staged changes
- Blog has no posts published yet
- ...

Re-run this checklist after fixing the critical issues.
```

### 就绪报告示例

```
Handoff readiness: READY
-------------------------
[OK] 41 checks passed
[WARN] 2 warnings (non-blocking)

Non-blocking warnings:
- No social_profiles set in site identity
- Blog has only 1 published post

Ship it.
```

资料来源：[skills/client-handoff-checklist/SKILL.md:60-85]()

---

## 反模式与注意事项

### 必须避免的行为

| 反模式 | 说明 | 正确做法 |
|-------|------|---------|
| **自动修复** | 该技能是检查清单，不是修复工具 | 用户查看问题后自行决定处理方式 |
| **放宽标准** | 对明显问题视而不见 | 严格按照检查标准执行 |
| **跳过检查** | 忽略某些检查项 | 逐项执行所有检查 |

### 重要约束

1. **元数据更新无暂存**：`meta_title`、`meta_description`、`meta_robots`、`canonical_url`、`og_image_id` 等字段的更新会直接影响线上元数据，而非进入暂存区。
2. **不能依赖 `has_unpublished_changes: false`**：即使是已发布的页面也可能存在过时的元数据。
3. **MCP 工具参数校验**：调用工具前需验证参数格式，确保 `account_id` 正确。

资料来源：[skills/client-handoff-checklist/SKILL.md:52-56]()

---

## 与其他技能的关系

### 技能协同图

```mermaid
graph LR
    A[generate-location-pages] -->|生成大量页面| B[bulk-seo-audit]
    B -->|发现 SEO 问题| C[client-handoff-checklist]
    C -->|最终 QA 通过| D[交付客户]
    
    E[blog-post-from-outline] -->|生成博客文章| F[client-handoff-checklist]
```

### 技能对比

| 技能 | 用途 | 专注领域 |
|-----|------|---------|
| `client-handoff-checklist` | 上线前最终检查 | 站点完整性、元数据、配置正确性 |
| `bulk-seo-audit` | SEO 问题审计 | 标题长度、描述长度、H1、规范化链接 |
| `generate-location-pages` | 程序化 SEO | 批量生成地理位置页面 |
| `blog-post-from-outline` | 博客文章生成 | 从大纲创建草稿文章 |

资料来源：[README.md:1-15]()

---

## 使用场景

### 适用场景

- **代理工作流完成时**：agency 完成客户网站开发，准备交付
- **迁移后验证**：从 WordPress 迁移博客后检查配置
- **定期质量检查**：每 30-90 天对线上站点进行例行检查
- **重大更新后验证**：进行批量内容更新后确认所有配置正常

### 不适用场景

- 正在进行中的开发工作（会产生大量误报）
- 需要修复问题的场景（应使用其他技能或手动修复）

---

## 快速参考

### 调用示例

```
运行客户端交接检查，账户 ID 为 YOUR_ACCOUNT_ID。
```

### 输出内容

1. 按类别分组的检查结果（`[OK]`、`[WARN]`、`[FAIL]`）
2. 关键问题列表（包含实体 ID 以便快速定位）
3. 最终就绪状态判定
4. 后续建议

### 建议的后续操作

| 检查结果 | 建议的后续操作 |
|---------|--------------|
| 存在 FAIL 项 | 修复问题后重新运行检查清单 |
| 全部通过但有 WARN | 根据业务需求决定是否处理警告项 |
| 全部通过 | 网站可交付客户 |

---

<a id='page-contributing'></a>

## 贡献指南

### 相关页面

相关主题：[项目概述](#page-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [CONTRIBUTING.md](https://github.com/BrightSiteHQ/skills/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/BrightSiteHQ/skills/blob/main/README.md)
- [skills/blog-post-from-outline/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/blog-post-from-outline/SKILL.md)
- [skills/bulk-seo-audit/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/bulk-seo-audit/SKILL.md)
- [skills/generate-location-pages/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/generate-location-pages/SKILL.md)
- [skills/client-handoff-checklist/SKILL.md](https://github.com/BrightSiteHQ/skills/blob/main/skills/client-handoff-checklist/SKILL.md)
</details>

# 贡献指南

本文档描述了如何为 BrightSite Skills 项目贡献新的技能（Skills），包括技能的设计原则、创建流程、代码规范以及错误报告机制。

## 项目概述

BrightSite Skills 是一个为 [BrightSite](https://onbrightsite.com) 平台设计的 Claude 技能集合，旨在帮助代理商自动化网站管理、内容创建和 SEO 优化等工作流程。

资料来源：[README.md:1-9]()

## 优秀技能的标准

一个技能要被接受，必须满足以下三个核心条件：

### 必须是真实工作流程

技能应该编码你在实际客户网站上运行过的工作流程，而非假设性的功能。BrightSite 团队倾向于接收经过实战验证的技能实现。

### 必须基于现有 MCP 工具

技能必须映射到当前 BrightSite MCP 服务器已提供的工具。如果工作流程需要不存在的工具，应先提交 issue 讨论添加工具的可能性，而不是创建无法执行的技能。

### 必须防止模型犯错

最有价值的部分通常是"应避免的反模式"（Anti-patterns to avoid）。技能应该帮助 AI 模型避免常见的、会影响客户网站的错误。

资料来源：[CONTRIBUTING.md:6-18]()

## 创建新技能的流程

```mermaid
graph TD
    A[Fork 仓库] --> B[创建 SKILL.md 文件]
    B --> C[使用标准 frontmatter 格式]
    C --> D[引用规范的 MCP 工具名称]
    D --> E[在真实账户测试]
    E --> F[添加行到 README.md 表格]
    F --> G[提交 Pull Request]
```

### 步骤详解

#### 1. Fork 仓库

首先在 GitHub 上 fork `BrightSiteHQ/skills` 仓库到你的个人账户。

#### 2. 创建技能文件

在 `skills/` 目录下创建新文件夹，命名规则为 kebab-case 格式：

```
skills/<your-skill-name>/SKILL.md
```

每个技能文件对应一个独立的工作流程，不要在一个文件中塞入多个功能。

#### 3. 使用标准 frontmatter

每个 SKILL.md 必须包含以下 YAML frontmatter：

| 字段 | 描述 | 示例 |
|------|------|------|
| `name` | 技能唯一标识符 | `blog-post-from-outline` |
| `description` | 触发技能的自然语言描述 | 包含"draft a blog post"、"write a post from this outline"等短语 |

frontmatter 之后跟随 markdown 格式的技能说明文档。

#### 4. 引用 MCP 工具规范

使用标准的 `mcp__brightsite__<tool>` 格式引用工具，例如：

- `mcp__brightsite__list_pages`
- `mcp__brightsite__create_page`
- `mcp__brightsite__get_post`

不要自行发明不存在的工具名称。

#### 5. 测试验证

在提交前，必须在真实的 BrightSite 账户（或测试账户）上运行技能验证其功能。如果无法提供测试账户，请在 PR 中说明，团队会协助运行测试。

#### 6. 更新文档

在 `README.md` 的技能列表表格中添加新技能的条目。

资料来源：[CONTRIBUTING.md:20-30]()

## 技能文档结构规范

### 必须包含的章节

| 章节 | 说明 |
|------|------|
| 描述头部 | 使用场景和限制 |
| 工具列表 | 使用的 MCP 工具 |
| 输入参数 | 用户需要提供的信息 |
| 工作流程 | 步骤说明 |
| 反模式 | 应避免的错误 |

### 描述性要求

**要具体**：避免模糊的描述如"验证输入"。应该写成"在调用 `mcp__brightsite__create_page` 前，将 `redirect_type` 从字符串转换为整数"。

**标注危险步骤**：每个技能都有一个潜在的危险操作，需要在文档中明确标注。

**禁止营销语言**：避免使用"强大的"、"无缝的"、"健壮的"等词汇。这些对模型理解技能无益。

**禁止表情符号**：技能输出中不应使用 emoji，除非用户明确要求。

资料来源：[CONTRIBUTING.md:32-42]()

## 技能使用示例

以下是常见的使用场景描述方式，这些描述会触发相应技能的自动加载：

| 用户输入示例 | 触发技能 |
|-------------|----------|
| "I have a WordPress export I need to import into account `8fd2k3jq91pn`" | `redirect-map-from-csv` |
| "Generate location pages for these 40 cities" | `generate-location-pages` |
| "Run an SEO audit on this site before we hand it off" | `bulk-seo-audit` |
| "Draft a blog post from this outline" | `blog-post-from-outline` |

资料来源：[README.md:40-47]()

## 账户 ID 说明

BrightSite 账户 ID 是未前缀的 NanoID 格式，示例：`8fd2k3jq91pn`。可以在以下位置找到：

- 仪表板 URL 中
- **Settings → API** 页面

在技能文档中，`YOUR_ACCOUNT_ID` 占位符需要替换为实际 ID。

资料来源：[README.md:48-51]()

## 错误报告流程

当发现技能与 MCP 实际行为不符时，应提交 GitHub Issue，包含以下信息：

### 必填信息

| 信息项 | 说明 |
|--------|------|
| 技能名称 | 出问题的技能标识 |
| MCP 工具调用 | 请求和响应的完整内容 |
| 期望行为 | 应该产生什么结果 |
| 实际行为 | 实际发生了什么 |

### 优先级说明

当技能与当前 MCP schema 不对齐时（如字段重命名、工具添加等），属于高优先级修复，应在 Issue 标题中标注。

资料来源：[CONTRIBUTING.md:44-54]()

## 质量检查清单

在提交技能前，确认以下检查项：

- [ ] frontmatter 包含 `name` 和 `description` 字段
- [ ] 文件路径使用 kebab-case 命名
- [ ] MCP 工具引用使用标准 `mcp__brightsite__` 前缀
- [ ] 包含"反模式"章节
- [ ] 所有步骤都有具体说明
- [ ] 不含 emoji 或营销用语
- [ ] 已在 README.md 表格中注册
- [ ] 在真实账户测试通过

## 许可协议

通过贡献代码，你同意你的贡献将采用本仓库中 MIT 协议授权。

资料来源：[CONTRIBUTING.md:56-58]()

## 相关资源

| 资源 | 链接 |
|------|------|
| BrightSite 官网 | https://onbrightsite.com |
| MCP 服务 | https://onbrightsite.com/mcp |
| GitHub 仓库 | https://github.com/BrightSiteHQ/skills |

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：BrightSiteHQ/skills

摘要：发现 12 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...。

## 1. 安装坑 · 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...

- 严重度：medium
- 证据强度：source_linked
- 发现：I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ...

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1240228986 | https://github.com/BrightSiteHQ/skills | host_targets=mcp_host, claude, claude_code, cursor, chatgpt

## 3. 能力坑 · 社区讨论暴露的待验证问题：GitHub Coding Agent Alternatives? : r/ClaudeAI - Reddit

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub Coding Agent Alternatives? : r/ClaudeAI - Reddit 24 Jun 2025 · I built a workflow tool for running multiple or custom agents for coding. ... I maintain an open-source library of 181 agent skills. I ...
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:reddit | ssig_8721fba6b9124b6c808eacc107d6dc1d | https://www.reddit.com/r/ClaudeAI/comments/1ljf9kn/github_coding_agent_alternatives/ | GitHub Coding Agent Alternatives? : r/ClaudeAI - Reddit

## 4. 能力坑 · 社区讨论暴露的待验证问题：I built Muninn, an open-source proxy for AI coding agents like Claude ...

- 严重度：medium
- 证据强度：source_linked
- 发现：I built Muninn, an open-source proxy for AI coding agents like Claude ... 12 Jan 2026 · We built an open-source coding agent CLI that can be run locally ... Turn 10,000 API endpoints into one CLI tool instead of MCP, Skills and tools ...
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:reddit | ssig_6102ff6da0284536abb5e26f2533abed | https://www.reddit.com/r/LocalLLaMA/comments/1qai4ul/i_built_muninn_an_opensource_proxy_for_ai_coding/ | I built Muninn, an open-source proxy for AI coding agents like Claude ...

## 5. 能力坑 · 社区讨论暴露的待验证问题：OSS alternatives to Claude Code as an agent foundation? : r/LocalLLaMA

- 严重度：medium
- 证据强度：source_linked
- 发现：OSS alternatives to Claude Code as an agent foundation? : r/LocalLLaMA 4 Dec 2025 · - Tool/MCP & domain-knowledge/skills integration that actually works reliably - ... https://github.com/ovh/shai Open source and you can add ...
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:reddit | ssig_b9197826c5ca4b98befca959e370dc3d | https://www.reddit.com/r/LocalLLaMA/comments/1peern1/oss_alternatives_to_claude_code_as_an_agent/ | OSS alternatives to Claude Code as an agent foundation? : r/LocalLLaMA

## 6. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1240228986 | https://github.com/BrightSiteHQ/skills | README/documentation is current enough for a first validation pass.

## 7. 运行坑 · 社区讨论暴露的待验证问题：you need somewhere between 1-10 Claude skills depending on what ...

- 严重度：medium
- 证据强度：source_linked
- 发现：you need somewhere between 1-10 Claude skills depending on what ... 20 Mar 2026 · https://github.com/haris-musa/excel-mcp-server ... Claude Inspector — See hidden Claude Code prompt mechanics https://github.com/kangraemin/claude ...
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:x | ssig_504e57203f64433a83bf7ec96631f94c | https://x.com/Hesamation/status/2035136966719582695 | you need somewhere between 1-10 Claude skills depending on what ...

## 8. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1240228986 | https://github.com/BrightSiteHQ/skills | last_activity_observed missing

## 9. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1240228986 | https://github.com/BrightSiteHQ/skills | no_demo; severity=medium

## 10. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1240228986 | https://github.com/BrightSiteHQ/skills | no_demo; severity=medium

## 11. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1240228986 | https://github.com/BrightSiteHQ/skills | issue_or_pr_quality=unknown

## 12. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1240228986 | https://github.com/BrightSiteHQ/skills | release_recency=unknown

<!-- canonical_name: BrightSiteHQ/skills; human_manual_source: deepwiki_human_wiki -->