# https://github.com/Shanksg/clawskills 项目说明书
生成时间：2026-05-13 12:47:35 UTC
## 目录
- [项目概述](#page-overview)
- [项目结构](#page-project-structure)
- [MCP 服务器架构](#page-mcp-server-architecture)
- [MCP 工具接口](#page-mcp-tools)
- [技能文档结构](#page-skill-anatomy)
- [技能目录总览](#page-skill-catalog)
- [跨工具工作流剧本](#page-playbooks)
- [部署指南](#page-deployment)
- [持续集成与发布](#page-cicd)
- [贡献指南](#page-contributing)
## 项目概述
### 相关页面
相关主题：[项目结构](#page-project-structure), [技能目录总览](#page-skill-catalog)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)
- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)
- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)
- [skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)
- [skills/jira/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)
- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)
- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)
- [skills/stripe/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/stripe/skill.md)
- [skills/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)
- [skills/servicenow/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/servicenow/skill.md)
- [skills/dynamics365/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/dynamics365/skill.md)
- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)
# 项目概述
## 项目简介
clawskills 是一个开源的技能文档库（Skills Repository），旨在为 AI 助手提供与主流第三方工具和服务集成的标准化指南。该项目通过结构化的 Markdown 文档，记录了 14 种常用工具的 API 认证方式、速率限制、错误处理和工作流配方，使 AI 代理能够准确、可靠地与这些平台交互。
该项目核心价值在于**降低 AI 集成错误率**。开发者可以引用对应工具的技能文档，让 AI 遵循正确的认证流程、速率限制处理方式和错误代码规范，而非依赖不完整或过时的知识。
资料来源：[README.md:1]()
## 核心架构
### 整体架构
```mermaid
graph TD
A[clawskills 仓库] --> B[技能文档库 skills/]
A --> C[剧本库 playbooks/]
A --> D[MCP 服务器 clawskills-mcp]
B --> E[14 个工具技能文档]
E --> E1[Monday.com]
E --> E2[Salesforce]
E --> E3[Jira]
E --> E4[Dynamics 365]
E --> E5[HubSpot]
E --> E6[ServiceNow]
E --> E7[Zendesk]
E --> E8[Asana]
E --> E9[GitHub]
E --> E10[Figma]
E --> E11[Slack]
E --> E12[Stripe]
E --> E13[Notion]
E --> E14[Linear]
D --> F[list_skills]
D --> G[get_skill]
D --> H[search_skills]
```
### MCP 服务器工具
clawskills 提供了 MCP（Model Context Protocol）服务器，使 Claude 等 AI 助手能够动态查询技能文档。MCP 服务器提供三个核心工具：
| 工具名称 | 功能描述 |
|---------|---------|
| `list_skills` | 列出所有可用的技能文档 |
| `get_skill` | 获取完整的技能文档或指定章节（如 `auth`、`rate-limits`、`recipes`、`errors`） |
| `search_skills` | 在所有技能文档中进行全文搜索 |
资料来源：[README.md:1]()
## 技能文档结构
### 必选章节
每个工具的技能文档（`skill.md`）必须包含 **11 个标准章节**，确保文档的完整性和一致性：
```mermaid
graph LR
A[必选章节] --> B[认证与权限]
A --> C[核心资源与字段]
A --> D[速率限制与重试]
A --> E[错误代码处理]
A --> F[常见工作流]
A --> G[最佳实践]
A --> H[故障排除]
A --> I[QA 检查清单]
A --> J[来源链接]
A --> K[最后验证日期]
```
资料来源：[README.md:1]()
### 认证模式对比
| 认证方式 | 适用场景 | 代表性工具 |
|---------|---------|-----------|
| Personal Access Token (PAT) | 服务器到服务器集成 | Figma、Linear、GitHub |
| OAuth 2.0 | 用户授权应用 | Figma、Linear、Slack、Stripe |
| API Key / Bearer Token | 标准 REST API | Jira、ServiceNow、Dynamics 365、HubSpot、Notion、Stripe |
| 基本认证 (Basic Auth) | 简单场景 | Zendesk |
资料来源：[skills/figma/skill.md:1]()[skills/linear/skill.md:1]()[skills/slack/skill.md:1]()
## 支持的工具列表
### 工具覆盖范围
| 工具名称 | 主要功能 | API 类型 | 关键认证方式 |
|---------|---------|---------|------------|
| Monday.com | 项目管理与工作流 | REST | OAuth 2.0 + API Token |
| Salesforce | CRM 与销售自动化 | REST + OAuth | Connected App |
| Jira | 敏捷项目与缺陷跟踪 | REST | API Token / OAuth |
| Dynamics 365 | 企业 ERP/CRM | OData REST | OAuth 2.0 |
| HubSpot | 营销与 CRM | REST + Webhooks | Private App Token |
| ServiceNow | IT 服务管理 | REST | OAuth 2.0 / Basic Auth |
| Zendesk | 客服与支持工单 | REST | API Token |
| Asana | 团队协作与任务管理 | REST | Personal Access Token |
| GitHub | 代码托管与 DevOps | REST + GraphQL | Personal Access Token |
| Figma | 设计与协作 | REST | Personal Access Token / OAuth |
| Slack | 企业通讯与自动化 | Web API | Bot Token / User Token |
| Stripe | 支付与订阅管理 | REST + Webhooks | Secret Key |
| Notion | 文档与知识管理 | REST | Internal Integration Token |
| Linear | 开发者项目追踪 | GraphQL | API Key / OAuth |
资料来源：[README.md:1]()[skills/ROADMAP.md:1]()
## 工作流程配方
### 跨工具编排示例
项目中包含跨系统的剧本（Playbook），展示如何编排多个工具的集成：
#### Slack-Jira 事故处理剧本
```mermaid
sequenceDiagram
participant S as Slack
participant B as Bot
participant J as Jira API
participant L as Linear API
S->>B: 触发事件
(reaction_added / message)
B->>S: 获取消息 permalink
B->>J: 搜索关联 Issue
alt 存在关联 Issue
B->>S: 回复已有 Issue 链接
else 无关联 Issue
B->>J: 创建新 Issue
B->>S: 回复新 Issue 链接
end
```
**字段映射规则：**
| Slack 事件字段 | Jira 相关字段 |
|---------------|--------------|
| `event.item.channel` + `event.item.ts` | Correlation Key |
| 消息文本（首句，截断至 ~120 字符） | Issue Summary |
| 消息内容 + Thread 回复 | Issue Description |
| 触发事件的频道 | Issue Project / Components |
| Slack Permalink | Description 中的链接 |
资料来源：[playbooks/slack-jira-incident.md:1]()
## 开发流程
### 贡献者工作流
```mermaid
graph LR
A[创建分支
git checkout -b skill/] --> B[遵循模板结构
11 个必选章节]
B --> C[验证端点与速率限制
对照官方文档]
C --> D[添加 Last validated 日期]
D --> E[更新 INDEX.md
和 README.md]
E --> F[添加 Sources 链接]
F --> G[提交 PR
CI 运行 npm test]
```
### 分支命名规范
| 分支类型 | 命名格式 | 示例 |
|---------|---------|-----|
| 新增工具技能 | `skill/` | `skill/notion` |
| 功能改进 | `feat/` | `feat/add-vertex-ai` |
| 文档修复 | `fix/` | `fix/correct-oauth-url` |
资料来源：[README.md:1]()
### CI/CD 流水线
| 阶段 | 触发条件 | 验证内容 |
|-----|---------|---------|
| 构建测试 | 每次 Push / PR | `npm test` 执行单元测试 |
| 技能验证 | PR 提交时 | 必选章节完整性、最小文件大小（≥5 KB）、所有 14 个工具验证 |
| 发布 | GitHub Actions → Release Workflow | patch / minor / major 版本选择、npm publish |
资料来源：[skills/ROADMAP.md:1]()
## 版本与发布
### 自动化发布
项目使用 GitHub Actions 实现自动化发布流程：
```mermaid
graph TD
A[合并到 main 分支] --> B[手动触发 Release Workflow]
B --> C{版本类型选择}
C -->|patch| D[0.0.x 补丁版本]
C -->|minor| E[0.x.0 次版本]
C -->|major| F[x.0.0 主版本]
D --> G[更新版本号]
E --> G
F --> G
G --> H[创建 Git Tag]
H --> I[npm publish]
I --> J[生成 Release Notes]
```
发布流程通过 OIDC（OpenID Connect）身份验证确保安全性，无需存储长期 npm 凭据。
资料来源：[skills/ROADMAP.md:1]()
## 安装与使用
### MCP 服务器安装
**临时使用（npx 方式）：**
```bash
npx -y clawskills-mcp
```
**全局安装：**
```bash
npm install -g clawskills-mcp
```
**Claude Desktop 配置示例：**
```json
{
"mcpServers": {
"clawskills": {
"command": "npx",
"args": ["-y", "clawskills-mcp"]
}
}
}
```
资料来源：[README.md:1]()
### 在项目中使用
开发者可以通过在 `.claude/CLAUDE.md` 文件中配置项目指令，引导 AI 始终使用对应的技能文档：
```markdown
# Integration Skills
当编写与以下工具集成的代码时，始终先阅读对应技能文档：
- Jira → @skills/jira/skill.md
- Slack → @skills/slack/skill.md
- GitHub → @skills/github/skill.md
- ... 其他工具
遵循文档中的认证模式、速率限制处理和错误代码规范。
```
资料来源：[README.md:1]()
## 开发路线图
### 当前完成状态
| 阶段 | 主题 | 状态 | 说明 |
|-----|------|------|------|
| Phase 1 | 基础（认证 + 核心 CRUD） | ✅ 完成 | 14 个工具全覆盖 |
| Phase 2 | 高频工作流 | ✅ 完成 | 每个工具 6-12 个配方 |
| Phase 3 | 事件驱动与实时 | ✅ 完成 | Webhook 设置与签名验证 |
| Phase 4 | 批量与高级操作 | ⚠️ 部分 | 大多数工具已记录，>500 条记录示例未全部完成 |
| Phase 5 | 跨工具编排 | ❌ 未开始 | INDEX.md 中有模式描述，无专门配方 |
资料来源：[skills/ROADMAP.md:1]()
### 未来发展方向
**优先级 1 — 内容准确性流水线**
随着供应商 API 持续演进，维护准确性将成为项目核心竞争优势。计划包括：
- 自动化验证官方文档变更
- 社区贡献审核机制
- 供应商 API 变更告警系统
资料来源：[skills/ROADMAP.md:1]()
## 项目结构
```
clawskills/
├── README.md # 项目主文档
├── skills/
│ ├── INDEX.md # 技能索引
│ ├── ROADMAP.md # 开发路线图
│ ├── figma/
│ │ └── skill.md
│ ├── github/
│ │ └── skill.md
│ ├── jira/
│ │ └── skill.md
│ ├── linear/
│ │ └── skill.md
│ ├── monday/
│ │ └── skill.md
│ ├── salesforce/
│ │ └── skill.md
│ ├── servicenow/
│ │ └── skill.md
│ ├── slack/
│ │ └── skill.md
│ ├── stripe/
│ │ └── skill.md
│ ├── notion/
│ │ └── skill.md
│ ├── dynamics365/
│ │ └── skill.md
│ ├── hubspot/
│ │ └── skill.md
│ ├── asana/
│ │ └── skill.md
│ └── zendesk/
│ └── skill.md
├── playbooks/
│ └── slack-jira-incident.md # 跨工具剧本
└── .github/
└── workflows/
├── ci.yml # CI 测试流水线
└── release.yml # 自动化发布
```
资料来源：[README.md:1]()[skills/ROADMAP.md:1]()
## 许可证与贡献
本项目采用 MIT 许可证开源，完全公开可用。项目欢迎社区贡献，所有贡献者需遵循以下准则：
1. 每个技能文档必须包含全部 11 个必选章节
2. 所有端点、速率限制和认证流程必须对照官方文档验证
3. 必须在文档中标注 "Last validated" 日期
4. 必须链接官方来源，禁止无验证的声明
资料来源：[README.md:1]()[skills/ROADMAP.md:1]()
---
## 项目结构
### 相关页面
相关主题：[项目概述](#page-overview), [MCP 服务器架构](#page-mcp-server-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)
- [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)
- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)
- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)
- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)
- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
# 项目结构
## 概述
`clawskills` 是一个技能文档（Skills Documentation）仓库，旨在为 AI 工具提供标准化的第三方 API 集成指南。每个技能文档涵盖单一工具（如 Jira、Figma、Linear）的认证方式、API 端点、速率限制、错误处理和工作流程。
```mermaid
graph TD
A[clawskills 仓库] --> B[skills/ 技能文档]
A --> C[mcp-server/ MCP服务器]
A --> D[playbooks/ 工作流剧本]
B --> B1[figma/skill.md]
B --> B2[jira/skill.md]
B --> B3[linear/skill.md]
B --> B14[... 共14个工具]
C --> C1[src/index.ts]
C --> C2[src/index.test.ts]
D --> D1[zendesk-jira-bug-escalation.md]
D --> D2[hubspot-asana-onboarding.md]
```
## 目录结构
```
clawskills/
├── README.md # 仓库主文档
├── package.json # npm 包配置
├── skills/ # 技能文档目录
│ ├── INDEX.md # 技能索引
│ ├── ROADMAP.md # 开发路线图
│ ├── figma/skill.md # Figma 技能文档
│ ├── github/skill.md # GitHub 技能文档
│ ├── hubspot/skill.md # HubSpot 技能文档
│ ├── jira/skill.md # Jira 技能文档
│ ├── linear/skill.md # Linear 技能文档
│ ├── monday/skill.md # Monday.com 技能文档
│ ├── notion/skill.md # Notion 技能文档
│ ├── salesforce/skill.md # Salesforce 技能文档
│ ├── servicenow/skill.md # ServiceNow 技能文档
│ ├── slack/skill.md # Slack 技能文档
│ ├── stripe/skill.md # Stripe 技能文档
│ ├── zendesk/skill.md # Zendesk 技能文档
│ ├── asana/skill.md # Asana 技能文档
│ └── dynamics365/skill.md # Dynamics 365 技能文档
├── playbooks/ # 工作流剧本目录
│ ├── INDEX.md # 剧本索引
│ ├── zendesk-jira-bug-escalation.md
│ └── hubspot-asana-onboarding.md
└── mcp-server/ # MCP 服务器实现
├── README.md # MCP 服务器文档
├── package.json # MCP 服务包配置
└── src/
├── index.ts # 主服务器逻辑
└── index.test.ts # 单元测试
```
## 技能文档结构（skill.md）
每个工具的技能文档都遵循统一的 11 节模板结构，确保一致性和完整性。资料来源：[skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)
| 章节 | 用途 |
|------|------|
| Overview | 工具简介、认证前置条件 |
| Authentication & permissions | 认证方式、权限范围 |
| Reliability: rate limits, retries, idempotency | 速率限制、重试策略 |
| Error handling & troubleshooting | 错误码、调试技巧 |
| Common workflows (recipes) | 常用 API 调用模式（6-12 个） |
| Webhooks | 事件订阅、签名验证 |
| Available tools / API endpoints | 端点清单 |
| Data model: entities & fields | 数据实体、字段说明 |
| Pagination | 分页方式 |
| Code samples | 代码示例 |
| Resources & references | 官方文档链接 |
### 技能覆盖的工具
仓库目前包含 **14 个主要工具**的技能文档：
| 工具 | 主要功能 |
|------|----------|
| Figma | 设计协作、组件导出 |
| GitHub | 代码仓库、Issue、PR |
| HubSpot | CRM、营销自动化 |
| Jira | 项目追踪、Bug 管理 |
| Linear | 敏捷项目管理 |
| Monday.com | 团队协作 |
| Notion | 文档、知识库 |
| Salesforce | 企业 CRM |
| ServiceNow | IT 服务管理 |
| Slack | 团队通讯 |
| Stripe | 支付处理 |
| Zendesk | 客服工单 |
| Asana | 任务管理 |
| Dynamics 365 | 微软企业套件 |
## MCP 服务器架构
MCP（Model Context Protocol）服务器是 Claude AI 与技能文档之间的桥梁，允许 AI 动态查询技能信息。资料来源：[mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)
```mermaid
graph LR
A[Claude AI] -->|list_skills| B[MCP 服务器]
A -->|get_skill| B
A -->|search_skills| B
A -->|list_playbooks| B
A -->|get_playbook| B
A -->|search_playbooks| B
B -->|读取| C[skills/*.md]
B -->|读取| D[playbooks/*.md]
B -->|JSON响应| A
```
### MCP 工具接口
| 工具名 | 功能 |
|--------|------|
| `list_skills` | 列出所有可用技能 |
| `get_skill` | 获取完整技能文档或指定章节 |
| `search_skills` | 全文搜索技能文档 |
| `list_playbooks` | 列出所有工作流剧本 |
| `get_playbook` | 获取指定剧本内容 |
| `search_playbooks` | 搜索剧本内容 |
| `search_clawskills` | 全局搜索 |
资料来源：[mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)
### 技能加载机制
```typescript
// 从 skills/ 目录加载所有 .md 文件
function loadSkills(skillsDir: string): Map {
const skills = new Map();
const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
for (const entry of entries) {
if (!entry.isFile() || !entry.name.endsWith(".md") || entry.name === "INDEX.md") continue;
const slug = entry.name.replace(/\.md$/, "");
const content = fs.readFileSync(path.join(skillsDir, entry.name), "utf-8");
skills.set(slug, content);
}
return skills;
}
```
资料来源：[mcp-server/src/index.ts:1-15](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)
## 剧本（Playbooks）
剧本是跨工具的工作流集成方案，串联多个工具的 API 实现复杂业务场景。资料来源：[playbooks/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/INDEX.md)
### 当前剧本
| 剧本名称 | 描述 |
|----------|------|
| `zendesk-jira-bug-escalation` | Zendesk 工单自动升级到 Jira Bug |
| `hubspot-asana-onboarding` | HubSpot 联系人同步到 Asana 任务 |
### 剧本搜索功能
剧本支持以下搜索参数：
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `query` | string | 是 | 搜索词，如 "idempotency"、"rollback"、"closed won" |
## 开发流程与贡献规范
### 添加新技能的流程
1. **创建分支**：`git checkout -b skill/`
2. **遵循模板**：参照现有 `skill.md` 的 11 节结构
3. **验证准确性**：对照官方文档确认端点、速率限制和认证流程
4. **添加验证日期**：在文档头部添加 `Last validated:` 日期
5. **更新索引**：修改 `skills/INDEX.md` 和 `README.md`
6. **引用来源**：在 `Sources` 章节提供官方文档链接
7. **提交 PR**：CI 会运行 `npm test` 验证格式
### 质量保证
| 测试项 | 说明 |
|--------|------|
| 技能加载测试 | 所有 14 个工具技能必须可加载 |
| 摘要行检查 | 每个技能必须有非空摘要 |
| 章节完整性 | 必须包含全部 11 个必需章节 |
| 文件大小 | 每个技能文件至少 5KB |
```typescript
it("every skill file is at least 5KB", () => {
for (const [slug, content] of skills.entries()) {
expect(content.length, `${slug}: suspiciously short skill file`)
.toBeGreaterThan(5000);
}
});
```
资料来源：[mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)
## 发布与自动化
### 发布流程
1. 合并 PR 到 `main` 分支
2. 进入 GitHub Actions → **Release** 工作流
3. 点击 "Run workflow"
4. 选择版本类型：`patch` / `minor` / `major`
### CI/CD 流水线
| 组件 | 功能 |
|------|------|
| `ci.yml` | 构建 + 测试（每次 push/PR） |
| `release.yml` | 版本发布、npm 包发布（通过 OIDC） |
资料来源：[skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
## 章节别名系统
MCP 服务器支持灵活的章节查询，使用别名快速定位内容：
| 别名 | 对应章节 |
|------|----------|
| `auth` / `authentication` | Authentication & permissions |
| `rate-limits` / `rate_limits` / `ratelimits` / `reliability` | Reliability: rate limits, retries, idempotency |
| `errors` / `error-handling` | Error handling & troubleshooting |
| `recipes` | Common workflows |
| `pagination` | Pagination |
| `webhooks` | Webhooks |
| `overview` | Overview |
| `fields` | Data model: entities & fields |
资料来源：[mcp-server/src/index.ts:60-80](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)
## 使用方式
### MCP 服务器安装
```bash
# 临时使用
npx -y clawskills-mcp
# 永久安装
npm install -g clawskills-mcp
```
### Claude Desktop 配置
```json
{
"mcpServers": {
"clawskills": {
"command": "npx",
"args": ["-y", "clawskills-mcp"]
}
}
}
```
资料来源：[README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## MCP 服务器架构
### 相关页面
相关主题：[MCP 工具接口](#page-mcp-tools), [项目结构](#page-project-structure)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)
- [mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)
- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)
- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)
- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)
# MCP 服务器架构
## 1. 概述
`clawskills-mcp` 是一个基于 **Model Context Protocol (MCP)** 的服务器实现，用于将 [ClawSkills](https://github.com/Shanksg/clawskills) 项目中的 API 集成技能文档以结构化的方式暴露给 AI agents。
### 1.1 核心定位
该 MCP 服务器充当 AI 代理与外部 API 集成文档之间的桥梁，使 AI 工具（如 Claude Desktop、Claude Code）能够动态获取 14 个工具的认证流程、速率限制、错误处理和工作流配方等关键信息。资料来源：[mcp-server/README.md:1-10]()
### 1.2 解决的问题
在 AI 编码助手执行跨平台集成任务时，传统的静态提示词方式难以保持 API 文档的时效性。MCP 服务器通过以下方式解决此问题：
- 提供动态查询接口，实时获取最新的 API 技能文档
- 支持全文检索，快速定位特定 API 端点或错误处理方案
- 解耦文档维护与 AI 推理逻辑，便于独立更新 API 文档
## 2. 系统架构
### 2.1 架构分层
```mermaid
graph TD
subgraph "客户端层"
A[Claude Desktop]
B[Claude Code]
C[其他 MCP 客户端]
end
subgraph "MCP 协议层"
D[MCP 协议处理器]
end
subgraph "clawskills-mcp 服务器"
E[工具路由]
F[文档加载器]
G[全文索引]
end
subgraph "数据层"
H[skills/\*.md 技能文档]
I[playbooks/\*.md 工作流文档]
J[skills/INDEX.md 索引]
end
A --> D
B --> D
C --> D
D --> E
E --> F
E --> G
F --> H
F --> I
G --> J
```
### 2.2 核心组件
| 组件 | 职责 | 文件位置 |
|------|------|----------|
| MCP 协议处理器 | 解析客户端请求，序列化和反序列化消息 | `mcp-server/src/` |
| 工具路由 | 根据工具名称分发请求到对应处理器 | `mcp-server/src/index.ts` |
| 文档加载器 | 读取和解析 Markdown 格式的技能文档 | `mcp-server/src/` |
| 全文索引 | 建立和维护文档内容的搜索索引 | `mcp-server/src/` |
## 3. 安装与部署
### 3.1 环境要求
| 要求 | 规格 |
|------|------|
| Node.js | >= 18.0.0 |
| 包管理器 | npm |
| 容器运行时 | Docker（可选） |
资料来源：[mcp-server/package.json]()
### 3.2 安装方式对比
| 方式 | 命令 | 适用场景 |
|------|------|----------|
| npx 即时运行 | `npx -y clawskills-mcp` | 临时使用、快速测试 |
| 全局安装 | `npm install -g clawskills-mcp` | 长期使用、命令行调用 |
| Docker 容器 | `docker build -t clawskills-mcp -f mcp-server/Dockerfile .` | 生产环境隔离部署 |
资料来源：[mcp-server/README.md:27-42]()
### 3.3 Docker 部署流程
```bash
# 1. 从仓库根目录构建镜像
docker build -t clawskills-mcp -f mcp-server/Dockerfile .
# 2. 运行容器
docker run --rm -i clawskills-mcp
```
Docker 方式确保了与宿主机环境的隔离，适合在生产环境中部署。
## 4. 客户端配置
### 4.1 Claude Desktop 配置
**配置文件路径：**
| 操作系统 | 路径 |
|----------|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
**配置结构：**
```json
{
"mcpServers": {
"clawskills": {
"command": "npx",
"args": ["-y", "clawskills-mcp"]
}
}
}
```
资料来源：[mcp-server/README.md:14-21]()
### 4.2 Claude Code 配置
| 作用域 | 配置文件位置 |
|--------|--------------|
| 项目级别 | `.claude/settings.json` |
| 全局级别 | `~/.claude/settings.json` |
配置格式与 Claude Desktop 相同，均使用 `mcpServers` 配置块。
## 5. 工具 API
MCP 服务器暴露以下四个核心工具：
### 5.1 工具总览
| 工具名称 | 功能描述 |
|----------|----------|
| `list_skills` | 列出所有可用的技能文档 slug 及其描述 |
| `get_skill` | 获取完整的技能文档或指定章节内容 |
| `search_skills` | 在所有技能文档中执行全文搜索 |
| `list_playbooks` | 列出可用的跨工具工作流文档 |
资料来源：[mcp-server/README.md:44-49]()
### 5.2 list_skills
列出所有已注册的 API 集成技能。
**返回结构：**
```json
{
"skills": [
{
"slug": "jira",
"description": "Jira Cloud API integration guide"
},
{
"slug": "slack",
"description": "Slack Web API and Events API integration"
}
]
}
```
### 5.3 get_skill
获取指定技能文档的完整内容或特定部分。
**输入参数：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `slug` | string | 是 | 技能文档标识符 |
| `section` | string | 否 | 指定章节名称（如 `auth`、`rate-limits`） |
**section 参数可选值：**
| 章节标识 | 对应内容 |
|----------|----------|
| `auth` | 认证方式与权限配置 |
| `rate-limits` | API 速率限制与重试策略 |
| `errors` | 错误码与故障排查 |
| `recipes` | 常见工作流配方 |
资料来源：[mcp-server/README.md:44-49]()
### 5.4 search_skills
跨所有技能文档执行全文检索。
**使用场景：**
- 查找特定错误码的处理方案
- 搜索某个 API 端点的使用方法
- 发现所有涉及某项权限的文档
### 5.5 list_playbooks
列出跨工具自动化工作流文档。
**当前支持的 Playbook：**
| Playbook | 功能描述 |
|----------|----------|
| `slack-jira-incident` | Slack 消息触发 Jira 事件创建的自动化流程 |
资料来源：[playbooks/slack-jira-incident.md]()
## 6. 数据流与请求处理
### 6.1 请求处理流程
```mermaid
sequenceDiagram
participant C as Claude 客户端
participant M as MCP 服务器
participant D as 文档系统
participant I as 索引系统
C->>M: MCP 请求 (工具名 + 参数)
M->>M: 解析请求 JSON
alt list_skills / list_playbooks
M->>D: 加载索引文件
D-->>M: 返回项目列表
else get_skill
M->>D: 定位技能文档
D-->>M: 返回文档内容
alt 指定 section
M->>M: 提取章节内容
end
else search_skills
M->>I: 执行全文搜索
I-->>M: 返回匹配结果
end
M-->>C: 返回结果 JSON
```
### 6.2 技能文档结构
每个技能文档（`skills//skill.md`）遵循统一的 11 节结构：
| 章节 | 内容 |
|------|------|
| 头部元数据 | API 版本、最后验证日期 |
| 认证与权限 | OAuth、PAT、API Key 等认证方式 |
| 基础端点 | 核心 API 端点说明 |
| 常见工作流 | 5-12 个可复制的配方 |
| 速率限制 | 请求限额与复杂度计算 |
| 错误处理 | 错误码与故障排查 |
| Webhook 配置 | 事件订阅与签名验证 |
| 批量操作 | 大数据量处理模式 |
| 安全与合规 | 隐私保护建议 |
资料来源：[skills/notion/skill.md](), [skills/figma/skill.md]()
## 7. 支持的 API 集成
### 7.1 技能库覆盖
当前 ClawSkills 包含 **14 个工具**的完整 API 集成文档：
| 工具 | 主要功能 |
|------|----------|
| Monday.com | 项目管理、看板操作 |
| Salesforce | CRM 自动化 |
| Jira | 敏捷项目管理、缺陷追踪 |
| Dynamics 365 | 企业资源规划 |
| HubSpot | 营销自动化 |
| ServiceNow | IT 服务管理 |
| Zendesk | 客户支持 |
| Asana | 团队协作 |
| GitHub | 代码托管与 CI/CD |
| Figma | 设计协作 |
| Slack | 团队通讯 |
| Stripe | 支付处理 |
| Notion | 知识管理 |
| Linear | 开发者项目管理 |
资料来源：[mcp-server/README.md:4-7]()
### 7.2 跨工具编排
Phase 5（跨工具编排）处于规划阶段，计划实现多系统联动工作流，例如：
```mermaid
graph LR
A[Slack 告警] --> B{事件分类}
B -->|安全事件| C[创建 Jira Bug]
B -->|客户投诉| D[创建 Zendesk 工单]
C --> E[通知 Slack 频道]
D --> E
```
## 8. 错误处理与调试
### 8.1 常见配置错误
| 症状 | 原因 | 解决方案 |
|------|------|----------|
| MCP 服务器未启动 | npx 缓存问题 | 添加 `-y` 参数强制重新下载 |
| 工具调用超时 | 网络问题或文档过大 | 检查网络连接 |
| 搜索无结果 | 索引未更新 | 确认文档已正确放置在 `skills/` 目录 |
### 8.2 日志记录
MCP 服务器应在 DEBUG 模式下记录以下信息：
| 日志级别 | 记录内容 |
|----------|----------|
| INFO | 工具调用、文档加载成功 |
| WARN | 部分文档缺失、搜索结果为空 |
| ERROR | MCP 协议解析失败、文件系统错误 |
## 9. 安全考虑
### 9.1 敏感信息处理
| 信息类型 | 处理建议 |
|----------|----------|
| API Token | 不记录在日志中 |
| 用户数据 | 脱敏处理后再输出 |
| 错误详情 | 仅返回给授权客户端 |
### 9.2 权限控制
MCP 服务器本身不实现额外的访问控制，权限管理依赖于：
- Claude 客户端的认证机制
- 操作系统层面的文件系统权限
- Docker 容器的网络隔离策略
## 10. 维护与更新
### 10.1 文档更新流程
```mermaid
graph LR
A[更新 skill.md] --> B[添加 Last validated 日期]
B --> C[更新 skills/INDEX.md]
C --> D[提交 PR]
D --> E[CI 验证]
E --> F[合并到 main]
F --> G[自动发布新版本]
```
### 10.2 CI/CD 自动化
| 阶段 | 工具 | 验证内容 |
|------|------|----------|
| 构建 | GitHub Actions | 依赖安装、类型检查 |
| 测试 | Vitest | 单元测试 + 文档结构验证 |
| 发布 | release.yml | 版本号递增、npm 发布 |
资料来源：[skills/ROADMAP.md]()
## 11. 扩展指南
### 11.1 添加新技能
1. 创建分支：`git checkout -b skill/`
2. 遵循模板结构创建 `skill.md`，确保包含全部 11 个章节
3. 验证所有端点、速率限制和认证流程
4. 更新 `skills/INDEX.md` 和 `README.md`
5. 提交 PR 触发 CI 验证
### 11.2 添加新工具至 MCP 服务器
在 `mcp-server/src/index.ts` 中注册新的工具处理器：
```typescript
import { getSkill, searchSkills } from './handlers';
// 新增工具注册
server.registerTool('get_skill', getSkill);
server.registerTool('search_skills', searchSkills);
```
## 12. 参考资料
| 资料 | 链接 |
|------|------|
| GitHub 仓库 | https://github.com/Shanksg/clawskills |
| MCP 服务器源码 | `mcp-server/src/index.ts` |
| npm 包 | `clawskills-mcp` |
| 技能索引 | `skills/INDEX.md` |
---
## MCP 工具接口
### 相关页面
相关主题：[MCP 服务器架构](#page-mcp-server-architecture), [技能文档结构](#page-skill-anatomy)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)
- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
# MCP 工具接口
## 概述
MCP（Model Context Protocol）工具接口是 clawskills 项目为 AI 助手提供的标准化工具集，允许 Claude 等 AI 工具直接调用技能文档库中的内容。通过 MCP 协议，AI 可以在对话过程中实时获取各种第三方服务的集成指南、API 文档和工作流配方。
MCP 工具接口是 clawskills 项目与 AI 运行时之间的桥梁，提供了三大核心能力：
| 工具名称 | 功能描述 |
|---------|---------|
| `list_skills` | 列出所有可用的技能文档 |
| `get_skill` | 获取完整技能文档或特定章节 |
| `search_skills` | 全文本搜索所有技能文档 |
资料来源：[README.md:1-100]()
## 架构设计
### MCP 服务器角色
clawskills 的 MCP 服务器封装了对技能文档库的访问逻辑，作为中间层将 AI 的自然语言请求转换为结构化的文档查询。其核心职责包括：
1. **技能发现** — 维护技能索引，支持按名称或分类列出所有可用工具
2. **内容检索** — 按需加载完整的技能文档或指定章节
3. **全文搜索** — 跨所有技能文档执行关键词匹配
```mermaid
graph TD
A[Claude AI] -->|MCP Protocol| B[clawskills-mcp Server]
B --> C{请求类型}
C -->|list_skills| D[skills/INDEX.md]
C -->|get_skill| E[skills/{tool}/skill.md]
C -->|search_skills| F[全文索引]
D --> G[技能列表响应]
E --> H[完整文档/章节响应]
F --> I[搜索结果响应]
G --> A
H --> A
I --> A
```
### 工具与技能的映射关系
MCP 工具与底层技能文档的对应关系如下：
| MCP 工具 | 底层资源 | 返回内容 |
|---------|---------|---------|
| `list_skills` | `skills/INDEX.md` | 所有技能的索引列表 |
| `get_skill` | `skills/{tool}/skill.md` | 指定工具的完整文档 |
| `search_skills` | 所有 `skill.md` 文件 | 匹配的技能文档片段 |
资料来源：[README.md:80-90]()
## 安装与配置
### 临时运行方式
使用 npx 直接运行，无需本地安装：
```bash
npx -y clawskills-mcp
```
### 全局安装方式
将 MCP 服务器安装为全局 npm 包：
```bash
npm install -g clawskills-mcp
```
### Claude Desktop 配置
在 Claude Desktop 的配置文件中添加 MCP 服务器连接：
```json
{
"mcpServers": {
"clawskills": {
"command": "npx",
"args": ["-y", "clawskills-mcp"]
}
}
}
```
### Claude Code 配置
对于 Claude Code 项目，可在 `.claude/CLAUDE.md` 中配置为项目级指令：
```markdown
# Integration Skills
当编写与以下工具集成的代码时，始终在编写代码前阅读对应的技能文档：
- Monday.com → @skills/monday/skill.md
- Salesforce → @skills/salesforce/skill.md
- Jira → @skills/jira/skill.md
- HubSpot → @skills/hubspot/skill.md
- Zendesk → @skills/zendesk/skill.md
- GitHub → @skills/github/skill.md
- Figma → @skills/figma/skill.md
- Slack → @skills/slack/skill.md
- Stripe → @skills/stripe/skill.md
- Notion → @skills/notion/skill.md
- Linear → @skills/linear/skill.md
```
资料来源：[README.md:95-115]()
## 三大核心工具详解
### list_skills — 技能列表
列出所有已注册的技能文档，AI 可据此了解项目支持的集成范围。
**使用场景：**
- 探索项目能力边界
- 在不确定具体工具时浏览可用选项
- 验证特定工具是否在支持列表中
### get_skill — 技能获取
获取指定技能的完整文档或特定章节。支持的章节筛选包括：
| 章节标识 | 内容范围 |
|---------|---------|
| `auth` | 认证与授权流程 |
| `rate-limits` | 速率限制说明 |
| `recipes` | 工作流配方 |
| `errors` | 错误代码与处理 |
**使用场景：**
- 在开始集成前获取完整认证指南
- 调试时查阅特定错误代码含义
- 提取特定工作流配方
### search_skills — 全文搜索
跨所有技能文档执行关键词搜索，返回匹配结果。
**使用场景：**
- 快速定位包含特定 API 端点的技能
- 搜索特定错误消息的解决方案
- 查找包含特定认证机制的文档
## 支持的工具生态
当前 MCP 接口覆盖以下 14 种第三方工具：
| 类别 | 支持的工具 |
|------|-----------|
| 项目管理 | Jira, Asana, Monday.com, Linear, Notion |
| 客户关系 | Salesforce, HubSpot, Zendesk |
| 开发协作 | GitHub, Figma |
| 通信 | Slack |
| 支付 | Stripe |
| 企业系统 | Dynamics 365, ServiceNow |
资料来源：[skills/ROADMAP.md:1-50]()
## 开发阶段与路线图
根据项目路线图，MCP 工具接口已实现以下阶段：
| 阶段 | 内容 | 状态 |
|------|------|------|
| Phase 1 — 基础 | 认证流、基本 CRUD、重试模式 | ✅ 完成 |
| Phase 2 — 高频工作流 | 每个工具 6-12 个配方 | ✅ 完成 |
| Phase 3 — 事件驱动 | Webhook 设置、签名验证、事件处理 | ✅ 完成 |
| Phase 4 — 批量操作 | 批量 API、大容量模式 | ⚠️ 部分完成 |
| Phase 5 — 跨工具编排 | 跨 2+ 工具的多系统配方 | ❌ 未开始 |
资料来源：[skills/ROADMAP.md:50-80]()
### 未来发展方向
**优先级 1 — 新鲜度与准确性管道**
核心 14 工具库建立后的下一步是确保文档随供应商 API 变化保持准确：
- **Phase A** — 建立文档变更检测机制
- **Phase B** — 自动化验证与测试
- **Phase C** — 社区驱动的更新流程
资料来源：[skills/ROADMAP.md:80-100]()
## 最佳实践
### 在提示词中引用技能文档
| 目标 | 提示词结构 |
|------|-----------|
| 引用特定章节 | 粘贴目标章节内容，明确说明用途 |
| 完整技能作为上下文 | 将技能文档加载为系统提示词的一部分 |
**示例：**
```
[粘贴 skills/salesforce/skill.md 中的"Authentication & permissions"章节]
基于以上内容，编写一个将 JWT 兑换为访问令牌并缓存至过期前 5 分钟的 Python 函数。
```
### 遵循文档规范
使用 MCP 工具获取的技能文档时，应严格遵循其中的：
- 认证模式
- 速率限制处理
- 错误代码处理
- API 版本标头要求
## 持续集成与发布
项目维护以下自动化流程：
| 组件 | 功能 | 状态 |
|------|------|------|
| `ci.yml` | 每次 push/PR 触发构建与测试 | ✅ 运行中 |
| `release.yml` | 手动触发版本发布、npm 发布 | ✅ 运行中 |
| 测试套件 | Vitest 单元测试 + 真实技能验证 | ✅ 运行中 |
版本号遵循语义化版本（patch/minor/major），发布流程通过 GitHub Actions 手动触发。
资料来源：[skills/ROADMAP.md:20-30]()
## 相关资源
- NPM 包：`clawskills-mcp`
- MCP 协议版本：Model Context Protocol 标准
- 技能文档路径：`skills/{toolname}/skill.md`
- 索引文件：`skills/INDEX.md`
---
## 技能文档结构
### 相关页面
相关主题：[技能目录总览](#page-skill-catalog), [MCP 工具接口](#page-mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)
- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)
- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)
- [skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)
- [skills/jira/skill.md](https://github.com/Shanksg/Shanksg/clawskills/blob/main/skills/jira/skill.md)
- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)
- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)
- [skills/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)
- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)
# 技能文档结构
## 概述
技能文档（Skill Documentation）是 clawskills 项目的核心资产，为 14 种主流工具和平台提供标准化的 API 集成指南。这些文档采用统一模板编写，包含身份验证、速率限制、常见工作流、错误处理等 11 个必填章节，确保 AI 代理能够准确、可靠地与外部系统交互。
技能文档的主要作用包括：
- 为 AI 代理提供可信赖的集成参考
- 标准化跨平台的 API 调用模式
- 降低集成错误率和开发时间
- 支持 RAG（检索增强生成）流程
资料来源：[README.md:1-20](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## 文档模板结构
### 必填章节清单
每个技能文档必须包含以下 11 个章节，CI 测试会验证所有章节的完整性：
| 章节编号 | 章节名称 | 说明 |
|---------|---------|------|
| 1 | 概述 | 工具简介、API 版本、基础 URL |
| 2 | 身份验证与权限 | 认证方式、OAuth 流程、令牌管理 |
| 3 | 速率限制 | 请求配额、重试策略、复杂度过载 |
| 4 | 核心 API 端点 | 主要接口列表及参数说明 |
| 5 | 常见工作流（Recipes） | 典型使用场景的代码示例 |
| 6 | Webhook 配置 | 事件订阅、签名验证、负载结构 |
| 7 | 错误处理 | 错误代码分类、异常处理模式 |
| 8 | 安全与隐私 | 最佳实践、合规要求 |
| 9 | 相关资源 | 官方文档链接、示例代码 |
| 10 | 变更日志 | 版本历史、breaking changes |
| 11 | 维护指南 | 文档更新流程、验证要求 |
资料来源：[mcp-server/src/index.test.ts:1-30](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)
### 文档质量标准
```
┌─────────────────────────────────────────────┐
│ 技能文档质量检查 │
├─────────────────────────────────────────────┤
│ ✓ 所有 11 个必填章节完整 │
│ ✓ 摘要行非空 │
│ ✓ 文件大小 ≥ 5KB（内容充实度） │
│ ✓ 端点、速率限制、认证流程经官方文档验证 │
│ ✓ 包含 Last validated 日期 │
│ ✓ 链接到官方 Sources 章节 │
└─────────────────────────────────────────────┘
```
资料来源：[README.md:25-35](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## 技能库组织架构
### 目录结构
```
clawskills/
├── skills/
│ ├── INDEX.md # 技能总索引
│ ├── ROADMAP.md # 路线图和开发阶段
│ ├── asana/
│ │ └── skill.md
│ ├── dynamics365/
│ │ └── skill.md
│ ├── figma/
│ │ └── skill.md
│ ├── github/
│ │ └── skill.md
│ ├── hubspot/
│ │ └── skill.md
│ ├── jira/
│ │ └── skill.md
│ ├── linear/
│ │ └── skill.md
│ ├── monday/
│ │ └── skill.md
│ ├── notion/
│ │ └── skill.md
│ ├── salesforce/
│ │ └── skill.md
│ ├── servicenow/
│ │ └── skill.md
│ ├── slack/
│ │ └── skill.md
│ ├── stripe/
│ │ └── skill.md
│ └── zendesk/
│ └── skill.md
├── playbooks/ # 跨工具编排手册
│ └── slack-jira-incident.md
└── mcp-server/ # MCP 服务端实现
```
资料来源：[skills/ROADMAP.md:1-50](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
### 覆盖的工具
| 类别 | 工具 | 协议类型 |
|------|------|----------|
| 项目管理 | Jira, Linear, Monday.com, Asana | REST API / GraphQL |
| CRM/销售 | Salesforce, HubSpot, Dynamics 365 | REST API |
| 客服 | Zendesk, ServiceNow | REST API |
| 开发工具 | GitHub | REST API |
| 设计协作 | Figma | REST API |
| 消息 | Slack | Web API / WebSocket |
| 支付 | Stripe | REST API |
| 知识管理 | Notion | REST API |
---
## 章节内容详解
### 1. 身份验证与权限（Authentication & Permissions）
此章节描述与工具交互所需的认证机制，包括 API Key、OAuth 2.0、JWT 等方式。
**典型认证模式：**
| 认证方式 | 适用场景 | Token 位置 |
|---------|---------|-----------|
| API Key / PAT | 服务器到服务器集成 | Header: `Authorization: Bearer xxx` |
| OAuth 2.0 | 用户授权应用 | 先获取 code，再兑换 access_token |
| JWT | 服务账户 | 请求体或专用端点 |
| HMAC 签名 | Webhook 验证 | 请求头特定字段 |
**Figma 示例：**
```bash
# Personal Access Token
curl https://api.figma.com/v1/me \
-H "X-Figma-Token: YOUR_PAT"
```
**Linear 示例：**
```bash
curl -X POST https://api.linear.app/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token&refresh_token=&client_id=&client_secret="
```
资料来源：[skills/figma/skill.md:30-60](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)，[skills/linear/skill.md:20-45](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)
### 2. 速率限制（Rate Limits）
每个技能文档记录平台特定的速率限制策略。
**速率限制信息表结构：**
| 维度 | 说明 |
|------|------|
| 请求配额 | 每小时/每分钟允许的请求数 |
| 复杂度过载 | 基于查询复杂度的积分限制 |
| 突发限制 | 短期峰值容忍 |
| 响应头 | 返回剩余配额、重试时间 |
**Linear 速率限制示例：**
| 认证类型 | 请求/小时 | 复杂度积分/小时 | 单次查询最大积分 |
|---------|----------|----------------|-----------------|
| API key | 5,000 | 250,000 | 10,000 |
| OAuth app | 5,000 | 2,000,000 | 10,000 |
| 未认证 | 60 | 10,000 | 10,000 |
**响应头字段：**
| Header | 描述 |
|--------|------|
| `X-RateLimit-Requests-Limit` | 时间窗口内允许的总请求数 |
| `X-RateLimit-Complexity-Limit` | 复杂度积分上限 |
| `Retry-After` | 需要等待的秒数 |
资料来源：[skills/linear/skill.md:50-70](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)
### 3. 常见工作流（Recipes）
Recipes 提供针对典型使用场景的完整代码示例，通常包含：
- 场景描述
- 所需权限范围
- 完整可运行的代码片段
- 错误处理模式
**工作流类型分类：**
```mermaid
graph TD
A[Recipes 工作流] --> B[CRUD 操作]
A --> C[查询与过滤]
A --> D[Webhook 配置]
A --> E[批量操作]
A --> F[跨系统编排]
B --> B1[创建资源]
B --> B2[读取详情]
B --> B3[更新字段]
B --> B4[删除归档]
```
**Jira Recipe 示例：**
```bash
curl -s -X PUT "$BASE/rest/api/3/issue/PROJ-42" \
-H "Authorization: $AUTH" \
-H "Content-Type: application/json" \
-d '{
"fields": {
"labels": ["production", "urgent"]
}
}'
```
资料来源：[skills/jira/skill.md:80-100](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)
### 4. Webhook 配置
Webhook 章节描述事件订阅机制、签名验证和负载结构。
**Webhook 组件：**
| 组件 | 描述 |
|------|------|
| 端点注册 | 创建 webhook 的 API 调用 |
| 事件类型 | 可订阅的事件列表 |
| 签名验证 | HMAC/SHA256 验证方法 |
| 负载结构 | 请求体字段说明 |
**Slack Webhook 安全配置：**
```python
import hmac, hashlib, time
def verify_slack_signature(
signing_secret: str,
body: bytes,
timestamp: str,
signature: str
) -> bool:
base = f"v0:{timestamp}:{body.decode()}"
expected = "v0=" + hmac.new(
signing_secret.encode(),
base.encode(),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
```
**Jira Webhook 负载示例：**
```json
{
"timestamp": 1708357200000,
"webhookEvent": "jira:issue_updated",
"user": { "accountId": "5b10a..." },
"issue": {
"id": "10023",
"key": "PROJ-42",
"fields": { "status": {}, "summary": "..." }
},
"changelog": {
"items": [
{ "field": "status", "fromString": "In Progress", "toString": "Done" }
]
}
}
```
资料来源：[skills/slack/skill.md:100-120](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)，[skills/jira/skill.md:40-60](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)
### 5. 错误处理
错误处理章节列出 API 返回的错误代码和处理策略。
**错误响应模式：**
| 错误类型 | HTTP 状态码 | 处理策略 |
|---------|------------|---------|
| 认证失败 | 401 | 检查 token 有效性，刷新或重新授权 |
| 权限不足 | 403 | 确认应用具备所需 scopes |
| 资源不存在 | 404 | 验证 ID/键值是否正确 |
| 速率限制 | 429 | 读取 Retry-After，等待后重试 |
| 服务器错误 | 500-503 | 指数退避重试 |
**常见错误代码表：**
| 工具 | 错误代码 | 含义 |
|------|---------|------|
| Linear | `RATELIMITED` | 请求超出速率限制 |
| Linear | `ENTITY_NOT_FOUND` | 指定实体不存在 |
| Slack | `cant_update_message` | 无权修改该消息 |
| Jira | 多种 | 见 Jira 官方错误文档 |
资料来源：[skills/linear/skill.md:150-180](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)，[skills/slack/skill.md:140-160](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)
---
## Playbooks 跨工具编排
Playbooks 展示如何组合多个工具的 API 实现复杂业务流程。
### 编排结构
```mermaid
graph LR
A[Slack 事件] -->|消息/反应| B[事件提取]
B --> C[权限验证]
C --> D{事件类型判断}
D -->|incident| E[创建 Jira Issue]
D -->|变更| F[更新现有 Issue]
E --> G[回复 Slack 线程]
F --> G
G --> H[可选: 镜像状态回 Slack]
```
### 字段映射规则
Playbooks 定义工具间的数据映射关系：
| Slack 字段 | Jira 字段 |
|-----------|----------|
| `event.channel` + `event.ts` | correlation key |
| 消息文本（首句） | `summary` |
| 消息全文 + 链接 | `description` |
| 频道配置 | `priority`, `issuetype`, `project` |
| `slack-incident` 标签 | 标签标识 |
### 编排最佳实践
1. **幂等性设计**：相同事件多次触发应产生相同结果
2. **相关性检测**：创建前搜索现有 Issue 避免重复
3. **状态同步**：可选地将目标系统状态变化同步回源系统
4. **错误恢复**：记录失败状态，支持人工干预
资料来源：[playbooks/slack-jira-incident.md:1-50](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)
---
## 开发流程与贡献规范
### 添加新技能的步骤
1. 创建分支：`git checkout -b skill/`
2. 参考现有模板创建 `skill.md`
3. 验证端点、速率限制、认证流程
4. 在文档头部添加 `Last validated:` 日期
5. 更新 `skills/INDEX.md` 和 `README.md`
6. 在 `## Sources` 章节添加官方文档链接
7. 提交 PR 触发 CI 测试
### CI 测试流程
```mermaid
graph TD
A[提交 PR] --> B[npm test]
B --> C{所有测试通过?}
C -->|是| D[合并到 main]
C -->|否| E[显示失败详情]
E --> F[修复问题]
F --> A
B --> B1[加载所有技能]
B1 --> B2[验证 11 个必填章节]
B2 --> B3[验证摘要行非空]
B3 --> B4[验证文件 ≥ 5KB]
```
资料来源：[README.md:20-40](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## 版本与发布
### 发布自动化
发布流程通过 GitHub Actions 自动化：
1. 合并代码到 `main` 分支
2. 前往 GitHub Actions → **Release** 工作流
3. 运行工作流，选择版本类型：
- `patch`：补丁版本（bug 修复）
- `minor`：次版本（新功能）
- `major`：主版本（breaking changes）
### 版本命名规范
遵循语义化版本（Semantic Versioning）：
- **Major**：`X.0.0` — 不兼容的 API 变更
- **Minor**：`X.Y.0` — 向后兼容的新功能
- **Patch**：`X.Y.Z` — 向后兼容的问题修复
资料来源：[README.md:40-50](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## 使用方式
### MCP 服务集成
MCP 服务器提供三个核心工具：
| 工具名称 | 功能 |
|---------|------|
| `list_skills` | 列出所有可用的技能文档 |
| `get_skill` | 获取完整技能或指定章节 |
| `search_skills` | 全文本搜索所有技能 |
**安装命令：**
```bash
npx -y clawskills-mcp
```
**Claude Desktop 配置：**
```json
{
"mcpServers": {
"clawskills": {
"command": "npx",
"args": ["-y", "clawskills-mcp"]
}
}
}
```
### AI 代理集成模式
**模式 1 — 参考特定章节：**
```
[paste "Authentication & permissions" section]
使用上述内容，写一个 Python 函数交换 JWT 获取 access token 并缓存
```
**模式 2 — 完整技能作为系统上下文：**
加载技能文档作为系统提示词的一部分，由 LLM 在运行时参考。
**模式 3 — RAG 知识库：**
将技能文档分割后索引到向量数据库，供检索增强生成使用。
```python
from langchain.text_splitter import MarkdownHeaderTextSplitter
splitter = MarkdownHeaderTextSplitter(
headers_to_split_on=[("##", "section"), ("###", "subsection")]
)
```
资料来源：[README.md:50-100](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## 维护与更新
### 文档新鲜度
技能文档需要定期验证以保持准确性：
| 验证项目 | 频率 | 负责人 |
|---------|------|-------|
| API 端点可用性 | 每季度 | 技能维护者 |
| 速率限制更新 | 发现变更时 | 提交者 |
| 认证流程变化 | 发现变更时 | 提交者 |
| 新功能添加 | 持续 | 社区贡献者 |
### 验证标记
文档头部应包含 `Last validated:` 日期：
```markdown
---
Last validated: 2025-11-15
---
```
### 问题报告
发现文档错误时：
1. 检查官方 API 文档确认正确行为
2. 创建 Issue 描述问题
3. 提交 PR 修复并更新验证日期
4. 关联相关 Issue
资料来源：[skills/ROADMAP.md:50-80](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
---
## 路线图与未来方向
### 当前阶段状态
| 阶段 | 主题 | 状态 |
|------|------|------|
| Phase 1 | 基础（认证 + 核心 CRUD） | ✅ 完成 |
| Phase 2 | 高频工作流（6-12 条 Recipes） | ✅ 完成 |
| Phase 3 | 事件驱动与实时 | ✅ 完成 |
| Phase 4 | 批量与高级操作 | ⚠️ 部分完成 |
| Phase 5 | 跨工具编排 | ❌ 未开始 |
### 下一阶段重点
**优先级 1 — 新鲜度和准确性流水线**
- 建立 API 变更监控系统
- 自动验证文档准确性
- 社区驱动的更新机制
**优先级 2 — 跨工具编排扩展**
- 更多 Playbooks 示例
- 标准化编排模式库
- 错误恢复和补偿策略
资料来源：[skills/ROADMAP.md:80-120](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
---
## 附录
### 快速参考：技能文档元数据
| 属性 | 要求 |
|------|------|
| 文件命名 | `skill.md` |
| 目录位置 | `skills//` |
| 最小大小 | 5 KB |
| 章节数量 | 11 个必填 |
| 语言 | Markdown |
| 引用格式 | 指向官方文档的链接 |
---
## 技能目录总览
### 相关页面
相关主题：[技能文档结构](#page-skill-anatomy), [跨工具工作流剧本](#page-playbooks)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)
- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)
- [skills/salesforce/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/salesforce/skill.md)
- [skills/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)
- [skills/zendesk/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/zendesk/skill.md)
- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)
- [skills/stripe/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/stripe/skill.md)
- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)
- [skills/jira/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)
- [skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)
- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)
- [skills/servicenow/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/servicenow/skill.md)
- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)
# 技能目录总览
## 项目概述
**Clawskills** 是一个开源的集成技能库项目，旨在为 AI 工具（特别是 Claude Code 和 Claude Desktop）提供标准化的第三方服务集成文档。该项目将常见的 SaaS 平台和开发工具的 API 使用方法、认证流程、速率限制和最佳实践整理成结构化的技能文档，使 AI 助手能够准确、高效地帮助用户完成与这些工具的集成工作。资料来源：[README.md:1]()
该技能库目前涵盖 **14 个主流工具**，包括项目管理、设计协作、CRM、客服、财务等多个领域的解决方案。每个技能文档都遵循统一的 11 部分结构，确保一致性和可维护性。资料来源：[README.md:15]()
## 架构设计
### 技能库整体架构
```mermaid
graph TD
A[clawskills 仓库] --> B[技能文档层 skills/]
A --> C[剧本目录 playbooks/]
A --> D[MCP 服务器 mcp-server/]
B --> E[14 个工具技能文档]
B --> F[INDEX.md 索引]
B --> G[ROADMAP.md 路线图]
C --> H[跨工具工作流剧本]
D --> I[list_skills 工具]
D --> J[get_skill 工具]
D --> K[search_skills 工具]
```
### MCP 服务器集成架构
MCP 服务器作为 AI 工具与技能库之间的桥梁，提供三个核心工具：资料来源：[README.md:80-85]()
```mermaid
sequenceDiagram
participant AI as AI 助手
participant MCP as MCP 服务器
participant FS as 文件系统
AI->>MCP: list_skills
MCP->>FS: 读取 skills/ 目录
FS-->>MCP: 技能列表
MCP-->>AI: 返回技能索引
AI->>MCP: get_skill("jira", "auth")
MCP->>FS: 读取 skills/jira/skill.md
FS-->>MCP: 完整文档内容
MCP-->>AI: 返回认证章节
AI->>MCP: search_skills("webhook")
MCP->>FS: 全文搜索所有技能
FS-->>MCP: 匹配结果
MCP-->>AI: 返回搜索结果
```
## 技能文档结构
### 标准章节模板
每个技能文档必须包含以下 11 个标准章节，这是项目质量要求的一部分：资料来源：[README.md:22]()
| 章节序号 | 章节名称 | 说明 |
|---------|---------|------|
| 1 | 基本信息 | 工具简介、API 基础 URL、版本 |
| 2 | 认证与权限 | 认证方式、OAuth 流程、权限范围 |
| 3 | 核心 API 端点 | 主要 REST 端点或 GraphQL 操作 |
| 4 | 常见工作流 | 典型使用场景的代码示例 |
| 5 | 速率限制与重试 | API 限制、错误处理策略 |
| 6 | 错误代码参考 | 常见错误及解决方案 |
| 7 | Webhook 配置 | 事件订阅、签名验证 |
| 8 | 批量操作 | 大量数据处理模式 |
| 9 | 数据模型 | 关键对象结构说明 |
| 10 | 安全与合规 | 最佳实践、隐私考虑 |
| 11 | 参考资料 | 官方文档链接 |
### 文档验证机制
项目通过自动化测试确保文档质量：资料来源：[mcp-server/src/index.test.ts:18-40]()
```mermaid
graph LR
A[提交 PR] --> B[CI 运行 npm test]
B --> C{加载所有技能}
C --> D{检查摘要行}
C --> E{检查必需章节}
C --> F{检查文件大小 ≥5KB}
D --> G{全部通过?}
E --> G
F --> G
G -->|是| H[PR 允许合并]
G -->|否| I[CI 失败报告]
```
测试套件验证以下条件：资料来源：[mcp-server/src/index.test.ts:18-40]()
- 所有 14 个已知技能都已加载
- 每个技能文件包含非空摘要行
- 每个技能文件包含全部必需章节
- 每个技能文件大小至少 5KB
## 支持的工具清单
### 工具分类总览
| 类别 | 工具列表 | 说明 |
|------|---------|------|
| 项目管理 | Jira, Linear, Asana, Monday.com | 任务跟踪、敏捷管理 |
| 设计协作 | Figma | 设计文件、组件库 |
| CRM | Salesforce, HubSpot, Dynamics 365 | 销售和客户管理 |
| 客服支持 | Zendesk, ServiceNow | 工单和服务管理 |
| 通信协作 | Slack | 团队消息和自动化 |
| 财务管理 | Stripe | 支付和订阅 |
| 知识管理 | Notion | 文档和数据库 |
| 开发协作 | GitHub | 代码仓库和 CI/CD |
### 工具认证方式对比
| 工具 | 主要认证方式 | Token 格式 | OAuth 支持 |
|------|-------------|-----------|-----------|
| Jira | Basic Auth / API Token | — | ✅ |
| Linear | API Key | — | ✅ |
| Asana | Personal Access Token | `1/xxxxxxxx` | ✅ |
| Monday.com | API Key | — | ✅ |
| Figma | Personal Access Token | `figd_xxx` | ✅ |
| Salesforce | OAuth 2.0 | — | ✅ |
| HubSpot | Private App Token | `pat-xxx` | ✅ |
| Dynamics 365 | OAuth 2.0 | — | ✅ |
| Zendesk | API Token | `xxx` | ✅ |
| ServiceNow | Basic Auth | — | ✅ |
| Slack | OAuth 2.0 / Bot Token | `xoxb-xxx` | ✅ |
| Stripe | Secret Key | `sk_xxx` | ❌ |
| Notion | Internal Integration | `secret_xxx` | ✅ |
| GitHub | Personal Access Token | `ghp_xxx` | ✅ |
### 速率限制对比
| 工具 | 认证类型 | 请求频率 | 特殊限制 |
|------|---------|---------|---------|
| Figma | PAT | 1,000 req/hr | 按计划分级 |
| Linear | API Key | 5,000 req/hr | 复杂度点限制 |
| Jira | API Token | 取决于计划 | 付费版更高 |
| Stripe | Secret Key | 无硬限制 | 建议请求隔离 |
| Notion | Integration | 3 req/s | 分段限制 |
| HubSpot | Private App | 100-500 req/10s | 按端点分级 |
## 跨工具工作流剧本
### 剧本目录
项目在 `playbooks/` 目录下维护跨工具集成的工作流剧本。资料来源：[README.md:10]()
```mermaid
graph TD
P[剧本目录] --> S1[Slack-Jira 事故管理]
P --> S2[跨工具同步流程]
P --> S3[自动化工作流]
S1 --> T1[Slack 消息监听]
S1 --> T2[Jira 问题创建]
S1 --> T3[状态同步]
T1 --> T4[事件类型识别]
T2 --> T5[字段映射]
T3 --> T6[回执通知]
```
### Slack-Jira 事故剧本字段映射
以下是一个跨工具集成的字段映射示例：资料来源：[playbooks/slack-jira-incident.md:1-20]()
| Slack 事件字段 | Jira 目标字段 | 说明 |
|---------------|---------------|------|
| `event.channel` + `event.ts` | Correlation Key | 用于去重的关联标识 |
| `event.text` (首句) | `summary` | 问题摘要，截断至 120 字符 |
| `permalink` | `description` | Slack 消息永久链接 |
| `event.thread_ts` | 评论/附件 | 线程上下文 |
| `slack-incident` 标签 | Label | 事故类型标记 |
| `correlation_key` | 自定义字段 | 跨系统关联键 |
## 开发贡献流程
### 添加新技能的步骤
项目采用标准化的分支和 PR 流程来管理技能文档的更新：资料来源：[README.md:18-30]()
```mermaid
graph LR
A[创建分支 git checkout -b skill/<toolname>] --> B[遵循模板结构]
B --> C[验证端点和限制]
C --> D[添加 Last validated 日期]
D --> E[更新 INDEX.md 和 README.md]
E --> F[PR 并等待 CI 通过]
F --> G[合并到 main]
G --> H[触发 Release 工作流]
```
### 贡献质量要求
- 所有 11 个标准章节必须完整填写
- 端点、速率限制和认证流程必须对照官方文档验证
- `Last validated` 日期必须更新
- 引用官方来源，禁止未经验证的声明
- 至少包含 5 个常见工作流示例
## 发布与维护机制
### 自动化发布流程
项目使用 GitHub Actions 实现完全自动化的发布流程：资料来源：[skills/ROADMAP.md:20-25]()
```mermaid
graph LR
A[合并到 main 分支] --> B[GitHub Actions]
B --> C[运行 Release 工作流]
C --> D[选择版本类型]
D --> E{patch/minor/major}
E --> F[版本号递增]
F --> G[创建 Git Tag]
F --> H[npm publish]
G --> I[GitHub Release]
```
### 版本管理策略
| 版本类型 | 适用场景 | 示例 |
|---------|---------|------|
| patch | 文档修正、链接更新 | 1.0.0 → 1.0.1 |
| minor | 新增端点、新增章节 | 1.0.1 → 1.1.0 |
| major | 新增工具、架构变更 | 1.1.0 → 2.0.0 |
## 未来发展路线
### 已完成阶段
| 阶段 | 主题 | 状态 |
|------|------|------|
| Phase 1 | 基础（认证 + 核心 CRUD） | ✅ 全部 14 个工具 |
| Phase 2 | 高频工作流（6-12 个示例/工具） | ✅ 全部 14 个工具 |
| Phase 3 | 事件驱动与实时（Webhook） | ✅ 全部 14 个工具 |
| Phase 4 | 批量与高级操作 | ⚠️ 部分完成 |
| Phase 5 | 跨工具编排（2+ 工具联动） | ❌ 未开始 |
资料来源：[skills/ROADMAP.md:30-40]()
### 优先级计划
**优先级 1 — 新鲜度和准确性流水线**
随着 14 个核心技能库完成，下一个护城河是确保文档随供应商 API 变化保持准确。资料来源：[skills/ROADMAP.md:45-50]()
计划包括：
- 自动化 API 变更检测
- 社区贡献的审查流程
- 定期重新验证机制
- 版本化技能文档
## 在 Claude Code 中使用
### 项目指令文件示例
在 `.claude/CLAUDE.md` 中配置项目级指令，使 AI 始终使用这些技能文档：资料来源：[README.md:60-75]()
```markdown
# 集成技能
当编写与以下工具集成的代码时，始终先阅读对应技能文档：
- Monday.com → @skills/monday/skill.md
- Salesforce → @skills/salesforce/skill.md
- Jira → @skills/jira/skill.md
- Dynamics 365 → @skills/dynamics365/skill.md
- HubSpot → @skills/hubspot/skill.md
- ServiceNow → @skills/servicenow/skill.md
- Zendesk → @skills/zendesk/skill.md
- Asana → @skills/asana/skill.md
- GitHub → @skills/github/skill.md
- Figma → @skills/figma/skill.md
- Slack → @skills/slack/skill.md
- Stripe → @skills/stripe/skill.md
- Notion → @skills/notion/skill.md
- Linear → @skills/linear/skill.md
遵循文档中指定的认证模式、速率限制处理和错误代码。
```
## 总结
技能目录总览展示了 Clawskills 项目的完整架构和价值主张：
- **14 个主流工具**的标准化集成文档
- **统一的 11 章节结构**确保一致性和可维护性
- **MCP 服务器集成**使 AI 工具能够实时访问技能库
- **自动化测试和发布**保证文档质量
- **跨工具剧本**支持复杂业务场景
该项目将持续更新以反映供应商 API 的变化，并逐步扩展跨工具编排能力。
---
## 跨工具工作流剧本
### 相关页面
相关主题：[技能目录总览](#page-skill-catalog), [贡献指南](#page-contributing)
相关源码文件
以下源码文件用于生成本页说明：
- [playbooks/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/INDEX.md)
- [playbooks/zendesk-jira-bug-escalation.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/zendesk-jira-bug-escalation.md)
- [playbooks/hubspot-asana-onboarding.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/hubspot-asana-onboarding.md)
- [playbooks/salesforce-hubspot-lead-sync.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/salesforce-hubspot-lead-sync.md)
- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)
# 跨工具工作流剧本
## 概述
跨工具工作流剧本（Playbooks）是 Clawskills 项目中用于定义和编排多系统集成的核心文档。这些剧本描述了如何将两个或多个工具（如 Slack、Jira、Zendesk、HubSpot、Salesforce、Asana 等）的 API 和事件机制组合起来，实现端到端的业务流程自动化。
剧本的核心价值在于提供经过验证的集成模式，涵盖身份验证、数据映射、事件处理、错误恢复等关键环节，帮助开发者快速实现跨系统的工作流编排。
资料来源：[playbooks/INDEX.md:1-20]()
---
## 剧本架构
### 剧本组成要素
每个剧本通常包含以下核心组件：
| 组件 | 说明 |
|------|------|
| 触发器（Trigger） | 启动工作流的事件来源，如消息接收、工单创建、状态变更 |
| 源系统 | 工作流的起始工具，产生原始事件 |
| 目标系统 | 工作流的终点，接收处理后的数据 |
| 数据映射 | 字段对应关系和格式转换规则 |
| 事件处理 | 对触发事件的响应逻辑 |
| 错误处理 | 异常情况的处理策略 |
资料来源：[playbooks/slack-jira-incident.md:10-15]()
### 剧本类型分类
根据业务场景，剧本可分为以下类型：
| 类型 | 描述 | 示例 |
|------|------|------|
| 事件驱动型 | 响应实时事件自动触发 | Slack 消息 → Jira 工单 |
| 同步型 | 双向数据保持一致 | Salesforce → HubSpot 线索同步 |
| 编排型 | 多步骤复杂业务流程 | Zendesk 工单 → Jira Bug → Slack 通知 |
资料来源：[playbooks/INDEX.md:1-30]()
---
## 剧本工作流程
### 标准执行流程
```mermaid
graph TD
A[触发事件] --> B{事件验证}
B -->|签名无效| C[拒绝请求]
B -->|验证通过| D[解析事件数据]
D --> E[数据映射与转换]
E --> F[调用目标系统 API]
F --> G{调用成功?}
G -->|是| H[记录响应]
G -->|否| I[重试/错误处理]
H --> J[发送确认通知]
I --> K{重试次数耗尽?}
K -->|否| F
K -->|是| L[告警并记录失败]
```
### 事件处理模式
```mermaid
graph LR
A[源系统事件] --> B[Webhook 接收端点]
B --> C{事件类型匹配}
C -->|issue_created| D[创建目标记录]
C -->|issue_updated| E[更新目标记录]
C -->|comment_created| F[添加评论]
D --> G[响应 200 OK]
E --> G
F --> G
```
资料来源：[playbooks/slack-jira-incident.md:30-50]()
---
## 字段映射规范
### Slack → Jira 字段映射
| Slack 属性 | Jira 字段 | 转换规则 |
|------------|-----------|----------|
| `event.item.channel` + `event.item.ts` | correlation key | 格式：`slack:{team_id}:{channel_id}:{ts}` |
| 消息文本首句 | `summary` | 截断至 120 字符 |
| 消息全文 + 线程回复 | `description` | 包含 Slack permalink 链接 |
| 触发器来源 | 标签 | 添加 `slack-incident` 标签 |
资料来源：[playbooks/slack-jira-incident.md:50-60]()
### Salesforce → HubSpot 字段映射
| Salesforce 字段 | HubSpot 字段 | 数据类型 |
|-----------------|--------------|----------|
| `Lead.Email` | `email` | string |
| `Lead.FirstName` | `firstname` | string |
| `Lead.LastName` | `lastname` | string |
| `Lead.Company` | `company` | string |
| `Lead.Phone` | `phone` | string |
| `Lead.LeadSource` | `hs_lead_status` | enumeration |
资料来源：[playbooks/salesforce-hubspot-lead-sync.md:15-25]()
---
## 认证与安全
### 跨系统认证模式
| 源系统 | 认证方式 | 目标系统 | 认证方式 |
|--------|----------|----------|----------|
| Slack | Bot Token (`xoxb-...`) | Jira | API Token + Basic Auth |
| Zendesk | API Token | Jira | API Token + Basic Auth |
| HubSpot | OAuth 2.0 / Private App | Asana | Personal Access Token |
| Salesforce | OAuth 2.0 | HubSpot | Private App Token |
资料来源：[playbooks/zendesk-jira-bug-escalation.md:20-30]()
### Webhook 安全验证
所有入站 Webhook 必须进行签名验证：
```python
# Slack 签名验证示例
def verify_slack_signature(body, timestamp, signature, signing_secret):
prefix = f"v0:{timestamp}:"
expected = "v0=" + hmac.new(
signing_secret.encode(),
prefix.encode() + body,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
```
```python
# Linear 签名验证示例
def verify_linear_signature(body, signature, secret):
expected = hmac.new(
secret.encode(),
body,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
```
资料来源：[playbooks/slack-jira-incident.md:70-85]()
---
## 错误处理策略
### 错误响应码处理
| Slack 错误码 | 处理策略 | 说明 |
|--------------|----------|------|
| `channel_not_found` | 重新安装应用 | workspace 权限变更导致 |
| `ratelimited` | 尊重 `Retry-After` 头 | 指数退避重试 |
| `already_in_channel` | 忽略 | 视为成功 |
| `cant_update_message` | 跳过更新 | 仅原发布 bot 可更新 |
| `msg_too_long` | 拆分消息 | 单条限制 40,000 字符 |
资料来源：[skills/slack/skill.md:100-120]()
### 重试机制
```mermaid
graph TD
A[API 调用] --> B{响应状态}
B -->|2xx| C[成功 - 继续]
B -->|429| D[读取 Retry-After]
B -->|5xx| E[重试]
D --> F[等待后重试]
E --> F
F --> A
B -->|4xx 非 429| G[记录错误]
G --> H[不重试 - 需修复代码]
```
资料来源：[playbooks/salesforce-hubspot-lead-sync.md:40-50]()
---
## 剧本示例：Slack-Jira 事件响应
### 业务流程
```mermaid
sequenceDiagram
participant S as Slack
participant A as 事件处理器
participant J as Jira
participant H as HubSpot
S->>A: 消息事件 (reaction_added)
A->>S: 获取 permalink
A->>J: 搜索相关工单
alt 找到现有工单
A->>J: 更新现有工单
else 未找到工单
A->>J: 创建新 Jira Issue
A->>H: 同步客户信息
end
A->>S: 回复线程 (工单链接)
```
### 实现要点
1. **关联键生成**：使用 `slack:{team_id}:{channel_id}:{ts}` 格式确保全局唯一性
2. **幂等性处理**：创建前先搜索，避免重复工单
3. **上下文保留**：在 description 中保留 Slack permalink 和消息原文
4. **异步处理**：返回 200 后在后台执行重操作
资料来源：[playbooks/slack-jira-incident.md:1-30]()
---
## 剧本示例：Zendesk-Jira Bug 升级
### 触发条件
| Zendesk 事件 | 条件 | Jira 操作 |
|--------------|------|----------|
| Ticket 创建 | `tags` 包含 `bug` | 创建 Bug 类型 Issue |
| Ticket 更新 | `priority` 变为 `urgent` | 升级现有 Bug |
| Ticket 更新 | `status` 变为 `solved` | 同步关闭 Jira Issue |
### 数据映射
| Zendesk 字段 | Jira 字段 | 说明 |
|--------------|-----------|------|
| `ticket.id` | `description` 引用 | 保留 Zendesk 链接 |
| `ticket.subject` | `summary` | Bug 标题 |
| `ticket.description` | `description` | 详细描述 |
| `ticket.priority` | `priority` | Urgent → Highest |
| `ticket.requester.email` | `reporter` | 报告人信息 |
资料来源：[playbooks/zendesk-jira-bug-escalation.md:10-25]()
---
## 剧本示例：HubSpot-Asana 客户入职
### 工作流阶段
```mermaid
graph LR
A[HubSpot Deal 成交] --> B[创建 Asana 项目]
B --> C[添加项目任务模板]
C --> D[分配负责人]
D --> E[发送客户通知]
E --> F[跟踪里程碑完成]
F --> G[同步回 HubSpot]
```
### 配置参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `project_template_gid` | string | Asana 项目模板 ID |
| `team_gid` | string | 负责团队 ID |
| `due_date_offset` | number | 相对成交日期的天数 |
| `notification_template` | string | 客户通知内容模板 |
资料来源：[playbooks/hubspot-asana-onboarding.md:15-40]()
---
## 剧本示例：Salesforce-HubSpot 线索同步
### 同步策略
```mermaid
graph TD
A[Salesforce Lead 创建/更新] --> B{冲突检测}
B -->|HubSpot 无对应记录| C[创建 HubSpot Contact]
B -->|HubSpot 存在记录| D[比较 updatedAt 时间戳]
D -->|SF 更新更新| E[更新 HubSpot]
D -->|HubSpot 更新更新| F[跳过 - 保留 HubSpot 数据]
C --> G[记录同步日志]
E --> G
```
### 同步字段配置
| Salesforce | HubSpot | 同步方向 | 冲突处理 |
|------------|---------|----------|----------|
| `Email` | `email` | 必填 | 作为唯一标识符 |
| `FirstName` | `firstname` | SF → HS | 以最新更新为准 |
| `LastName` | `lastname` | SF → HS | 以最新更新为准 |
| `Company` | `company` | SF → HS | 以最新更新为准 |
| `Phone` | `phone` | 双向 | 以最新更新为准 |
资料来源：[playbooks/salesforce-hubspot-lead-sync.md:10-35]()
---
## 最佳实践
### 设计原则
1. **幂等性优先**：所有操作必须可安全重试，避免重复创建资源
2. **快速响应**：Webhook 端点应立即返回 200，在后台处理复杂逻辑
3. **签名验证**：所有入站事件必须验证签名，拒绝未授权请求
4. **数据映射文档化**：明确记录每个字段的转换规则和默认值
5. **错误可观测性**：记录足够的日志信息便于调试，包括错误码和响应时间
### 性能优化
| 优化点 | 策略 |
|--------|------|
| API 调用次数 | 使用批量 API，减少循环调用 |
| Webhook 处理 | 消息队列异步处理，避免阻塞 |
| 缓存策略 | 缓存认证 token 和频繁查询的数据 |
| 复杂度控制 | Linear API 请求优先选择必要的字段 |
资料来源：[skills/linear/skill.md:80-100]()
---
## 相关资源
### 工具技能文档
- [Slack 技能文档](../skills/slack/skill.md)
- [Jira 技能文档](../skills/jira/skill.md)
- [HubSpot 技能文档](../skills/hubspot/skill.md)
- [Salesforce 技能文档](../skills/salesforce/skill.md)
- [Zendesk 技能文档](../skills/zendesk/skill.md)
- [Linear 技能文档](../skills/linear/skill.md)
- [Asana 技能文档](../skills/asana/skill.md)
### 扩展阅读
- [ROADMAP.md](../skills/ROADMAP.md) - 跨工具编排模式规划
- [CLAUDE.md](https://github.com/Shanksg/clawskills/blob/main/.claude/CLAUDE.md) - Claude Code 集成配置
---
## 部署指南
### 相关页面
相关主题：[持续集成与发布](#page-cicd), [MCP 服务器架构](#page-mcp-server-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)
- [package.json](https://github.com/Shanksg/clawskills/blob/main/package.json)
- [.github/workflows/ci.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/ci.yml) (隐含引用)
- [.github/workflows/release.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/release.yml) (隐含引用)
- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md) (隐含引用)
# 部署指南
## 概述
clawskills 是一个技能文档库（Skills Documentation Library），为 AI 工具提供集成指南。该项目包含 14 种工具的完整集成文档，并通过 MCP（Model Context Protocol）服务器提供访问接口。
核心部署组件为 `clawskills-mcp` 服务器，它提供三个主要工具供 AI 助手调用：
| 工具名称 | 功能描述 |
|---------|---------|
| `list_skills` | 列出所有可用的技能文档 |
| `get_skill` | 获取完整的技能文档或指定章节 |
| `search_skills` | 全文本搜索所有技能文档 |
资料来源：[README.md:1-10]()
## 架构概览
```graph TD
A[用户/AI 工具] -->|MCP 协议| B[clawskills-mcp 服务器]
B -->|HTTP| C[GitHub API]
C -->|返回| B
B -->|技能文档| A
D[GitHub Actions] -->|自动化发布| E[npm 仓库]
E -->|安装| B
```
## 本地部署方式
### 临时运行（npx）
无需安装，可直接通过 npx 运行 MCP 服务器：
```bash
npx -y clawskills-mcp
```
此方式适用于一次性测试或临时集成场景。服务器启动后，AI 工具（如 Claude Desktop）可通过 MCP 协议连接并调用技能文档。
资料来源：[README.md:71-75]()
### 全局安装
对于长期使用，建议全局安装：
```bash
npm install -g clawskills-mcp
```
全局安装后，MCP 服务器在系统中持久可用，不受当前工作目录限制。
资料来源：[README.md:76-78]()
## Claude Desktop / Claude Code 配置
### 配置步骤
将以下配置添加到 Claude Desktop 或 Claude Code 的配置文件中：
```json
{
"mcpServers": {
"clawskills": {
"command": "npx",
"args": ["-y", "clawskills-mcp"]
}
}
}
```
### 配置位置
| 平台 | 配置文件路径 |
|------|-------------|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Code | `.claude/settings.json` 或项目级配置 |
### 验证配置
配置完成后，重启 Claude Desktop/Claude Code，然后尝试调用技能工具：
```
list_skills
```
预期返回所有 14 个工具的技能文档列表。
资料来源：[README.md:79-90]()
## MCP 服务器工具详解
### list_skills
返回所有可用的技能文档列表，无需参数。
```json
// 响应示例
{
"skills": [
"monday",
"salesforce",
"jira",
"dynamics365",
"hubspot",
"servicenow",
"zendesk",
"asana",
"github",
"figma",
"slack",
"stripe",
"notion",
"linear"
]
}
```
### get_skill
获取指定技能的完整文档或特定章节。
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `skill_name` | string | 是 | 技能名称（如 `jira`、`linear`） |
| `section` | string | 否 | 指定章节：`auth`、`rate-limits`、`recipes`、`errors` |
```json
// 获取 Jira 技能文档的认证部分
{
"skill_name": "jira",
"section": "auth"
}
```
### search_skills
全文本搜索所有技能文档。
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `query` | string | 是 | 搜索关键词 |
| `limit` | number | 否 | 返回结果数量限制（默认 10） |
## CI/CD 自动化部署
### 持续集成
每次推送和 PR 合并时触发 CI 流程：
```mermaid
graph LR
A[推送/PR] --> B{GitHub Actions CI}
B --> C[npm test]
C --> D{测试通过?}
D -->|是| E[允许合并]
D -->|否| F[阻止合并]
```
测试套件包括：
- Vitest 单元测试
- 真实技能文档验证
- 必需章节检查
- 文档大小验证（≥5 KB）
资料来源：[skills/ROADMAP.md:1-15]()
### 发布自动化
项目使用 `release.yml` 工作流自动化版本发布：
1. 合并到 `main` 分支
2. 进入 GitHub Actions → **Release**
3. 运行工作流，选择版本类型：
- `patch` — 补丁版本（bug 修复）
- `minor` — 次版本（新功能）
- `major` — 主版本（破坏性变更）
发布流程自动完成：
- 版本号递增
- Git 标签创建
- npm 包发布
资料来源：[README.md:35-40]()
### OIDC 认证
发布流程使用 OpenID Connect (OIDC) 与 npm 仓库建立安全连接，无需存储 npm token。
## 部署验证清单
部署完成后，按以下清单验证：
- [ ] Claude Desktop/Code 已重启
- `list_skills` 调用成功，返回 14 个工具
- `get_skill` 能获取完整文档
- `search_skills` 搜索结果准确
- MCP 连接状态为"已连接"
## 项目结构参考
```
clawskills/
├── README.md # 主说明文档
├── package.json # npm 包配置
├── skills/ # 技能文档目录
│ ├── INDEX.md # 所有技能索引
│ ├── jira/
│ ├── linear/
│ ├── figma/
│ └── ... # 其他 11 个工具
├── playbooks/ # 跨工具工作流
│ └── slack-jira-incident.md
└── .github/
└── workflows/
├── ci.yml # 持续集成
└── release.yml # 发布自动化
```
## 常见部署问题
| 问题 | 解决方案 |
|------|---------|
| MCP 服务器连接失败 | 检查 JSON 配置格式，确保 `command` 为 `npx` |
| 工具调用超时 | 确认网络连接，可使用全局安装替代 npx |
| 版本过旧 | 运行 `npm update -g clawskills-mcp` 更新 |
| 权限错误 | 检查 Claude Desktop 配置文件的读写权限 |
## 相关资源
- 项目主页：https://github.com/Shanksg/clawskills
- MCP 服务器 npm 包：https://www.npmjs.com/package/clawskills-mcp
- 技能索引：[skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)
- 开发路线图：[skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
---
## 持续集成与发布
### 相关页面
相关主题：[部署指南](#page-deployment)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)
- [mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)
- [.github/workflows/ci.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/ci.yml)
- [.github/workflows/release.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/release.yml)
- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)
- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
# 持续集成与发布
## 概述
ClawSkills 项目采用自动化持续集成（CI）和持续发布（CD）流程，确保代码质量和发布效率。整个系统基于 GitHub Actions 实现自动化构建、测试和发布流程，涵盖单元测试、技能文档验证、版本管理和 npm 包发布等关键环节。
项目包含两套独立的自动化工作流：
- **CI 工作流** (`ci.yml`)：在每次 push 和 PR 时自动执行构建和测试
- **发布工作流** (`release.yml`)：通过手动触发实现语义化版本管理和 npm 发布
## 整体架构
```mermaid
graph TD
A[开发者提交代码] --> B{触发方式}
B -->|push / PR| C[ci.yml 工作流]
B -->|workflow_dispatch| D[release.yml 工作流]
C --> E[安装依赖]
E --> F[npm test]
F --> G{测试结果}
G -->|通过| H[CI 成功]
G -->|失败| I[CI 失败 / 通知]
D --> J[选择版本类型]
J --> K[patch / minor / major]
K --> L[更新版本号]
L --> M[创建 Git Tag]
M --> N[推送至 npm]
N --> O[发布完成]
```
## CI 工作流详解
### 触发条件
CI 工作流在以下场景自动触发：
| 触发事件 | 说明 |
|---------|------|
| `push` | 代码推送至 main 分支或 PR 分支 |
| `pull_request` | 创建或更新 Pull Request |
资料来源：[.github/workflows/ci.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/ci.yml)
### 测试套件
项目使用 Vitest 作为测试框架，测试套件位于 `mcp-server/src/index.test.ts`。测试验证以下关键要求：
```typescript
describe("real skills", () => {
it("loads all expected skills", () => {
// 验证所有14个skill都被正确加载
});
it("every skill has a non-empty summary line", () => {
// 验证每个skill都有摘要行
});
it("every skill contains the required sections", () => {
// 验证每个skill包含所有11个必需部分
});
it("every skill file is at least 5KB", () => {
// 验证skill文件大小合理
});
});
```
资料来源：[mcp-server/src/index.test.ts:19-44](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)
### 必需部分验证
每个 skill 文档必须包含以下 11 个部分：
1. 认证与权限
2. 核心端点
3. 常见工作流（Recipes）
4. 过滤与查询模式
5. 速率限制与重试策略
6. 错误处理
7. Webhook 配置
8. 数据模型
9. 安全与隐私
10. 配额与限制
11. 相关资源
### npm 测试命令
```json
{
"scripts": {
"test": "vitest run"
}
}
```
资料来源：[mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)
## 发布工作流详解
### 触发方式
发布工作流通过 GitHub Actions 手动触发（workflow_dispatch），开发者可选择发布类型。
```yaml
workflow_dispatch:
inputs:
release_type:
description: '发布类型'
required: true
type: choice
options:
- patch
- minor
- major
```
资料来源：[.github/workflows/release.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/release.yml)
### 发布流程步骤
```mermaid
graph LR
A[选择发布类型] --> B[更新 package.json 版本号]
B --> C[创建 Git Tag]
C --> D[提交更改]
D --> E[推送到 GitHub]
E --> F[发布到 npm registry]
```
### 版本管理策略
项目采用语义化版本（SemVer）规范：
| 版本类型 | 说明 | 示例 |
|---------|------|------|
| `patch` | 补丁版本，修复问题 | 1.0.0 → 1.0.1 |
| `minor` | 次版本，新增功能（向后兼容） | 1.0.0 → 1.1.0 |
| `major` | 主版本，破坏性变更 | 1.0.0 → 2.0.0 |
### OIDC 发布机制
发布工作流使用 OpenID Connect (OIDC) 进行身份验证，确保安全的 npm 发布流程：
```yaml
permissions:
id-token: write
contents: read
```
此配置允许工作流从 npm 获取短期令牌，无需长期存储凭据。
## MCP Server 包管理
### 包结构
```json
{
"name": "clawskills-mcp",
"version": "0.2.0",
"description": "MCP server exposing ClawSkills API integration docs",
"bin": {
"clawskills-mcp": "./dist/index.js"
},
"engines": {
"node": ">=18"
}
}
```
资料来源：[mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)
### 安装方式
| 安装方式 | 命令 | 适用场景 |
|---------|------|---------|
| 临时运行（npx） | `npx -y clawskills-mcp` | Claude Desktop / Claude Code |
| 全局安装 | `npm install -g clawskills-mcp` | 持久化使用 |
## 技能文档同步机制
### 同步脚本
项目提供两个辅助脚本用于管理和同步技能文档：
| 脚本 | 功能 |
|------|------|
| `check-skills.mjs` | 验证 skill 文档的完整性和格式 |
| `sync-skills.mjs` | 同步更新 skill 文档 |
资料来源：[mcp-server/scripts/check-skills.mjs](https://github.com/Shanksg/clawskills/blob/main/mcp-server/scripts/check-skills.mjs), [mcp-server/scripts/sync-skills.mjs](https://github.com/Shanksg/clawskills/blob/main/mcp-server/scripts/sync-skills.mjs)
### 可用 Skills 列表
系统支持以下 14 个工具的集成技能文档：
- Asana
- Dynamics 365
- Figma
- GitHub
- HubSpot
- Jira
- Linear
- Monday.com
- Notion
- Salesforce
- ServiceNow
- Slack
- Stripe
- Zendesk
资料来源：[mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)
## MCP 工具接口
### 工具列表
| 工具名称 | 功能描述 |
|---------|---------|
| `list_skills` | 列出所有可用的 skill 文档 |
| `get_skill` | 获取完整的 skill 文档或指定部分 |
| `search_skills` | 在所有 skill 文档中进行全文搜索 |
| `list_playbooks` | 列出所有可用的剧本 |
| `get_playbook` | 获取指定剧本内容 |
### 使用配置
在 Claude Desktop 或 Claude Code 中配置：
```json
{
"mcpServers": {
"clawskills": {
"command": "npx",
"args": ["-y", "clawskills-mcp"]
}
}
}
```
## 开发贡献流程
### 分支命名规范
```bash
git checkout -b skill/<工具名称>
```
### 提交流程
1. 创建功能分支
2. 按照模板结构编写或更新 skill 文档（必须包含全部 11 个部分）
3. 验证所有端点、速率限制和认证流程
4. 在文档头部添加 `Last validated:` 日期
5. 更新 `skills/INDEX.md` 和 `README.md`
6. 在 `## Sources` 部分添加官方文档链接
7. 提交 Pull Request
### PR 验证
提交 PR 后，CI 流水线自动执行 `npm test`，验证内容：
- skill 文件可正常加载
- 包含所有必需章节
- 文件大小不小于 5KB
资料来源：[mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)
## 最佳实践
### 技能文档编写规范
| 要求 | 说明 |
|------|------|
| 章节完整性 | 必须包含全部 11 个必需部分 |
| 最小长度 | 文件大小至少 5KB |
| API 验证 | 所有端点需对照官方文档验证 |
| 认证模式 | 严格按照文档中的认证模式实现 |
| 速率限制 | 准确记录各 API 的速率限制 |
| 错误代码 | 列出所有相关的错误代码和处理方式 |
### 发布检查清单
- [ ] 所有测试通过
- [ ] 版本号正确更新
- [ ] Git Tag 已创建
- [ ] CHANGELOG 已更新
- [ ] npm 发布成功
## 相关资源
- GitHub Actions 文档：https://docs.github.com/actions
- Vitest 测试框架：https://vitest.dev
- SemVer 规范：https://semver.org
---
## 贡献指南
### 相关页面
相关主题：[技能文档结构](#page-skill-anatomy)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)
- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)
# 贡献指南
本文档介绍如何为 clawskills 项目贡献代码和技能文档。clawskills 是一个集成技能库，汇集了多种工具（如 Salesforce、Jira、Linear、Slack 等）的 API 集成文档和最佳实践。贡献者可以通过标准的 Git 工作流提交新的技能文档或更新现有内容。
---
## 贡献流程概述
贡献 clawskills 的标准流程包含以下步骤：
```mermaid
graph TD
A[创建功能分支] --> B[遵循 skill.md 模板编写文档]
A1[git checkout -b skill/<toolname>] --> A
B --> C[对照官方文档验证内容]
C --> D[添加 Last validated 日期]
D --> E[更新 INDEX.md 和 README.md]
E --> F[提交 Pull Request]
F --> G[CI 自动测试]
G --> H{测试通过?}
H -->|是| I[合并到 main 分支]
H -->|否| J[修复测试失败]
J --> F
I --> K[触发 Release 工作流]
K --> L[选择版本类型]
L --> M[发布新版本]
```
资料来源：[README.md:29-40](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## 创建功能分支
所有贡献必须通过 Git 分支工作流进行。创建新技能文档时，请使用以下命名规范：
```bash
git checkout -b skill/
```
其中 `` 是目标工具的名称（小写）。
| 分支前缀 | 用途 | 示例 |
|---------|------|------|
| `skill/` | 新增技能文档 | `skill/zendesk` |
| `skill/` | 更新现有技能 | `skill/salesforce-update` |
资料来源：[README.md:30](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## 技能文档结构要求
clawskills 要求所有技能文档严格遵循标准模板结构。文档必须包含 **11 个必需章节**，每个章节都有其特定用途。
### 必需章节列表
| 章节编号 | 章节名称 | 说明 |
|---------|---------|------|
| 1 | 概述 | 工具简介和使用场景 |
| 2 | 认证与权限 | API 密钥、OAuth 等认证方式 |
| 3 | 核心端点 | 主要 API 端点及其参数 |
| 4 | 常见工作流 | 典型使用场景和代码示例 |
| 5 | 错误处理 | 错误代码和解决方案 |
| 6 | 速率限制 | API 限制和重试策略 |
| 7 | Webhook | 事件订阅配置 |
| 8 | 数据模型 | 主要数据类型和字段 |
| 9 | 可靠性 | 容错和幂等性保证 |
| 10 | 安全与隐私 | 最佳安全实践 |
| 11 | 参考来源 | 官方文档链接 |
### 文档验证规则
CI 测试会验证以下条件：
```typescript
const REQUIRED_SECTIONS = [
"认证与权限", "核心端点", "常见工作流",
"错误处理", "速率限制", "可靠性",
"安全与隐私", "参考来源"
];
// 每个技能文件必须满足以下条件：
// 1. 包含所有必需章节
// 2. 文件大小至少 5KB
// 3. 每个章节内容非空
```
资料来源：[mcp-server/src/index.test.ts:20-40](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)
---
## 内容编写规范
### 验证要求
在提交贡献前，必须对照官方供应商文档验证以下信息：
| 验证项 | 说明 |
|-------|------|
| 端点地址 | 确保 URL 路径和参数准确 |
| 速率限制 | 验证当前限制值和计算方式 |
| 认证流程 | 确认 OAuth scopes 和 token 格式 |
| 错误代码 | 对照官方错误码文档 |
### 日期标注
每个技能文档的元数据头部必须包含 `Last validated:` 日期：
```markdown
---
tool: jira
version: "3.x"
last_validated: 2024-01-15
---
```
### 来源引用
`## 参考来源` 章节必须包含指向官方文档的有效链接。禁止添加未经核实的信息：
```markdown
## 参考来源
- [Jira Cloud REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/)
- [OAuth 2.0 认证](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)
```
资料来源：[README.md:33-36](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## 索引文件更新
当添加新技能时，必须同步更新以下文件：
| 文件路径 | 更新内容 |
|---------|---------|
| `skills/INDEX.md` | 添加新技能的链接和简介 |
| `README.md` | 在工具列表中补充新工具 |
这些更新确保用户能够发现和访问新增的技能文档。
资料来源：[README.md:37](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## Pull Request 流程
### 提交 PR
完成文档编写和索引更新后，打开 Pull Request：
```bash
git add .
git commit -m "feat: add linear skill documentation"
git push origin skill/linear
```
### CI 测试
PR 提交后，CI 流水线自动执行测试：
```bash
npm test
```
测试内容包括：
- 验证所有必需章节存在
- 检查文件大小（≥5KB）
- 确认摘要行非空
- 加载所有已知技能
| 测试项 | 失败后果 |
|-------|---------|
| 必需章节缺失 | PR 被阻止合并 |
| 文件过短 | 提示可疑的短文件 |
| 摘要为空 | 返回错误信息 |
资料来源：[README.md:38](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## 发布流程
### 版本管理策略
clawskills 使用语义化版本号（SemVer）：
| 版本类型 | 使用场景 | 示例 |
|---------|---------|------|
| `patch` | 补丁版本，文档修正 | 1.0.1 → 1.0.2 |
| `minor` | 次要版本，功能新增 | 1.0.1 → 1.1.0 |
| `major` | 主要版本，破坏性变更 | 1.0.1 → 2.0.0 |
### 发布步骤
发布流程已完全自动化：
1. 将 PR 合并到 `main` 分支
2. 进入 GitHub Actions 页面
3. 选择 **Release** 工作流
4. 点击 **Run workflow**
5. 选择版本类型（patch / minor / major）
```mermaid
graph LR
A[合并到 main] --> B[GitHub Actions]
B --> C[触发 Release 工作流]
C --> D[选择版本号]
D --> E[创建 Git Tag]
E --> F[NPM 包发布]
F --> G[生成 Release Notes]
```
资料来源：[README.md:39-40](https://github.com/Shanksg/clawskills/blob/main/README.md)
---
## 治理与更新机制
### 治理原则
根据 ROADMAP.md，clawskills 采用以下治理策略：
| 原则 | 说明 |
|-----|------|
| 准确性优先 | 所有端点和限制必须对照官方文档验证 |
| 自动化维护 | CI/CD 流水线确保文档一致性 |
| 版本控制 | 语义化版本管理变更 |
### 内容更新周期
技能文档的优先级排序：
| 优先级 | 类型 | 说明 |
|-------|------|------|
| P1 | 准确性更新 | 官方 API 变更时的紧急更新 |
| P2 | 新功能补充 | 主流工作流添加 |
| P3 | 完善现有内容 | 边缘案例和高级用法 |
资料来源：[skills/ROADMAP.md:20-30](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)
---
## 快速检查清单
在提交贡献前，请确认以下项目：
- [ ] 分支命名符合 `skill/` 规范
- [ ] 文档包含全部 11 个必需章节
- [ ] 所有端点和限制已对照官方文档验证
- [ ] 已添加 `Last validated:` 日期
- [ ] `skills/INDEX.md` 和 `README.md` 已更新
- [ ] 参考来源章节包含有效官方链接
- [ ] CI 测试全部通过
---
## 常见问题
### 技能文档最小长度是多少？
每个技能文档必须至少 **5KB**，CI 测试会检查文件大小。短文件会被标记为可疑并阻止合并。
### 可以跳过某些章节吗？
不可以。claws kills 要求所有 11 个章节都必须存在且非空。
### 如何验证认证流程是否正确？
请直接对照官方供应商文档。例如，Salesforce 的 OAuth 流程应参考官方 Developer Guide。禁止基于第三方资料或推测编写认证内容。
---
---
## Doramagic 踩坑日志
项目：Shanksg/clawskills
摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。
## 1. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1161910025 | https://github.com/Shanksg/clawskills | host_targets=mcp_host, claude
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1161910025 | https://github.com/Shanksg/clawskills | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | last_activity_observed missing
## 4. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium
## 5. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:1161910025 | https://github.com/Shanksg/clawskills | No sandbox install has been executed yet; downstream must verify before user use.
## 6. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium
## 7. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | issue_or_pr_quality=unknown
## 8. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | release_recency=unknown