ClawSkills 概览与架构

项目定位与目标

ClawSkills 是一个面向 AI Agent、自动化构建者与 LLM 的 SaaS 集成技能文档库。它针对 GTM（Go-to-Market）与运营流程中最常用的 SaaS 平台，提供可直接复用的 API 使用文档、技能配方与故障排查指南。每个技能文档都附带真实可用的代码示例、限速规则、错误处理剧本以及平台版本元数据，确保 AI 在生成集成代码时遵循官方推荐做法。资料来源：README.md:1-9

仓库采用三层结构：skills/ 存放单平台技能文档；playbooks/ 存放跨工具工作流剧本；mcp-server/ 提供 MCP（Model Context Protocol）服务器，将所有技能文档以工具形式暴露给 Claude Desktop 或 Claude Code。资料来源：README.md:13-35

整体架构

下面用 Mermaid 图展示 ClawSkills 的核心组件及其关系：

graph TB
    User[用户 / AI Agent]
    MCP[MCP Server<br/>clawskills-mcp v0.6.0]
    Skills[skills/<br/>14 个技能文档]
    Playbooks[playbooks/<br/>跨工具工作流]
    Vendor[厂商 API<br/>Notion / Linear / Slack 等]
    Cron[GitHub Actions<br/>freshness 校验]

    User -->|npx / docker| MCP
    MCP -->|list_skills / get_skill / search_skills| Skills
    MCP -->|list_playbooks| Playbooks
    Skills -.->|API-Version / Bearer Token| Vendor
    Cron -.->|定期校验 Last validated| Skills
    Playbooks -->|组合调用| Skills

架构的关键点：

• 技能即文档：每个 skills/<tool>/skill.md 是一个自包含 Markdown 文档，独立跟踪平台 API 版本与 Last validated 日期。资料来源：README.md:124-129
• 剧本即编排：playbooks/ 描述多系统协同流程，例如 Zendesk → Jira 升级、HubSpot → Asana 新员工引导。资料来源：playbooks/INDEX.md
• MCP 即网关：clawskills-mcp 把所有文档转译为工具调用（list_skills、get_skill、search_skills、list_playbooks 等），供 Claude 直接检索。资料来源：mcp-server/README.md:27-34

技能文档结构

每个技能文档遵循统一的章节模板，便于 AI 按需检索。典型结构包括：适用范围与替代方案、关键概念与数据模型、认证与权限、常见工作流（配方）、查询与过滤模式、可靠性（限速、重试、幂等性）、错误处理与排查、安全与合规、测试清单、参考来源。资料来源：README.md:117-130

以 Notion 技能为例，文档会注明 API 版本头（Notion-Version: 2025-09-03）、多源数据库的 data_source_id 用法、UUIDv4 ID 格式以及 OAuth 2.0 公网集成的完整四步流程。资料来源：skills/notion/skill.md 类似地，Linear 技能明确列出 Issue 的 priority 整数映射（0=None, 1=Urgent, 2=High, 3=Medium, 4=Low）以及 identifier 简写格式。资料来源：skills/linear/skill.md

技能文档之间通过索引层互相引用：skills/INDEX.md 汇总 14 个平台、目标用户画像与 Top 工作流，并提供认证方式速查表（Monday.com API Token、Salesforce OAuth 2.0 JWT Bearer、Jira Cloud Basic Auth、Dynamics 365 Azure AD Client Credentials、HubSpot Private App Token、ServiceNow OAuth 2.0 Client Credentials 等）。资料来源：skills/INDEX.md

MCP 服务器与分发

clawskills-mcp 是一个独立 npm 包（v0.6.0），通过 dist/index.js 启动，提供 dist、skills、playbooks 三类打包产物。prepack 钩子会自动执行 sync:skills 以确保文档随包发布同步。资料来源：mcp-server/package.json:1-30

部署方式支持两种：

1. npx 即用（推荐用于 Claude Desktop / Claude Code）：在 MCP 配置中声明 {"command": "npx", "args": ["-y", "clawskills-mcp"]}。资料来源：mcp-server/README.md:11-21
2. Docker：docker build -t clawskills-mcp -f mcp-server/Dockerfile . 后以 docker run --rm -i 运行。资料来源：mcp-server/README.md:31-36

服务器同时提供命令行脚本：sync:skills 同步文档到 dist/；check:skills 与 check:freshness（--freshness 模式）用于校验文档完整性；check:docs 检查文档规范。资料来源：mcp-server/package.json:18-25

测试套件覆盖 loadSkills 等核心函数，验证技能目录扫描、空目录容错、缺失 skill.md 的跳过等行为。资料来源：mcp-server/src/index.test.ts

时效性校验与社区关注点

所有技能文档头部都标注 Last validated: 日期，配合 ROADMAP.md 的优先级 1（Freshness & Validation）持续刷新。文档还要求始终锁定 API 版本头，例如 Monday.com 固定为 2026-01。资料来源：skills/ROADMAP.md、资料来源：README.md:140-150

社区当前活跃议题 #12 指出：部分厂商（如 Monday.com）的变更日志页面采用客户端 JS 渲染，导致 curl / GitHub Actions cron 等纯 HTTP 抓取只能拿到头部与 CSS 错误，破坏了 fresh pipeline。讨论方向是为校验流水线增加 headless-browser fallback，以便在静态抓取失败时回退到 Playwright/Puppeteer 等浏览器引擎渲染。资料来源：GitHub Issue #12

这条需求反映了 ClawSkills 的核心契约——技能文档必须与厂商实时文档保持一致，否则下游 Agent 将基于过期信息生成错误代码。

See Also

• 技能索引与平台覆盖：skills/INDEX.md
• 路线图与治理：skills/ROADMAP.md
• 跨工具工作流剧本：playbooks/INDEX.md
• MCP 服务器配置：mcp-server/README.md
• 时效性回退讨论：Issue #12

技能库与跨工具剧本（Skills Library and Cross-Tool Playbooks）

项目定位与覆盖范围

ClawSkills 是一个面向 AI Agent、自动化构建者与大语言模型的 SaaS 集成技能文档库，旨在让上层模型能够以可复现、可治理的方式调用主流 GTM 与运营平台的 API README.md:1-3。

技能层（skills/）目前已发布 14 份技能文档，覆盖 Monday.com、Salesforce、Jira、Dynamics 365、HubSpot、ServiceNow、Zendesk、Asana、GitHub、Figma、Slack、Stripe、Notion、Linear skills/INDEX.md:13-27。每份技能文档通过 API-Version 或类似的版本头与 Last validated 日期在文件头中明确声明其所追踪的 API 版本，并由 skills/ROADMAP.md` 中的“季度复审循环”机制保持新鲜度。

剧本层（playbooks/）是建立在技能层之上的编排层，关注跨系统的端到端工作流，而非单一工具的端点细节 playbooks/INDEX.md:1-4。

技能文档的统一结构

每份 skill.md 都遵循一致的结构，便于 Agent 在上下文中按需加载特定小节 README.md:57-75。典型章节包括：选型用例、关键概念与数据模型、认证与权限、常见工作流（Recipes）、查询与过滤模式、可靠性（速率限制、重试、幂等性）、错误处理、安全与合规、测试清单、参考资料。

例如 skills/notion/skill.md 文档包含 multi-source databases 版本变更说明、属性类型表（title、rich_text、select 等）以及块（Block）API 的端到端工作流；skills/linear/skill.md 则以表格形式给出 Issue 字段参考（identifier、priority、state 等）。skills/slack/skill.md 在开篇列出十余个“最佳适用用例”并标明触发源与产出 skills/slack/skill.md:1-30。这种统一模板让 Agent 可按“目标”选择切片，例如处理 429 时仅加载 Reliability` 小节 README.md:33-37。

跨工具剧本模板

剧本的定位是“端到端工作流”而非“单工具参考”，通过显式定义业务触发、系统序列、字段映射、幂等键、重试与部分失败策略、对账与回滚、可观测性检查来降低多系统集成的运维风险 playbooks/INDEX.md:16-25。

目前已发布的 4 个生产级剧本 playbooks/INDEX.md:8-12：

候选列表（GitHub PR → Slack 通知、Stripe 支付失败 → HubSpot 任务等）已在 playbooks/INDEX.md:28-32 中给出，等待按优先级评分进入开发管线 skills/ROADMAP.md:62-72。

接入与维护机制

技能库通过 MCP 服务器 clawskills-mcp（npm v0.6.0）向 Claude Desktop、Claude Code 等 Agent 暴露 mcp-server/README.md:1-8, skills/ROADMAP.md:30-32。主要工具包括 list_skills、get_skill、search_skills、list_playbooks、get_playbook、search_playbooks、search_clawskills mcp-server/README.md:28-70。安装方式支持 npx -y clawskills-mcp、npm install -g clawskills-mcp 或通过 mcp-server/Dockerfile 构建的容器镜像 mcp-server/README.md:14-23。

flowchart LR
    A[Agent/LLM] -->|MCP| B[clawskills-mcp]
    B -->|list/get/search| C[skills/*.md]
    B -->|list/get/search| D[playbooks/*.md]
    C -->|Recipe 引用| E[单工具 API]
    D -->|编排| F[多系统工作流]
    G[Freshness Pipeline] -->|季度重校验| C
    G -->|Issue #12 改进| H[Headless Browser 回退]

为防止供应商文档过期，仓库引入了新鲜度流水线（Freshness Pipeline），对超过 90 天的文档自动标记并触发重审 skills/ROADMAP.md:96-103。社区已记录的 Issue #12 表明：部分供应商变更日志页面采用客户端 JS 渲染，导致 curl / WebFetch / GitHub Actions cron 只能拿到头部或 CSS 错误，需要在流水线中加入 Headless Browser 兜底机制，以保证 Skill 文档头的 Last validated 日期真正反映 API 现状。

See Also

• skills/INDEX.md — 全部工具的索引、顶部工作流、认证速查
• skills/ROADMAP.md — 阶段化构建计划与治理模型
• playbooks/INDEX.md — 已发布与候选剧本
• mcp-server/README.md — MCP 服务器的安装与工具说明
• README.md — 顶层项目说明与最佳实践

概述

clawskills-mcp 是一个基于 Model Context Protocol（MCP） 的服务器，负责把仓库内 14 份结构化的 skill.md 文档以及后续的 playbooks/ 工作流手册暴露为 AI 代理可以直接调用的工具集。它的 npm 包名是 clawskills-mcp，当前版本 0.6.0，与各 skill 自身记录的 API 版本相互独立：MCP 包版本号只反映服务器/工具层变更，而 skill 文档头部的 Last validated 字段追踪底层 SaaS API 的版本。资料来源：mcp-server/package.json:2-2、mcp-server/README.md:3-5。

整个仓库采用「文档即资产」的策略：14 份 skill + 跨工具 playbook 是单一事实源（single source of truth），MCP 服务器只是把这份资产搬运到 Claude Desktop、Claude Code、Cursor 等客户端内的工具层，从而避免在 prompt 中重复粘贴大段文档。资料来源：README.md:9-15、skills/INDEX.md:1-5。

安装与运行

clawskills-mcp 支持两种主流运行方式，分别面向本地开发与容器化部署。

MCP 客户端的标准配置片段如下，资料来源：mcp-server/README.md:14-22：

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

启动入口在 mcp-server/package.json 的 bin 字段中声明为 clawskills-mcp，运行产物为 dist/index.js。build 脚本先执行 sync:skills 再 tsc，保证 TypeScript 编译前 skills/ 与 playbooks/ 已经同步到打包目录。资料来源：mcp-server/package.json:21-37。

工具接口

clawskills-mcp 暴露的核心工具面向「按需检索 + 全文搜索」两个使用场景：

资料来源：mcp-server/README.md:36-41。

mcp-server/src/index.ts 是服务器与 MCP 协议适配的入口，mcp-server/src/index.test.ts 通过「真实 skill 加载」测试保障所有 14 份文档在打包后仍可被正确解析。roadmap 中也明确指出，在 playbooks 层稳定后将优先实现 list_playbooks、get_playbook 以及「更偏好 recipe/playbook 而非零散提及」的搜索排序。资料来源：mcp-server/src/index.test.ts:1-1、skills/ROADMAP.md:53-62。

下图展示了从用户提问到具体 API 调用之间的检索链路：

flowchart LR
  A[用户/Agent] --> B[MCP 客户端]
  B --> C[clawskills-mcp]
  C --> D[list_skills / search_skills]
  D --> E[skill.md 索引]
  E --> F[get_skill 返回切片]
  F --> B
  B --> G[生成 API 调用代码]

打包、同步与保鲜流程

mcp-server/package.json 暴露了完整的运维脚本链，资料来源：mcp-server/package.json:21-37：

• sync:skills — 把仓库根目录的 skills/、playbooks/ 同步到 mcp-server/skills/、mcp-server/playbooks/，确保打包后能离线携带。
• check:skills — 静态校验所有 skill 文档结构。
• check:freshness — 触发保鲜流水线，识别 90 天以上未复审的文档。
• prepack — npm 发布前自动跑 sync:skills，防止脏打包。
• test — 使用 vitest run 执行 index.test.ts。

保鲜流水线与社区关注点紧密相关：issue #12 反馈部分 vendor changelog 由 JS 客户端渲染，导致 curl、GitHub Actions 定时任务抓取时只能拿到 CSS/HTML 骨架，使 freshness 流水线失效。roadmap 将「增加 headless-browser 回退」列为保鲜改进的优先项。资料来源：skills/ROADMAP.md:24-32。

质量治理遵循三条约束：

1. 版本钉死：每次复审在文档头部更新 API version 与 Last validated。
2. 季度复审：超过 90 天的文档被 freshness 流水线自动标记。
3. 变更提醒：使用 > ⚠️ Changed [date]: 行内标注关键 API 变更（如鉴权、限流、字段）。

资料来源：skills/ROADMAP.md:64-70。

常见失败模式

• 打包后找不到 skill：通常因跳过 prepack/build 中的 sync:skills 导致 mcp-server/skills/ 为空，需重新执行 npm run sync:skills。
• 保鲜流水线漏报：与 issue #12 同类问题，vendor 页面为 SPA 渲染；需要为 check:freshness 增加 headless-browser 回退（Playwright/Puppeteer）才能完整捕获变更。
• MCP 客户端连不上服务器：检查 claude_desktop_config.json 中 command/args 是否正确指向 npx -y clawskills-mcp，并确认 Node ≥ 18。

See Also

• ClawSkills 主仓库 README
• Skill 索引 INDEX.md
• 路线图 ROADMAP.md
• Issue #12 — Freshness pipeline headless fallback

概述

ClawSkills 的核心是一个由 AI 代理读取的结构化 Markdown 技能文档库，覆盖 Monday.com、Salesforce、Jira、Notion、Linear、HubSpot、ServiceNow、Zendesk、Dynamics 365、GitHub、Slack、Figma、Stripe 等 14 个 SaaS 平台。资料来源：skills/INDEX.md:1-20

由于 SaaS API 经常变化（版本号、认证方式、限流策略都会随厂商调整），仓库建立了一套 Freshness Pipeline 持续校准每份技能文档与对应官方文档的一致性。README.md 明确指出："Each skill tracks its own platform version and Last validated date in the document header"，而 MCP 包 (clawskills-mcp) 则使用独立的 npm 版本号，因为后者版本化的是服务器/工具层、而非底层 SaaS API。资料来源：README.md:50-60 / mcp-server/README.md:1-15

每份技能文档头部都会写入 Last validated: 日期与目标 API 版本号（如 Notion 的 2025-09-03），用于在代理生成代码时锁定版本基线。资料来源：skills/notion/skill.md:1-20

Freshness Pipeline 的工作方式

管道由三层组成：

1. 人工再验证（Re-validation pass）：维护者定期对全部技能文档执行一次完整再验证，逐条对照官方文档复核端点、限流、错误码、作用域。
2. 自动化校验：CI 在 PR 合并前运行 npm test，确保每份技能文档符合 11 节模板结构且能成功加载。资料来源：README.md:120-130
3. MCP 层独立版本发布：clawskills-mcp 通过 release.yml 单独发版。资料来源：mcp-server/README.md:1-15

下图为当前管道的端到端流程以及已识别的盲点：

flowchart LR
    A[Vendor 官方文档 / Changelog] -->|HTTP fetch| B[原始 HTML 抓取]
    B --> C{是否 JS 渲染?}
    C -->|否| D[解析并对比 skill.md]
    C -->|是| E[当前管道失败<br/>仅返回 header / CSS]
    D --> F[更新文档<br/>刷新 Last validated]
    E -.->|计划中| G[Headless browser fallback]
    G -.-> F
    F --> H[PR + CI npm test]
    H --> I[GitHub Actions Release workflow]

已知缺陷：JS 渲染的厂商 changelog

2026-05-11 的再验证中确认：多家厂商的 changelog 页面是客户端渲染，纯 HTTP 客户端（curl、WebFetch、GitHub Actions cron 任务）只能拿到 header 与 CSS 报错，导致管道出现盲点。资料来源：GitHub Issue #12 已规划的解决方案是引入 headless-browser fallback：在普通 HTTP 抓取失败时回退到无头浏览器（如 Playwright / Puppeteer）执行 JS 并取回真实正文，从而让 changelog 类的厂商页面也能被纳入自动巡检。

治理与优先级

治理节奏在 skills/ROADMAP.md 中明确定义。ROADMAP.md 将维护工作划分为多个 Priority：Priority 1 — Freshness & packaging 是最高优先级；Priority 2/3 涵盖多工具适配与平台发布（npm、MCP 注册表、Mintlify 文档站点）；Priority 4 收尾 Phase 4/5 的空白项（Bulk API、跨工具编排）。资料来源：skills/ROADMAP.md:1-80

影响技能新鲜度的高频厂商变化包括：Monday.com 每季度发布新 API 版本，API-Version 头需固定到 2026-01 或后续版本；Figma 在 2025-11 弃用 files:read 范围、改用粒度作用域并调整了按 plan+seat 类型区分的限流；Notion 在 2025-09-03 引入 multi-source databases，新建页面需要使用 data_source_id 而非 database_id。资料来源：README.md:140-160 / skills/notion/skill.md:1-20

贡献流程

新增或更新技能需遵循以下流程：

1. 新建分支：git checkout -b skill/<toolname>。资料来源：README.md:170-180
2. 遵循模板：每份 skill.md 必须包含 11 个必填章节（Key concepts & data model、Auth、Recipes、Rate limits、Errors、Security、Testing checklist、Sources 等）。资料来源：README.md:80-110
3. 对照官方文档验证：提交前对所有端点、限流、认证流程做人工核对。
4. 更新头部元数据：写入最新的 Last validated: 日期与 API 版本。资料来源：skills/linear/skill.md:1-15
5. 同步索引：新增工具时同步更新 skills/INDEX.md 与根 README.md。资料来源：skills/INDEX.md:1-20
6. CI 校验：PR 触发 npm test，自动校验技能文档加载与章节完整性。资料来源：README.md:185-195
7. 发布自动化：合并到 main 后，通过 GitHub Actions → Release → Run workflow 选择 patch / minor / major 完成发版。资料来源：README.md:195-200

See Also

• skills/ROADMAP.md — 完整优先级与治理流程
• mcp-server/README.md — MCP 服务器与 npm 发布
• GitHub Issue #12 — Headless browser fallback 提案
• README.md — 项目总体说明与最佳实践

Pitfall Log / 踩坑日志

项目：Shanksg/clawskills

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs。

1. 安装坑 · 来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Shanksg/clawskills/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/Shanksg/clawskills | host_targets=mcp_host, claude, claude_code

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/Shanksg/clawskills | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/Shanksg/clawskills | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Shanksg/clawskills | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/Shanksg/clawskills | no_demo; severity=medium

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/Shanksg/clawskills | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/Shanksg/clawskills | release_recency=unknown