项目简介

clawskills 是一个开源的技能文档库（Skills Repository），旨在为 AI 助手提供与主流第三方工具和服务集成的标准化指南。该项目通过结构化的 Markdown 文档，记录了 14 种常用工具的 API 认证方式、速率限制、错误处理和工作流配方，使 AI 代理能够准确、可靠地与这些平台交互。

该项目核心价值在于降低 AI 集成错误率。开发者可以引用对应工具的技能文档，让 AI 遵循正确的认证流程、速率限制处理方式和错误代码规范，而非依赖不完整或过时的知识。

资料来源：README.md:1

核心架构

整体架构

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 服务器提供三个核心工具：

资料来源：README.md:1

技能文档结构

必选章节

每个工具的技能文档（skill.md）必须包含 11 个标准章节，确保文档的完整性和一致性：

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

认证模式对比

资料来源：skills/figma/skill.md:1skills/linear/skill.md:1skills/slack/skill.md:1

支持的工具列表

工具覆盖范围

资料来源：README.md:1skills/ROADMAP.md:1

工作流程配方

跨工具编排示例

项目中包含跨系统的剧本（Playbook），展示如何编排多个工具的集成：

#### Slack-Jira 事故处理剧本

sequenceDiagram
    participant S as Slack
    participant B as Bot
    participant J as Jira API
    participant L as Linear API
    
    S->>B: 触发事件<br/>(reaction_added / message)
    B->>S: 获取消息 permalink
    B->>J: 搜索关联 Issue
   alt 存在关联 Issue
        B->>S: 回复已有 Issue 链接
    else 无关联 Issue
        B->>J: 创建新 Issue
        B->>S: 回复新 Issue 链接
    end

字段映射规则：

资料来源：playbooks/slack-jira-incident.md:1

开发流程

贡献者工作流

graph LR
    A[创建分支<br/>git checkout -b skill/<toolname>] --> B[遵循模板结构<br/>11 个必选章节]
    B --> C[验证端点与速率限制<br/>对照官方文档]
    C --> D[添加 Last validated 日期]
    D --> E[更新 INDEX.md<br/>和 README.md]
    E --> F[添加 Sources 链接]
    F --> G[提交 PR<br/>CI 运行 npm test]

分支命名规范

资料来源：README.md:1

CI/CD 流水线

资料来源：skills/ROADMAP.md:1

版本与发布

自动化发布

项目使用 GitHub Actions 实现自动化发布流程：

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 方式）：

npx -y clawskills-mcp

全局安装：

npm install -g clawskills-mcp

Claude Desktop 配置示例：

{
  "mcpServers": {
    "clawskills": {
      "command": "npx",
      "args": ["-y", "clawskills-mcp"]
    }
  }
}

资料来源：README.md:1

在项目中使用

开发者可以通过在 .claude/CLAUDE.md 文件中配置项目指令，引导 AI 始终使用对应的技能文档：

# Integration Skills

当编写与以下工具集成的代码时，始终先阅读对应技能文档：

- Jira → @skills/jira/skill.md
- Slack → @skills/slack/skill.md
- GitHub → @skills/github/skill.md
- ... 其他工具

遵循文档中的认证模式、速率限制处理和错误代码规范。

资料来源：README.md:1

开发路线图

当前完成状态

资料来源：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:1skills/ROADMAP.md:1

许可证与贡献

本项目采用 MIT 许可证开源，完全公开可用。项目欢迎社区贡献，所有贡献者需遵循以下准则：

1. 每个技能文档必须包含全部 11 个必选章节
2. 所有端点、速率限制和认证流程必须对照官方文档验证
3. 必须在文档中标注 "Last validated" 日期
4. 必须链接官方来源，禁止无验证的声明

资料来源：README.md:1skills/ROADMAP.md:1

概述

clawskills 是一个技能文档（Skills Documentation）仓库，旨在为 AI 工具提供标准化的第三方 API 集成指南。每个技能文档涵盖单一工具（如 Jira、Figma、Linear）的认证方式、API 端点、速率限制、错误处理和工作流程。

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

技能覆盖的工具

仓库目前包含 14 个主要工具的技能文档：

MCP 服务器架构

MCP（Model Context Protocol）服务器是 Claude AI 与技能文档之间的桥梁，允许 AI 动态查询技能信息。资料来源：mcp-server/src/index.ts

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 工具接口

资料来源：mcp-server/README.md

技能加载机制

// 从 skills/ 目录加载所有 .md 文件
function loadSkills(skillsDir: string): Map<string, string> {
  const skills = new Map<string, string>();
  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

剧本（Playbooks）

剧本是跨工具的工作流集成方案，串联多个工具的 API 实现复杂业务场景。资料来源：playbooks/INDEX.md

当前剧本

剧本搜索功能

剧本支持以下搜索参数：

开发流程与贡献规范

添加新技能的流程

1. 创建分支：git checkout -b skill/<toolname>
2. 遵循模板：参照现有 skill.md 的 11 节结构
3. 验证准确性：对照官方文档确认端点、速率限制和认证流程
4. 添加验证日期：在文档头部添加 Last validated: 日期
5. 更新索引：修改 skills/INDEX.md 和 README.md
6. 引用来源：在 Sources 章节提供官方文档链接
7. 提交 PR：CI 会运行 npm test 验证格式

质量保证

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

发布与自动化

发布流程

1. 合并 PR 到 main 分支
2. 进入 GitHub Actions → Release 工作流
3. 点击 "Run workflow"
4. 选择版本类型：patch / minor / major

CI/CD 流水线

资料来源：skills/ROADMAP.md

章节别名系统

MCP 服务器支持灵活的章节查询，使用别名快速定位内容：

资料来源：mcp-server/src/index.ts:60-80

使用方式

MCP 服务器安装

# 临时使用
npx -y clawskills-mcp

# 永久安装
npm install -g clawskills-mcp

Claude Desktop 配置

{
  "mcpServers": {
    "clawskills": {
      "command": "npx",
      "args": ["-y", "clawskills-mcp"]
    }
  }
}

资料来源：README.md

1. 概述

clawskills-mcp 是一个基于 Model Context Protocol (MCP) 的服务器实现，用于将 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 架构分层

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 核心组件

3. 安装与部署

3.1 环境要求

资料来源：mcp-server/package.json

3.2 安装方式对比

资料来源：mcp-server/README.md:27-42

3.3 Docker 部署流程

# 1. 从仓库根目录构建镜像
docker build -t clawskills-mcp -f mcp-server/Dockerfile .

# 2. 运行容器
docker run --rm -i clawskills-mcp

Docker 方式确保了与宿主机环境的隔离，适合在生产环境中部署。

4. 客户端配置

4.1 Claude Desktop 配置

配置文件路径：

配置结构：

{
  "mcpServers": {
    "clawskills": {
      "command": "npx",
      "args": ["-y", "clawskills-mcp"]
    }
  }
}

资料来源：mcp-server/README.md:14-21

4.2 Claude Code 配置

配置格式与 Claude Desktop 相同，均使用 mcpServers 配置块。

5. 工具 API

MCP 服务器暴露以下四个核心工具：

5.1 工具总览

资料来源：mcp-server/README.md:44-49

5.2 list_skills

列出所有已注册的 API 集成技能。

返回结构：

{
  "skills": [
    {
      "slug": "jira",
      "description": "Jira Cloud API integration guide"
    },
    {
      "slug": "slack",
      "description": "Slack Web API and Events API integration"
    }
  ]
}

5.3 get_skill

获取指定技能文档的完整内容或特定部分。

输入参数：

section 参数可选值：

资料来源：mcp-server/README.md:44-49

5.4 search_skills

跨所有技能文档执行全文检索。

使用场景：

• 查找特定错误码的处理方案
• 搜索某个 API 端点的使用方法
• 发现所有涉及某项权限的文档

5.5 list_playbooks

列出跨工具自动化工作流文档。

当前支持的 Playbook：

资料来源：playbooks/slack-jira-incident.md

6. 数据流与请求处理

6.1 请求处理流程

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/<tool>/skill.md）遵循统一的 11 节结构：

资料来源：skills/notion/skill.md, skills/figma/skill.md

7. 支持的 API 集成

7.1 技能库覆盖

当前 ClawSkills 包含 14 个工具的完整 API 集成文档：

资料来源：mcp-server/README.md:4-7

7.2 跨工具编排

Phase 5（跨工具编排）处于规划阶段，计划实现多系统联动工作流，例如：

graph LR
    A[Slack 告警] --> B{事件分类}
    B -->|安全事件| C[创建 Jira Bug]
    B -->|客户投诉| D[创建 Zendesk 工单]
    C --> E[通知 Slack 频道]
    D --> E

8. 错误处理与调试

8.1 常见配置错误

8.2 日志记录

MCP 服务器应在 DEBUG 模式下记录以下信息：

9. 安全考虑

9.1 敏感信息处理

9.2 权限控制

MCP 服务器本身不实现额外的访问控制，权限管理依赖于：

• Claude 客户端的认证机制
• 操作系统层面的文件系统权限
• Docker 容器的网络隔离策略

10. 维护与更新

10.1 文档更新流程

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 自动化

资料来源：skills/ROADMAP.md

11. 扩展指南

11.1 添加新技能

1. 创建分支：git checkout -b skill/<toolname>
2. 遵循模板结构创建 skill.md，确保包含全部 11 个章节
3. 验证所有端点、速率限制和认证流程
4. 更新 skills/INDEX.md 和 README.md
5. 提交 PR 触发 CI 验证

11.2 添加新工具至 MCP 服务器

在 mcp-server/src/index.ts 中注册新的工具处理器：

import { getSkill, searchSkills } from './handlers';

// 新增工具注册
server.registerTool('get_skill', getSkill);
server.registerTool('search_skills', searchSkills);

12. 参考资料

概述

MCP（Model Context Protocol）工具接口是 clawskills 项目为 AI 助手提供的标准化工具集，允许 Claude 等 AI 工具直接调用技能文档库中的内容。通过 MCP 协议，AI 可以在对话过程中实时获取各种第三方服务的集成指南、API 文档和工作流配方。

MCP 工具接口是 clawskills 项目与 AI 运行时之间的桥梁，提供了三大核心能力：

资料来源：README.md:1-100

架构设计

MCP 服务器角色

clawskills 的 MCP 服务器封装了对技能文档库的访问逻辑，作为中间层将 AI 的自然语言请求转换为结构化的文档查询。其核心职责包括：

1. 技能发现 — 维护技能索引，支持按名称或分类列出所有可用工具
2. 内容检索 — 按需加载完整的技能文档或指定章节
3. 全文搜索 — 跨所有技能文档执行关键词匹配

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 工具与底层技能文档的对应关系如下：

资料来源：README.md:80-90

安装与配置

临时运行方式

使用 npx 直接运行，无需本地安装：

npx -y clawskills-mcp

全局安装方式

将 MCP 服务器安装为全局 npm 包：

npm install -g clawskills-mcp

Claude Desktop 配置

在 Claude Desktop 的配置文件中添加 MCP 服务器连接：

{
  "mcpServers": {
    "clawskills": {
      "command": "npx",
      "args": ["-y", "clawskills-mcp"]
    }
  }
}

Claude Code 配置

对于 Claude Code 项目，可在 .claude/CLAUDE.md 中配置为项目级指令：

# 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 — 技能获取

获取指定技能的完整文档或特定章节。支持的章节筛选包括：

使用场景：

• 在开始集成前获取完整认证指南
• 调试时查阅特定错误代码含义
• 提取特定工作流配方

search_skills — 全文搜索

跨所有技能文档执行关键词搜索，返回匹配结果。

使用场景：

• 快速定位包含特定 API 端点的技能
• 搜索特定错误消息的解决方案
• 查找包含特定认证机制的文档

支持的工具生态

当前 MCP 接口覆盖以下 14 种第三方工具：

资料来源：skills/ROADMAP.md:1-50

开发阶段与路线图

根据项目路线图，MCP 工具接口已实现以下阶段：

资料来源：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 版本标头要求

持续集成与发布

项目维护以下自动化流程：

版本号遵循语义化版本（patch/minor/major），发布流程通过 GitHub Actions 手动触发。

资料来源：skills/ROADMAP.md:20-30

相关资源

• NPM 包：clawskills-mcp
• MCP 协议版本：Model Context Protocol 标准
• 技能文档路径：skills/{toolname}/skill.md
• 索引文件：skills/INDEX.md

概述

技能文档（Skill Documentation）是 clawskills 项目的核心资产，为 14 种主流工具和平台提供标准化的 API 集成指南。这些文档采用统一模板编写，包含身份验证、速率限制、常见工作流、错误处理等 11 个必填章节，确保 AI 代理能够准确、可靠地与外部系统交互。

技能文档的主要作用包括：

• 为 AI 代理提供可信赖的集成参考
• 标准化跨平台的 API 调用模式
• 降低集成错误率和开发时间
• 支持 RAG（检索增强生成）流程

资料来源：README.md:1-20

项目概述

Clawskills 是一个开源的集成技能库项目，旨在为 AI 工具（特别是 Claude Code 和 Claude Desktop）提供标准化的第三方服务集成文档。该项目将常见的 SaaS 平台和开发工具的 API 使用方法、认证流程、速率限制和最佳实践整理成结构化的技能文档，使 AI 助手能够准确、高效地帮助用户完成与这些工具的集成工作。资料来源：README.md:1

该技能库目前涵盖 14 个主流工具，包括项目管理、设计协作、CRM、客服、财务等多个领域的解决方案。每个技能文档都遵循统一的 11 部分结构，确保一致性和可维护性。资料来源：README.md:15

架构设计

技能库整体架构

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

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

文档验证机制

项目通过自动化测试确保文档质量：资料来源：mcp-server/src/index.test.ts:18-40

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

支持的工具清单

工具分类总览

工具认证方式对比

速率限制对比

跨工具工作流剧本

剧本目录

项目在 playbooks/ 目录下维护跨工具集成的工作流剧本。资料来源：README.md:10

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

开发贡献流程

添加新技能的步骤

项目采用标准化的分支和 PR 流程来管理技能文档的更新：资料来源：README.md:18-30

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

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]

版本管理策略

未来发展路线

已完成阶段

资料来源：skills/ROADMAP.md:30-40

优先级计划

优先级 1 — 新鲜度和准确性流水线

随着 14 个核心技能库完成，下一个护城河是确保文档随供应商 API 变化保持准确。资料来源：skills/ROADMAP.md:45-50

计划包括：

• 自动化 API 变更检测
• 社区贡献的审查流程
• 定期重新验证机制
• 版本化技能文档

在 Claude Code 中使用

项目指令文件示例

在 .claude/CLAUDE.md 中配置项目级指令，使 AI 始终使用这些技能文档：资料来源：README.md:60-75

# 集成技能

当编写与以下工具集成的代码时，始终先阅读对应技能文档：

- 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 的变化，并逐步扩展跨工具编排能力。

概述

跨工具工作流剧本（Playbooks）是 Clawskills 项目中用于定义和编排多系统集成的核心文档。这些剧本描述了如何将两个或多个工具（如 Slack、Jira、Zendesk、HubSpot、Salesforce、Asana 等）的 API 和事件机制组合起来，实现端到端的业务流程自动化。

剧本的核心价值在于提供经过验证的集成模式，涵盖身份验证、数据映射、事件处理、错误恢复等关键环节，帮助开发者快速实现跨系统的工作流编排。

资料来源：playbooks/INDEX.md:1-20

概述

clawskills 是一个技能文档库（Skills Documentation Library），为 AI 工具提供集成指南。该项目包含 14 种工具的完整集成文档，并通过 MCP（Model Context Protocol）服务器提供访问接口。

核心部署组件为 clawskills-mcp 服务器，它提供三个主要工具供 AI 助手调用：

资料来源：README.md:1-10

架构概览

    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 服务器：

npx -y clawskills-mcp

此方式适用于一次性测试或临时集成场景。服务器启动后，AI 工具（如 Claude Desktop）可通过 MCP 协议连接并调用技能文档。

资料来源：README.md:71-75

全局安装

对于长期使用，建议全局安装：

npm install -g clawskills-mcp

全局安装后，MCP 服务器在系统中持久可用，不受当前工作目录限制。

资料来源：README.md:76-78

Claude Desktop / Claude Code 配置

配置步骤

将以下配置添加到 Claude Desktop 或 Claude Code 的配置文件中：

{
  "mcpServers": {
    "clawskills": {
      "command": "npx",
      "args": ["-y", "clawskills-mcp"]
    }
  }
}

配置位置

验证配置

配置完成后，重启 Claude Desktop/Claude Code，然后尝试调用技能工具：

list_skills

预期返回所有 14 个工具的技能文档列表。

资料来源：README.md:79-90

MCP 服务器工具详解

list_skills

返回所有可用的技能文档列表，无需参数。

// 响应示例
{
  "skills": [
    "monday",
    "salesforce",
    "jira",
    "dynamics365",
    "hubspot",
    "servicenow",
    "zendesk",
    "asana",
    "github",
    "figma",
    "slack",
    "stripe",
    "notion",
    "linear"
  ]
}

get_skill

获取指定技能的完整文档或特定章节。

// 获取 Jira 技能文档的认证部分
{
  "skill_name": "jira",
  "section": "auth"
}

search_skills

全文本搜索所有技能文档。

CI/CD 自动化部署

持续集成

每次推送和 PR 合并时触发 CI 流程：

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   # 发布自动化

常见部署问题

相关资源

• 项目主页：https://github.com/Shanksg/clawskills
• MCP 服务器 npm 包：https://www.npmjs.com/package/clawskills-mcp
• 技能索引：skills/INDEX.md
• 开发路线图：skills/ROADMAP.md

概述

ClawSkills 项目采用自动化持续集成（CI）和持续发布（CD）流程，确保代码质量和发布效率。整个系统基于 GitHub Actions 实现自动化构建、测试和发布流程，涵盖单元测试、技能文档验证、版本管理和 npm 包发布等关键环节。

项目包含两套独立的自动化工作流：

• CI 工作流 (ci.yml)：在每次 push 和 PR 时自动执行构建和测试
• 发布工作流 (release.yml)：通过手动触发实现语义化版本管理和 npm 发布

整体架构

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 工作流在以下场景自动触发：

资料来源：.github/workflows/ci.yml

测试套件

项目使用 Vitest 作为测试框架，测试套件位于 mcp-server/src/index.test.ts。测试验证以下关键要求：

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

必需部分验证

每个 skill 文档必须包含以下 11 个部分：

1. 认证与权限
2. 核心端点
3. 常见工作流（Recipes）
4. 过滤与查询模式
5. 速率限制与重试策略
6. 错误处理
7. Webhook 配置
8. 数据模型
9. 安全与隐私
10. 配额与限制
11. 相关资源

npm 测试命令

{
  "scripts": {
    "test": "vitest run"
  }
}

资料来源：mcp-server/package.json

发布工作流详解

触发方式

发布工作流通过 GitHub Actions 手动触发（workflow_dispatch），开发者可选择发布类型。

workflow_dispatch:
  inputs:
    release_type:
      description: '发布类型'
      required: true
      type: choice
      options:
        - patch
        - minor
        - major

资料来源：.github/workflows/release.yml

发布流程步骤

graph LR
    A[选择发布类型] --> B[更新 package.json 版本号]
    B --> C[创建 Git Tag]
    C --> D[提交更改]
    D --> E[推送到 GitHub]
    E --> F[发布到 npm registry]

版本管理策略

项目采用语义化版本（SemVer）规范：

OIDC 发布机制

发布工作流使用 OpenID Connect (OIDC) 进行身份验证，确保安全的 npm 发布流程：

permissions:
  id-token: write
  contents: read

此配置允许工作流从 npm 获取短期令牌，无需长期存储凭据。

MCP Server 包管理

包结构

{
  "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

安装方式

技能文档同步机制

同步脚本

项目提供两个辅助脚本用于管理和同步技能文档：

资料来源：mcp-server/scripts/check-skills.mjs, 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

MCP 工具接口

工具列表

使用配置

在 Claude Desktop 或 Claude Code 中配置：

{
  "mcpServers": {
    "clawskills": {
      "command": "npx",
      "args": ["-y", "clawskills-mcp"]
    }
  }
}

开发贡献流程

分支命名规范

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

最佳实践

技能文档编写规范

发布检查清单

• [ ] 所有测试通过
• [ ] 版本号正确更新
• [ ] Git Tag 已创建
• [ ] CHANGELOG 已更新
• [ ] npm 发布成功

相关资源

• GitHub Actions 文档：https://docs.github.com/actions
• Vitest 测试框架：https://vitest.dev
• SemVer 规范：https://semver.org

Pitfall Log / 踩坑日志

项目：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