{
"canonical_name": "Shanksg/clawskills",
"compilation_id": "pack_456455709b7e4fc7bf07b855e03796f1",
"created_at": "2026-05-13T14:18:23.873680+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx -y clawskills-mcp` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx -y clawskills-mcp",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_19240457effb421ebab746f071da149e"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_7e2c1fe5c4616406c51e50944cf67783",
"canonical_name": "Shanksg/clawskills",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/Shanksg/clawskills",
"slug": "clawskills",
"source_packet_id": "phit_d8e0452baf28460eb769ab7786db654d",
"source_validation_id": "dval_5c9a84a2c3d84783bc392d5f713cfdc7"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 0,
"one_liner_en": "MCP server + skill docs teaching AI agents to reliably integrate with 14 SaaS APIs — auth, rate limits, recipes, and cross-tool playbooks.",
"one_liner_zh": "MCP server + skill docs teaching AI agents to reliably integrate with 14 SaaS APIs — auth, rate limits, recipes, and cross-tool playbooks.",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, api, server"
},
"target_user": "使用 mcp_host, claude 等宿主 AI 的用户",
"title_en": "clawskills",
"title_zh": "clawskills 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_d8e0452baf28460eb769ab7786db654d",
"page_model": {
"artifacts": {
"artifact_slug": "clawskills",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx -y clawskills-mcp",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/Shanksg/clawskills#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "MCP server + skill docs teaching AI agents to reliably integrate with 14 SaaS APIs — auth, rate limits, recipes, and cross-tool playbooks."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1161910025 | https://github.com/Shanksg/clawskills | host_targets=mcp_host, claude"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1161910025 | https://github.com/Shanksg/clawskills | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:1161910025 | https://github.com/Shanksg/clawskills | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 2,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 0
},
"source_url": "https://github.com/Shanksg/clawskills",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "MCP server + skill docs teaching AI agents to reliably integrate with 14 SaaS APIs — auth, rate limits, recipes, and cross-tool playbooks.",
"title": "clawskills 能力包",
"trial_prompt": "# clawskills - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 clawskills 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-project-structure：项目结构。围绕“项目结构”模拟一次用户任务，不展示安装或运行结果。\n3. page-mcp-server-architecture：MCP 服务器架构。围绕“MCP 服务器架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-mcp-tools：MCP 工具接口。围绕“MCP 工具接口”模拟一次用户任务，不展示安装或运行结果。\n5. page-skill-anatomy：技能文档结构。围绕“技能文档结构”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-project-structure\n输入：用户提供的“项目结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-mcp-server-architecture\n输入：用户提供的“MCP 服务器架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-mcp-tools\n输入：用户提供的“MCP 工具接口”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-skill-anatomy\n输入：用户提供的“技能文档结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-project-structure：Step 2 必须围绕“项目结构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-mcp-server-architecture：Step 3 必须围绕“MCP 服务器架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-mcp-tools：Step 4 必须围绕“MCP 工具接口”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-skill-anatomy：Step 5 必须围绕“技能文档结构”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Shanksg/clawskills\n- https://github.com/Shanksg/clawskills#readme\n- skills/asana/skill.md\n- skills/dynamics365/skill.md\n- skills/figma/skill.md\n- skills/github/skill.md\n- skills/hubspot/skill.md\n- skills/jira/skill.md\n- skills/linear/skill.md\n- skills/monday/skill.md\n- skills/notion/skill.md\n- skills/salesforce/skill.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 clawskills 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Freshness pipeline: add headless-browser fallback for JS-rendered vendor（https://github.com/Shanksg/clawskills/issues/12）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Freshness pipeline: add headless-browser fallback for JS-rendered vendor",
"url": "https://github.com/Shanksg/clawskills/issues/12"
}
],
"status": "已收录 1 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "MCP server + skill docs teaching AI agents to reliably integrate with 14 SaaS APIs — auth, rate limits, recipes, and cross-tool playbooks.",
"effort": "安装已验证",
"forks": 0,
"icon": "link",
"name": "clawskills 能力包",
"risk": "需复核",
"slug": "clawskills",
"stars": 0,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/Shanksg/clawskills 项目说明书\n\n生成时间：2026-05-13 12:47:35 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [项目结构](#page-project-structure)\n- [MCP 服务器架构](#page-mcp-server-architecture)\n- [MCP 工具接口](#page-mcp-tools)\n- [技能文档结构](#page-skill-anatomy)\n- [技能目录总览](#page-skill-catalog)\n- [跨工具工作流剧本](#page-playbooks)\n- [部署指南](#page-deployment)\n- [持续集成与发布](#page-cicd)\n- [贡献指南](#page-contributing)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[项目结构](#page-project-structure), [技能目录总览](#page-skill-catalog)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)\n- [skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n- [skills/jira/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/stripe/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/stripe/skill.md)\n- [skills/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)\n- [skills/servicenow/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/servicenow/skill.md)\n- [skills/dynamics365/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/dynamics365/skill.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# 项目概述\n\n## 项目简介\n\nclawskills 是一个开源的技能文档库（Skills Repository），旨在为 AI 助手提供与主流第三方工具和服务集成的标准化指南。该项目通过结构化的 Markdown 文档，记录了 14 种常用工具的 API 认证方式、速率限制、错误处理和工作流配方，使 AI 代理能够准确、可靠地与这些平台交互。\n\n该项目核心价值在于**降低 AI 集成错误率**。开发者可以引用对应工具的技能文档，让 AI 遵循正确的认证流程、速率限制处理方式和错误代码规范，而非依赖不完整或过时的知识。\n\n资料来源：[README.md:1]()\n\n## 核心架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[clawskills 仓库] --> B[技能文档库 skills/]\n A --> C[剧本库 playbooks/]\n A --> D[MCP 服务器 clawskills-mcp]\n B --> E[14 个工具技能文档]\n E --> E1[Monday.com]\n E --> E2[Salesforce]\n E --> E3[Jira]\n E --> E4[Dynamics 365]\n E --> E5[HubSpot]\n E --> E6[ServiceNow]\n E --> E7[Zendesk]\n E --> E8[Asana]\n E --> E9[GitHub]\n E --> E10[Figma]\n E --> E11[Slack]\n E --> E12[Stripe]\n E --> E13[Notion]\n E --> E14[Linear]\n D --> F[list_skills]\n D --> G[get_skill]\n D --> H[search_skills]\n```\n\n### MCP 服务器工具\n\nclawskills 提供了 MCP（Model Context Protocol）服务器，使 Claude 等 AI 助手能够动态查询技能文档。MCP 服务器提供三个核心工具：\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `list_skills` | 列出所有可用的技能文档 |\n| `get_skill` | 获取完整的技能文档或指定章节（如 `auth`、`rate-limits`、`recipes`、`errors`） |\n| `search_skills` | 在所有技能文档中进行全文搜索 |\n\n资料来源：[README.md:1]()\n\n## 技能文档结构\n\n### 必选章节\n\n每个工具的技能文档（`skill.md`）必须包含 **11 个标准章节**，确保文档的完整性和一致性：\n\n```mermaid\ngraph LR\n A[必选章节] --> B[认证与权限]\n A --> C[核心资源与字段]\n A --> D[速率限制与重试]\n A --> E[错误代码处理]\n A --> F[常见工作流]\n A --> G[最佳实践]\n A --> H[故障排除]\n A --> I[QA 检查清单]\n A --> J[来源链接]\n A --> K[最后验证日期]\n```\n\n资料来源：[README.md:1]()\n\n### 认证模式对比\n\n| 认证方式 | 适用场景 | 代表性工具 |\n|---------|---------|-----------|\n| Personal Access Token (PAT) | 服务器到服务器集成 | Figma、Linear、GitHub |\n| OAuth 2.0 | 用户授权应用 | Figma、Linear、Slack、Stripe |\n| API Key / Bearer Token | 标准 REST API | Jira、ServiceNow、Dynamics 365、HubSpot、Notion、Stripe |\n| 基本认证 (Basic Auth) | 简单场景 | Zendesk |\n\n资料来源：[skills/figma/skill.md:1]()[skills/linear/skill.md:1]()[skills/slack/skill.md:1]()\n\n## 支持的工具列表\n\n### 工具覆盖范围\n\n| 工具名称 | 主要功能 | API 类型 | 关键认证方式 |\n|---------|---------|---------|------------|\n| Monday.com | 项目管理与工作流 | REST | OAuth 2.0 + API Token |\n| Salesforce | CRM 与销售自动化 | REST + OAuth | Connected App |\n| Jira | 敏捷项目与缺陷跟踪 | REST | API Token / OAuth |\n| Dynamics 365 | 企业 ERP/CRM | OData REST | OAuth 2.0 |\n| HubSpot | 营销与 CRM | REST + Webhooks | Private App Token |\n| ServiceNow | IT 服务管理 | REST | OAuth 2.0 / Basic Auth |\n| Zendesk | 客服与支持工单 | REST | API Token |\n| Asana | 团队协作与任务管理 | REST | Personal Access Token |\n| GitHub | 代码托管与 DevOps | REST + GraphQL | Personal Access Token |\n| Figma | 设计与协作 | REST | Personal Access Token / OAuth |\n| Slack | 企业通讯与自动化 | Web API | Bot Token / User Token |\n| Stripe | 支付与订阅管理 | REST + Webhooks | Secret Key |\n| Notion | 文档与知识管理 | REST | Internal Integration Token |\n| Linear | 开发者项目追踪 | GraphQL | API Key / OAuth |\n\n资料来源：[README.md:1]()[skills/ROADMAP.md:1]()\n\n## 工作流程配方\n\n### 跨工具编排示例\n\n项目中包含跨系统的剧本（Playbook），展示如何编排多个工具的集成：\n\n#### Slack-Jira 事故处理剧本\n\n```mermaid\nsequenceDiagram\n participant S as Slack\n participant B as Bot\n participant J as Jira API\n participant L as Linear API\n \n S->>B: 触发事件
(reaction_added / message)\n B->>S: 获取消息 permalink\n B->>J: 搜索关联 Issue\n alt 存在关联 Issue\n B->>S: 回复已有 Issue 链接\n else 无关联 Issue\n B->>J: 创建新 Issue\n B->>S: 回复新 Issue 链接\n end\n```\n\n**字段映射规则：**\n\n| Slack 事件字段 | Jira 相关字段 |\n|---------------|--------------|\n| `event.item.channel` + `event.item.ts` | Correlation Key |\n| 消息文本（首句，截断至 ~120 字符） | Issue Summary |\n| 消息内容 + Thread 回复 | Issue Description |\n| 触发事件的频道 | Issue Project / Components |\n| Slack Permalink | Description 中的链接 |\n\n资料来源：[playbooks/slack-jira-incident.md:1]()\n\n## 开发流程\n\n### 贡献者工作流\n\n```mermaid\ngraph LR\n A[创建分支
git checkout -b skill/] --> B[遵循模板结构
11 个必选章节]\n B --> C[验证端点与速率限制
对照官方文档]\n C --> D[添加 Last validated 日期]\n D --> E[更新 INDEX.md
和 README.md]\n E --> F[添加 Sources 链接]\n F --> G[提交 PR
CI 运行 npm test]\n```\n\n### 分支命名规范\n\n| 分支类型 | 命名格式 | 示例 |\n|---------|---------|-----|\n| 新增工具技能 | `skill/` | `skill/notion` |\n| 功能改进 | `feat/` | `feat/add-vertex-ai` |\n| 文档修复 | `fix/` | `fix/correct-oauth-url` |\n\n资料来源：[README.md:1]()\n\n### CI/CD 流水线\n\n| 阶段 | 触发条件 | 验证内容 |\n|-----|---------|---------|\n| 构建测试 | 每次 Push / PR | `npm test` 执行单元测试 |\n| 技能验证 | PR 提交时 | 必选章节完整性、最小文件大小（≥5 KB）、所有 14 个工具验证 |\n| 发布 | GitHub Actions → Release Workflow | patch / minor / major 版本选择、npm publish |\n\n资料来源：[skills/ROADMAP.md:1]()\n\n## 版本与发布\n\n### 自动化发布\n\n项目使用 GitHub Actions 实现自动化发布流程：\n\n```mermaid\ngraph TD\n A[合并到 main 分支] --> B[手动触发 Release Workflow]\n B --> C{版本类型选择}\n C -->|patch| D[0.0.x 补丁版本]\n C -->|minor| E[0.x.0 次版本]\n C -->|major| F[x.0.0 主版本]\n D --> G[更新版本号]\n E --> G\n F --> G\n G --> H[创建 Git Tag]\n H --> I[npm publish]\n I --> J[生成 Release Notes]\n```\n\n发布流程通过 OIDC（OpenID Connect）身份验证确保安全性，无需存储长期 npm 凭据。\n\n资料来源：[skills/ROADMAP.md:1]()\n\n## 安装与使用\n\n### MCP 服务器安装\n\n**临时使用（npx 方式）：**\n\n```bash\nnpx -y clawskills-mcp\n```\n\n**全局安装：**\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n**Claude Desktop 配置示例：**\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:1]()\n\n### 在项目中使用\n\n开发者可以通过在 `.claude/CLAUDE.md` 文件中配置项目指令，引导 AI 始终使用对应的技能文档：\n\n```markdown\n# Integration Skills\n\n当编写与以下工具集成的代码时，始终先阅读对应技能文档：\n\n- Jira → @skills/jira/skill.md\n- Slack → @skills/slack/skill.md\n- GitHub → @skills/github/skill.md\n- ... 其他工具\n\n遵循文档中的认证模式、速率限制处理和错误代码规范。\n```\n\n资料来源：[README.md:1]()\n\n## 开发路线图\n\n### 当前完成状态\n\n| 阶段 | 主题 | 状态 | 说明 |\n|-----|------|------|------|\n| Phase 1 | 基础（认证 + 核心 CRUD） | ✅ 完成 | 14 个工具全覆盖 |\n| Phase 2 | 高频工作流 | ✅ 完成 | 每个工具 6-12 个配方 |\n| Phase 3 | 事件驱动与实时 | ✅ 完成 | Webhook 设置与签名验证 |\n| Phase 4 | 批量与高级操作 | ⚠️ 部分 | 大多数工具已记录，>500 条记录示例未全部完成 |\n| Phase 5 | 跨工具编排 | ❌ 未开始 | INDEX.md 中有模式描述，无专门配方 |\n\n资料来源：[skills/ROADMAP.md:1]()\n\n### 未来发展方向\n\n**优先级 1 — 内容准确性流水线**\n\n随着供应商 API 持续演进，维护准确性将成为项目核心竞争优势。计划包括：\n\n- 自动化验证官方文档变更\n- 社区贡献审核机制\n- 供应商 API 变更告警系统\n\n资料来源：[skills/ROADMAP.md:1]()\n\n## 项目结构\n\n```\nclawskills/\n├── README.md # 项目主文档\n├── skills/\n│ ├── INDEX.md # 技能索引\n│ ├── ROADMAP.md # 开发路线图\n│ ├── figma/\n│ │ └── skill.md\n│ ├── github/\n│ │ └── skill.md\n│ ├── jira/\n│ │ └── skill.md\n│ ├── linear/\n│ │ └── skill.md\n│ ├── monday/\n│ │ └── skill.md\n│ ├── salesforce/\n│ │ └── skill.md\n│ ├── servicenow/\n│ │ └── skill.md\n│ ├── slack/\n│ │ └── skill.md\n│ ├── stripe/\n│ │ └── skill.md\n│ ├── notion/\n│ │ └── skill.md\n│ ├── dynamics365/\n│ │ └── skill.md\n│ ├── hubspot/\n│ │ └── skill.md\n│ ├── asana/\n│ │ └── skill.md\n│ └── zendesk/\n│ └── skill.md\n├── playbooks/\n│ └── slack-jira-incident.md # 跨工具剧本\n└── .github/\n └── workflows/\n ├── ci.yml # CI 测试流水线\n └── release.yml # 自动化发布\n```\n\n资料来源：[README.md:1]()[skills/ROADMAP.md:1]()\n\n## 许可证与贡献\n\n本项目采用 MIT 许可证开源，完全公开可用。项目欢迎社区贡献，所有贡献者需遵循以下准则：\n\n1. 每个技能文档必须包含全部 11 个必选章节\n2. 所有端点、速率限制和认证流程必须对照官方文档验证\n3. 必须在文档中标注 \"Last validated\" 日期\n4. 必须链接官方来源，禁止无验证的声明\n\n资料来源：[README.md:1]()[skills/ROADMAP.md:1]()\n\n---\n\n\n\n## 项目结构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [MCP 服务器架构](#page-mcp-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n \n\n# 项目结构\n\n## 概述\n\n`clawskills` 是一个技能文档（Skills Documentation）仓库，旨在为 AI 工具提供标准化的第三方 API 集成指南。每个技能文档涵盖单一工具（如 Jira、Figma、Linear）的认证方式、API 端点、速率限制、错误处理和工作流程。\n\n```mermaid\ngraph TD\n A[clawskills 仓库] --> B[skills/ 技能文档]\n A --> C[mcp-server/ MCP服务器]\n A --> D[playbooks/ 工作流剧本]\n \n B --> B1[figma/skill.md]\n B --> B2[jira/skill.md]\n B --> B3[linear/skill.md]\n B --> B14[... 共14个工具]\n \n C --> C1[src/index.ts]\n C --> C2[src/index.test.ts]\n \n D --> D1[zendesk-jira-bug-escalation.md]\n D --> D2[hubspot-asana-onboarding.md]\n```\n\n## 目录结构\n\n```\nclawskills/\n├── README.md # 仓库主文档\n├── package.json # npm 包配置\n├── skills/ # 技能文档目录\n│ ├── INDEX.md # 技能索引\n│ ├── ROADMAP.md # 开发路线图\n│ ├── figma/skill.md # Figma 技能文档\n│ ├── github/skill.md # GitHub 技能文档\n│ ├── hubspot/skill.md # HubSpot 技能文档\n│ ├── jira/skill.md # Jira 技能文档\n│ ├── linear/skill.md # Linear 技能文档\n│ ├── monday/skill.md # Monday.com 技能文档\n│ ├── notion/skill.md # Notion 技能文档\n│ ├── salesforce/skill.md # Salesforce 技能文档\n│ ├── servicenow/skill.md # ServiceNow 技能文档\n│ ├── slack/skill.md # Slack 技能文档\n│ ├── stripe/skill.md # Stripe 技能文档\n│ ├── zendesk/skill.md # Zendesk 技能文档\n│ ├── asana/skill.md # Asana 技能文档\n│ └── dynamics365/skill.md # Dynamics 365 技能文档\n├── playbooks/ # 工作流剧本目录\n│ ├── INDEX.md # 剧本索引\n│ ├── zendesk-jira-bug-escalation.md\n│ └── hubspot-asana-onboarding.md\n└── mcp-server/ # MCP 服务器实现\n ├── README.md # MCP 服务器文档\n ├── package.json # MCP 服务包配置\n └── src/\n ├── index.ts # 主服务器逻辑\n └── index.test.ts # 单元测试\n```\n\n## 技能文档结构（skill.md）\n\n每个工具的技能文档都遵循统一的 11 节模板结构，确保一致性和完整性。资料来源：[skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n\n| 章节 | 用途 |\n|------|------|\n| Overview | 工具简介、认证前置条件 |\n| Authentication & permissions | 认证方式、权限范围 |\n| Reliability: rate limits, retries, idempotency | 速率限制、重试策略 |\n| Error handling & troubleshooting | 错误码、调试技巧 |\n| Common workflows (recipes) | 常用 API 调用模式（6-12 个） |\n| Webhooks | 事件订阅、签名验证 |\n| Available tools / API endpoints | 端点清单 |\n| Data model: entities & fields | 数据实体、字段说明 |\n| Pagination | 分页方式 |\n| Code samples | 代码示例 |\n| Resources & references | 官方文档链接 |\n\n### 技能覆盖的工具\n\n仓库目前包含 **14 个主要工具**的技能文档：\n\n| 工具 | 主要功能 |\n|------|----------|\n| Figma | 设计协作、组件导出 |\n| GitHub | 代码仓库、Issue、PR |\n| HubSpot | CRM、营销自动化 |\n| Jira | 项目追踪、Bug 管理 |\n| Linear | 敏捷项目管理 |\n| Monday.com | 团队协作 |\n| Notion | 文档、知识库 |\n| Salesforce | 企业 CRM |\n| ServiceNow | IT 服务管理 |\n| Slack | 团队通讯 |\n| Stripe | 支付处理 |\n| Zendesk | 客服工单 |\n| Asana | 任务管理 |\n| Dynamics 365 | 微软企业套件 |\n\n## MCP 服务器架构\n\nMCP（Model Context Protocol）服务器是 Claude AI 与技能文档之间的桥梁，允许 AI 动态查询技能信息。资料来源：[mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n```mermaid\ngraph LR\n A[Claude AI] -->|list_skills| B[MCP 服务器]\n A -->|get_skill| B\n A -->|search_skills| B\n A -->|list_playbooks| B\n A -->|get_playbook| B\n A -->|search_playbooks| B\n \n B -->|读取| C[skills/*.md]\n B -->|读取| D[playbooks/*.md]\n \n B -->|JSON响应| A\n```\n\n### MCP 工具接口\n\n| 工具名 | 功能 |\n|--------|------|\n| `list_skills` | 列出所有可用技能 |\n| `get_skill` | 获取完整技能文档或指定章节 |\n| `search_skills` | 全文搜索技能文档 |\n| `list_playbooks` | 列出所有工作流剧本 |\n| `get_playbook` | 获取指定剧本内容 |\n| `search_playbooks` | 搜索剧本内容 |\n| `search_clawskills` | 全局搜索 |\n\n资料来源：[mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n\n### 技能加载机制\n\n```typescript\n// 从 skills/ 目录加载所有 .md 文件\nfunction loadSkills(skillsDir: string): Map {\n const skills = new Map();\n const entries = fs.readdirSync(skillsDir, { withFileTypes: true });\n for (const entry of entries) {\n if (!entry.isFile() || !entry.name.endsWith(\".md\") || entry.name === \"INDEX.md\") continue;\n const slug = entry.name.replace(/\\.md$/, \"\");\n const content = fs.readFileSync(path.join(skillsDir, entry.name), \"utf-8\");\n skills.set(slug, content);\n }\n return skills;\n}\n```\n\n资料来源：[mcp-server/src/index.ts:1-15](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n## 剧本（Playbooks）\n\n剧本是跨工具的工作流集成方案，串联多个工具的 API 实现复杂业务场景。资料来源：[playbooks/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/INDEX.md)\n\n### 当前剧本\n\n| 剧本名称 | 描述 |\n|----------|------|\n| `zendesk-jira-bug-escalation` | Zendesk 工单自动升级到 Jira Bug |\n| `hubspot-asana-onboarding` | HubSpot 联系人同步到 Asana 任务 |\n\n### 剧本搜索功能\n\n剧本支持以下搜索参数：\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `query` | string | 是 | 搜索词，如 \"idempotency\"、\"rollback\"、\"closed won\" |\n\n## 开发流程与贡献规范\n\n### 添加新技能的流程\n\n1. **创建分支**：`git checkout -b skill/`\n2. **遵循模板**：参照现有 `skill.md` 的 11 节结构\n3. **验证准确性**：对照官方文档确认端点、速率限制和认证流程\n4. **添加验证日期**：在文档头部添加 `Last validated:` 日期\n5. **更新索引**：修改 `skills/INDEX.md` 和 `README.md`\n6. **引用来源**：在 `Sources` 章节提供官方文档链接\n7. **提交 PR**：CI 会运行 `npm test` 验证格式\n\n### 质量保证\n\n| 测试项 | 说明 |\n|--------|------|\n| 技能加载测试 | 所有 14 个工具技能必须可加载 |\n| 摘要行检查 | 每个技能必须有非空摘要 |\n| 章节完整性 | 必须包含全部 11 个必需章节 |\n| 文件大小 | 每个技能文件至少 5KB |\n\n```typescript\nit(\"every skill file is at least 5KB\", () => {\n for (const [slug, content] of skills.entries()) {\n expect(content.length, `${slug}: suspiciously short skill file`)\n .toBeGreaterThan(5000);\n }\n});\n```\n\n资料来源：[mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n\n## 发布与自动化\n\n### 发布流程\n\n1. 合并 PR 到 `main` 分支\n2. 进入 GitHub Actions → **Release** 工作流\n3. 点击 \"Run workflow\"\n4. 选择版本类型：`patch` / `minor` / `major`\n\n### CI/CD 流水线\n\n| 组件 | 功能 |\n|------|------|\n| `ci.yml` | 构建 + 测试（每次 push/PR） |\n| `release.yml` | 版本发布、npm 包发布（通过 OIDC） |\n\n资料来源：[skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n## 章节别名系统\n\nMCP 服务器支持灵活的章节查询，使用别名快速定位内容：\n\n| 别名 | 对应章节 |\n|------|----------|\n| `auth` / `authentication` | Authentication & permissions |\n| `rate-limits` / `rate_limits` / `ratelimits` / `reliability` | Reliability: rate limits, retries, idempotency |\n| `errors` / `error-handling` | Error handling & troubleshooting |\n| `recipes` | Common workflows |\n| `pagination` | Pagination |\n| `webhooks` | Webhooks |\n| `overview` | Overview |\n| `fields` | Data model: entities & fields |\n\n资料来源：[mcp-server/src/index.ts:60-80](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n## 使用方式\n\n### MCP 服务器安装\n\n```bash\n# 临时使用\nnpx -y clawskills-mcp\n\n# 永久安装\nnpm install -g clawskills-mcp\n```\n\n### Claude Desktop 配置\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n\n\n## MCP 服务器架构\n\n### 相关页面\n\n相关主题：[MCP 工具接口](#page-mcp-tools), [项目结构](#page-project-structure)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)\n- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n \n\n# MCP 服务器架构\n\n## 1. 概述\n\n`clawskills-mcp` 是一个基于 **Model Context Protocol (MCP)** 的服务器实现，用于将 [ClawSkills](https://github.com/Shanksg/clawskills) 项目中的 API 集成技能文档以结构化的方式暴露给 AI agents。\n\n### 1.1 核心定位\n\n该 MCP 服务器充当 AI 代理与外部 API 集成文档之间的桥梁，使 AI 工具（如 Claude Desktop、Claude Code）能够动态获取 14 个工具的认证流程、速率限制、错误处理和工作流配方等关键信息。资料来源：[mcp-server/README.md:1-10]()\n\n### 1.2 解决的问题\n\n在 AI 编码助手执行跨平台集成任务时，传统的静态提示词方式难以保持 API 文档的时效性。MCP 服务器通过以下方式解决此问题：\n\n- 提供动态查询接口，实时获取最新的 API 技能文档\n- 支持全文检索，快速定位特定 API 端点或错误处理方案\n- 解耦文档维护与 AI 推理逻辑，便于独立更新 API 文档\n\n## 2. 系统架构\n\n### 2.1 架构分层\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n A[Claude Desktop]\n B[Claude Code]\n C[其他 MCP 客户端]\n end\n \n subgraph \"MCP 协议层\"\n D[MCP 协议处理器]\n end\n \n subgraph \"clawskills-mcp 服务器\"\n E[工具路由]\n F[文档加载器]\n G[全文索引]\n end\n \n subgraph \"数据层\"\n H[skills/\\*.md 技能文档]\n I[playbooks/\\*.md 工作流文档]\n J[skills/INDEX.md 索引]\n end\n \n A --> D\n B --> D\n C --> D\n D --> E\n E --> F\n E --> G\n F --> H\n F --> I\n G --> J\n```\n\n### 2.2 核心组件\n\n| 组件 | 职责 | 文件位置 |\n|------|------|----------|\n| MCP 协议处理器 | 解析客户端请求，序列化和反序列化消息 | `mcp-server/src/` |\n| 工具路由 | 根据工具名称分发请求到对应处理器 | `mcp-server/src/index.ts` |\n| 文档加载器 | 读取和解析 Markdown 格式的技能文档 | `mcp-server/src/` |\n| 全文索引 | 建立和维护文档内容的搜索索引 | `mcp-server/src/` |\n\n## 3. 安装与部署\n\n### 3.1 环境要求\n\n| 要求 | 规格 |\n|------|------|\n| Node.js | >= 18.0.0 |\n| 包管理器 | npm |\n| 容器运行时 | Docker（可选） |\n\n资料来源：[mcp-server/package.json]()\n\n### 3.2 安装方式对比\n\n| 方式 | 命令 | 适用场景 |\n|------|------|----------|\n| npx 即时运行 | `npx -y clawskills-mcp` | 临时使用、快速测试 |\n| 全局安装 | `npm install -g clawskills-mcp` | 长期使用、命令行调用 |\n| Docker 容器 | `docker build -t clawskills-mcp -f mcp-server/Dockerfile .` | 生产环境隔离部署 |\n\n资料来源：[mcp-server/README.md:27-42]()\n\n### 3.3 Docker 部署流程\n\n```bash\n# 1. 从仓库根目录构建镜像\ndocker build -t clawskills-mcp -f mcp-server/Dockerfile .\n\n# 2. 运行容器\ndocker run --rm -i clawskills-mcp\n```\n\nDocker 方式确保了与宿主机环境的隔离，适合在生产环境中部署。\n\n## 4. 客户端配置\n\n### 4.1 Claude Desktop 配置\n\n**配置文件路径：**\n\n| 操作系统 | 路径 |\n|----------|------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n\n**配置结构：**\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[mcp-server/README.md:14-21]()\n\n### 4.2 Claude Code 配置\n\n| 作用域 | 配置文件位置 |\n|--------|--------------|\n| 项目级别 | `.claude/settings.json` |\n| 全局级别 | `~/.claude/settings.json` |\n\n配置格式与 Claude Desktop 相同，均使用 `mcpServers` 配置块。\n\n## 5. 工具 API\n\nMCP 服务器暴露以下四个核心工具：\n\n### 5.1 工具总览\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `list_skills` | 列出所有可用的技能文档 slug 及其描述 |\n| `get_skill` | 获取完整的技能文档或指定章节内容 |\n| `search_skills` | 在所有技能文档中执行全文搜索 |\n| `list_playbooks` | 列出可用的跨工具工作流文档 |\n\n资料来源：[mcp-server/README.md:44-49]()\n\n### 5.2 list_skills\n\n列出所有已注册的 API 集成技能。\n\n**返回结构：**\n\n```json\n{\n \"skills\": [\n {\n \"slug\": \"jira\",\n \"description\": \"Jira Cloud API integration guide\"\n },\n {\n \"slug\": \"slack\",\n \"description\": \"Slack Web API and Events API integration\"\n }\n ]\n}\n```\n\n### 5.3 get_skill\n\n获取指定技能文档的完整内容或特定部分。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `slug` | string | 是 | 技能文档标识符 |\n| `section` | string | 否 | 指定章节名称（如 `auth`、`rate-limits`） |\n\n**section 参数可选值：**\n\n| 章节标识 | 对应内容 |\n|----------|----------|\n| `auth` | 认证方式与权限配置 |\n| `rate-limits` | API 速率限制与重试策略 |\n| `errors` | 错误码与故障排查 |\n| `recipes` | 常见工作流配方 |\n\n资料来源：[mcp-server/README.md:44-49]()\n\n### 5.4 search_skills\n\n跨所有技能文档执行全文检索。\n\n**使用场景：**\n- 查找特定错误码的处理方案\n- 搜索某个 API 端点的使用方法\n- 发现所有涉及某项权限的文档\n\n### 5.5 list_playbooks\n\n列出跨工具自动化工作流文档。\n\n**当前支持的 Playbook：**\n\n| Playbook | 功能描述 |\n|----------|----------|\n| `slack-jira-incident` | Slack 消息触发 Jira 事件创建的自动化流程 |\n\n资料来源：[playbooks/slack-jira-incident.md]()\n\n## 6. 数据流与请求处理\n\n### 6.1 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant C as Claude 客户端\n participant M as MCP 服务器\n participant D as 文档系统\n participant I as 索引系统\n\n C->>M: MCP 请求 (工具名 + 参数)\n M->>M: 解析请求 JSON\n alt list_skills / list_playbooks\n M->>D: 加载索引文件\n D-->>M: 返回项目列表\n else get_skill\n M->>D: 定位技能文档\n D-->>M: 返回文档内容\n alt 指定 section\n M->>M: 提取章节内容\n end\n else search_skills\n M->>I: 执行全文搜索\n I-->>M: 返回匹配结果\n end\n M-->>C: 返回结果 JSON\n```\n\n### 6.2 技能文档结构\n\n每个技能文档（`skills//skill.md`）遵循统一的 11 节结构：\n\n| 章节 | 内容 |\n|------|------|\n| 头部元数据 | API 版本、最后验证日期 |\n| 认证与权限 | OAuth、PAT、API Key 等认证方式 |\n| 基础端点 | 核心 API 端点说明 |\n| 常见工作流 | 5-12 个可复制的配方 |\n| 速率限制 | 请求限额与复杂度计算 |\n| 错误处理 | 错误码与故障排查 |\n| Webhook 配置 | 事件订阅与签名验证 |\n| 批量操作 | 大数据量处理模式 |\n| 安全与合规 | 隐私保护建议 |\n\n资料来源：[skills/notion/skill.md](), [skills/figma/skill.md]()\n\n## 7. 支持的 API 集成\n\n### 7.1 技能库覆盖\n\n当前 ClawSkills 包含 **14 个工具**的完整 API 集成文档：\n\n| 工具 | 主要功能 |\n|------|----------|\n| Monday.com | 项目管理、看板操作 |\n| Salesforce | CRM 自动化 |\n| Jira | 敏捷项目管理、缺陷追踪 |\n| Dynamics 365 | 企业资源规划 |\n| HubSpot | 营销自动化 |\n| ServiceNow | IT 服务管理 |\n| Zendesk | 客户支持 |\n| Asana | 团队协作 |\n| GitHub | 代码托管与 CI/CD |\n| Figma | 设计协作 |\n| Slack | 团队通讯 |\n| Stripe | 支付处理 |\n| Notion | 知识管理 |\n| Linear | 开发者项目管理 |\n\n资料来源：[mcp-server/README.md:4-7]()\n\n### 7.2 跨工具编排\n\nPhase 5（跨工具编排）处于规划阶段，计划实现多系统联动工作流，例如：\n\n```mermaid\ngraph LR\n A[Slack 告警] --> B{事件分类}\n B -->|安全事件| C[创建 Jira Bug]\n B -->|客户投诉| D[创建 Zendesk 工单]\n C --> E[通知 Slack 频道]\n D --> E\n```\n\n## 8. 错误处理与调试\n\n### 8.1 常见配置错误\n\n| 症状 | 原因 | 解决方案 |\n|------|------|----------|\n| MCP 服务器未启动 | npx 缓存问题 | 添加 `-y` 参数强制重新下载 |\n| 工具调用超时 | 网络问题或文档过大 | 检查网络连接 |\n| 搜索无结果 | 索引未更新 | 确认文档已正确放置在 `skills/` 目录 |\n\n### 8.2 日志记录\n\nMCP 服务器应在 DEBUG 模式下记录以下信息：\n\n| 日志级别 | 记录内容 |\n|----------|----------|\n| INFO | 工具调用、文档加载成功 |\n| WARN | 部分文档缺失、搜索结果为空 |\n| ERROR | MCP 协议解析失败、文件系统错误 |\n\n## 9. 安全考虑\n\n### 9.1 敏感信息处理\n\n| 信息类型 | 处理建议 |\n|----------|----------|\n| API Token | 不记录在日志中 |\n| 用户数据 | 脱敏处理后再输出 |\n| 错误详情 | 仅返回给授权客户端 |\n\n### 9.2 权限控制\n\nMCP 服务器本身不实现额外的访问控制，权限管理依赖于：\n- Claude 客户端的认证机制\n- 操作系统层面的文件系统权限\n- Docker 容器的网络隔离策略\n\n## 10. 维护与更新\n\n### 10.1 文档更新流程\n\n```mermaid\ngraph LR\n A[更新 skill.md] --> B[添加 Last validated 日期]\n B --> C[更新 skills/INDEX.md]\n C --> D[提交 PR]\n D --> E[CI 验证]\n E --> F[合并到 main]\n F --> G[自动发布新版本]\n```\n\n### 10.2 CI/CD 自动化\n\n| 阶段 | 工具 | 验证内容 |\n|------|------|----------|\n| 构建 | GitHub Actions | 依赖安装、类型检查 |\n| 测试 | Vitest | 单元测试 + 文档结构验证 |\n| 发布 | release.yml | 版本号递增、npm 发布 |\n\n资料来源：[skills/ROADMAP.md]()\n\n## 11. 扩展指南\n\n### 11.1 添加新技能\n\n1. 创建分支：`git checkout -b skill/`\n2. 遵循模板结构创建 `skill.md`，确保包含全部 11 个章节\n3. 验证所有端点、速率限制和认证流程\n4. 更新 `skills/INDEX.md` 和 `README.md`\n5. 提交 PR 触发 CI 验证\n\n### 11.2 添加新工具至 MCP 服务器\n\n在 `mcp-server/src/index.ts` 中注册新的工具处理器：\n\n```typescript\nimport { getSkill, searchSkills } from './handlers';\n\n// 新增工具注册\nserver.registerTool('get_skill', getSkill);\nserver.registerTool('search_skills', searchSkills);\n```\n\n## 12. 参考资料\n\n| 资料 | 链接 |\n|------|------|\n| GitHub 仓库 | https://github.com/Shanksg/clawskills |\n| MCP 服务器源码 | `mcp-server/src/index.ts` |\n| npm 包 | `clawskills-mcp` |\n| 技能索引 | `skills/INDEX.md` |\n\n---\n\n\n\n## MCP 工具接口\n\n### 相关页面\n\n相关主题：[MCP 服务器架构](#page-mcp-server-architecture), [技能文档结构](#page-skill-anatomy)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n \n\n# MCP 工具接口\n\n## 概述\n\nMCP（Model Context Protocol）工具接口是 clawskills 项目为 AI 助手提供的标准化工具集，允许 Claude 等 AI 工具直接调用技能文档库中的内容。通过 MCP 协议，AI 可以在对话过程中实时获取各种第三方服务的集成指南、API 文档和工作流配方。\n\nMCP 工具接口是 clawskills 项目与 AI 运行时之间的桥梁，提供了三大核心能力：\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `list_skills` | 列出所有可用的技能文档 |\n| `get_skill` | 获取完整技能文档或特定章节 |\n| `search_skills` | 全文本搜索所有技能文档 |\n\n资料来源：[README.md:1-100]()\n\n## 架构设计\n\n### MCP 服务器角色\n\nclawskills 的 MCP 服务器封装了对技能文档库的访问逻辑，作为中间层将 AI 的自然语言请求转换为结构化的文档查询。其核心职责包括：\n\n1. **技能发现** — 维护技能索引，支持按名称或分类列出所有可用工具\n2. **内容检索** — 按需加载完整的技能文档或指定章节\n3. **全文搜索** — 跨所有技能文档执行关键词匹配\n\n```mermaid\ngraph TD\n A[Claude AI] -->|MCP Protocol| B[clawskills-mcp Server]\n B --> C{请求类型}\n C -->|list_skills| D[skills/INDEX.md]\n C -->|get_skill| E[skills/{tool}/skill.md]\n C -->|search_skills| F[全文索引]\n D --> G[技能列表响应]\n E --> H[完整文档/章节响应]\n F --> I[搜索结果响应]\n G --> A\n H --> A\n I --> A\n```\n\n### 工具与技能的映射关系\n\nMCP 工具与底层技能文档的对应关系如下：\n\n| MCP 工具 | 底层资源 | 返回内容 |\n|---------|---------|---------|\n| `list_skills` | `skills/INDEX.md` | 所有技能的索引列表 |\n| `get_skill` | `skills/{tool}/skill.md` | 指定工具的完整文档 |\n| `search_skills` | 所有 `skill.md` 文件 | 匹配的技能文档片段 |\n\n资料来源：[README.md:80-90]()\n\n## 安装与配置\n\n### 临时运行方式\n\n使用 npx 直接运行，无需本地安装：\n\n```bash\nnpx -y clawskills-mcp\n```\n\n### 全局安装方式\n\n将 MCP 服务器安装为全局 npm 包：\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n### Claude Desktop 配置\n\n在 Claude Desktop 的配置文件中添加 MCP 服务器连接：\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n### Claude Code 配置\n\n对于 Claude Code 项目，可在 `.claude/CLAUDE.md` 中配置为项目级指令：\n\n```markdown\n# Integration Skills\n\n当编写与以下工具集成的代码时，始终在编写代码前阅读对应的技能文档：\n\n- Monday.com → @skills/monday/skill.md\n- Salesforce → @skills/salesforce/skill.md\n- Jira → @skills/jira/skill.md\n- HubSpot → @skills/hubspot/skill.md\n- Zendesk → @skills/zendesk/skill.md\n- GitHub → @skills/github/skill.md\n- Figma → @skills/figma/skill.md\n- Slack → @skills/slack/skill.md\n- Stripe → @skills/stripe/skill.md\n- Notion → @skills/notion/skill.md\n- Linear → @skills/linear/skill.md\n```\n\n资料来源：[README.md:95-115]()\n\n## 三大核心工具详解\n\n### list_skills — 技能列表\n\n列出所有已注册的技能文档，AI 可据此了解项目支持的集成范围。\n\n**使用场景：**\n- 探索项目能力边界\n- 在不确定具体工具时浏览可用选项\n- 验证特定工具是否在支持列表中\n\n### get_skill — 技能获取\n\n获取指定技能的完整文档或特定章节。支持的章节筛选包括：\n\n| 章节标识 | 内容范围 |\n|---------|---------|\n| `auth` | 认证与授权流程 |\n| `rate-limits` | 速率限制说明 |\n| `recipes` | 工作流配方 |\n| `errors` | 错误代码与处理 |\n\n**使用场景：**\n- 在开始集成前获取完整认证指南\n- 调试时查阅特定错误代码含义\n- 提取特定工作流配方\n\n### search_skills — 全文搜索\n\n跨所有技能文档执行关键词搜索，返回匹配结果。\n\n**使用场景：**\n- 快速定位包含特定 API 端点的技能\n- 搜索特定错误消息的解决方案\n- 查找包含特定认证机制的文档\n\n## 支持的工具生态\n\n当前 MCP 接口覆盖以下 14 种第三方工具：\n\n| 类别 | 支持的工具 |\n|------|-----------|\n| 项目管理 | Jira, Asana, Monday.com, Linear, Notion |\n| 客户关系 | Salesforce, HubSpot, Zendesk |\n| 开发协作 | GitHub, Figma |\n| 通信 | Slack |\n| 支付 | Stripe |\n| 企业系统 | Dynamics 365, ServiceNow |\n\n资料来源：[skills/ROADMAP.md:1-50]()\n\n## 开发阶段与路线图\n\n根据项目路线图，MCP 工具接口已实现以下阶段：\n\n| 阶段 | 内容 | 状态 |\n|------|------|------|\n| Phase 1 — 基础 | 认证流、基本 CRUD、重试模式 | ✅ 完成 |\n| Phase 2 — 高频工作流 | 每个工具 6-12 个配方 | ✅ 完成 |\n| Phase 3 — 事件驱动 | Webhook 设置、签名验证、事件处理 | ✅ 完成 |\n| Phase 4 — 批量操作 | 批量 API、大容量模式 | ⚠️ 部分完成 |\n| Phase 5 — 跨工具编排 | 跨 2+ 工具的多系统配方 | ❌ 未开始 |\n\n资料来源：[skills/ROADMAP.md:50-80]()\n\n### 未来发展方向\n\n**优先级 1 — 新鲜度与准确性管道**\n\n核心 14 工具库建立后的下一步是确保文档随供应商 API 变化保持准确：\n\n- **Phase A** — 建立文档变更检测机制\n- **Phase B** — 自动化验证与测试\n- **Phase C** — 社区驱动的更新流程\n\n资料来源：[skills/ROADMAP.md:80-100]()\n\n## 最佳实践\n\n### 在提示词中引用技能文档\n\n| 目标 | 提示词结构 |\n|------|-----------|\n| 引用特定章节 | 粘贴目标章节内容，明确说明用途 |\n| 完整技能作为上下文 | 将技能文档加载为系统提示词的一部分 |\n\n**示例：**\n\n```\n[粘贴 skills/salesforce/skill.md 中的\"Authentication & permissions\"章节]\n\n基于以上内容，编写一个将 JWT 兑换为访问令牌并缓存至过期前 5 分钟的 Python 函数。\n```\n\n### 遵循文档规范\n\n使用 MCP 工具获取的技能文档时，应严格遵循其中的：\n- 认证模式\n- 速率限制处理\n- 错误代码处理\n- API 版本标头要求\n\n## 持续集成与发布\n\n项目维护以下自动化流程：\n\n| 组件 | 功能 | 状态 |\n|------|------|------|\n| `ci.yml` | 每次 push/PR 触发构建与测试 | ✅ 运行中 |\n| `release.yml` | 手动触发版本发布、npm 发布 | ✅ 运行中 |\n| 测试套件 | Vitest 单元测试 + 真实技能验证 | ✅ 运行中 |\n\n版本号遵循语义化版本（patch/minor/major），发布流程通过 GitHub Actions 手动触发。\n\n资料来源：[skills/ROADMAP.md:20-30]()\n\n## 相关资源\n\n- NPM 包：`clawskills-mcp`\n- MCP 协议版本：Model Context Protocol 标准\n- 技能文档路径：`skills/{toolname}/skill.md`\n- 索引文件：`skills/INDEX.md`\n\n---\n\n\n\n## 技能文档结构\n\n### 相关页面\n\n相关主题：[技能目录总览](#page-skill-catalog), [MCP 工具接口](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)\n- [skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n- [skills/jira/skill.md](https://github.com/Shanksg/Shanksg/clawskills/blob/main/skills/jira/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# 技能文档结构\n\n## 概述\n\n技能文档（Skill Documentation）是 clawskills 项目的核心资产，为 14 种主流工具和平台提供标准化的 API 集成指南。这些文档采用统一模板编写，包含身份验证、速率限制、常见工作流、错误处理等 11 个必填章节，确保 AI 代理能够准确、可靠地与外部系统交互。\n\n技能文档的主要作用包括：\n\n- 为 AI 代理提供可信赖的集成参考\n- 标准化跨平台的 API 调用模式\n- 降低集成错误率和开发时间\n- 支持 RAG（检索增强生成）流程\n\n资料来源：[README.md:1-20](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 文档模板结构\n\n### 必填章节清单\n\n每个技能文档必须包含以下 11 个章节，CI 测试会验证所有章节的完整性：\n\n| 章节编号 | 章节名称 | 说明 |\n|---------|---------|------|\n| 1 | 概述 | 工具简介、API 版本、基础 URL |\n| 2 | 身份验证与权限 | 认证方式、OAuth 流程、令牌管理 |\n| 3 | 速率限制 | 请求配额、重试策略、复杂度过载 |\n| 4 | 核心 API 端点 | 主要接口列表及参数说明 |\n| 5 | 常见工作流（Recipes） | 典型使用场景的代码示例 |\n| 6 | Webhook 配置 | 事件订阅、签名验证、负载结构 |\n| 7 | 错误处理 | 错误代码分类、异常处理模式 |\n| 8 | 安全与隐私 | 最佳实践、合规要求 |\n| 9 | 相关资源 | 官方文档链接、示例代码 |\n| 10 | 变更日志 | 版本历史、breaking changes |\n| 11 | 维护指南 | 文档更新流程、验证要求 |\n\n资料来源：[mcp-server/src/index.test.ts:1-30](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n\n### 文档质量标准\n\n```\n┌─────────────────────────────────────────────┐\n│ 技能文档质量检查 │\n├─────────────────────────────────────────────┤\n│ ✓ 所有 11 个必填章节完整 │\n│ ✓ 摘要行非空 │\n│ ✓ 文件大小 ≥ 5KB（内容充实度） │\n│ ✓ 端点、速率限制、认证流程经官方文档验证 │\n│ ✓ 包含 Last validated 日期 │\n│ ✓ 链接到官方 Sources 章节 │\n└─────────────────────────────────────────────┘\n```\n\n资料来源：[README.md:25-35](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 技能库组织架构\n\n### 目录结构\n\n```\nclawskills/\n├── skills/\n│ ├── INDEX.md # 技能总索引\n│ ├── ROADMAP.md # 路线图和开发阶段\n│ ├── asana/\n│ │ └── skill.md\n│ ├── dynamics365/\n│ │ └── skill.md\n│ ├── figma/\n│ │ └── skill.md\n│ ├── github/\n│ │ └── skill.md\n│ ├── hubspot/\n│ │ └── skill.md\n│ ├── jira/\n│ │ └── skill.md\n│ ├── linear/\n│ │ └── skill.md\n│ ├── monday/\n│ │ └── skill.md\n│ ├── notion/\n│ │ └── skill.md\n│ ├── salesforce/\n│ │ └── skill.md\n│ ├── servicenow/\n│ │ └── skill.md\n│ ├── slack/\n│ │ └── skill.md\n│ ├── stripe/\n│ │ └── skill.md\n│ └── zendesk/\n│ └── skill.md\n├── playbooks/ # 跨工具编排手册\n│ └── slack-jira-incident.md\n└── mcp-server/ # MCP 服务端实现\n```\n\n资料来源：[skills/ROADMAP.md:1-50](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n### 覆盖的工具\n\n| 类别 | 工具 | 协议类型 |\n|------|------|----------|\n| 项目管理 | Jira, Linear, Monday.com, Asana | REST API / GraphQL |\n| CRM/销售 | Salesforce, HubSpot, Dynamics 365 | REST API |\n| 客服 | Zendesk, ServiceNow | REST API |\n| 开发工具 | GitHub | REST API |\n| 设计协作 | Figma | REST API |\n| 消息 | Slack | Web API / WebSocket |\n| 支付 | Stripe | REST API |\n| 知识管理 | Notion | REST API |\n\n---\n\n## 章节内容详解\n\n### 1. 身份验证与权限（Authentication & Permissions）\n\n此章节描述与工具交互所需的认证机制，包括 API Key、OAuth 2.0、JWT 等方式。\n\n**典型认证模式：**\n\n| 认证方式 | 适用场景 | Token 位置 |\n|---------|---------|-----------|\n| API Key / PAT | 服务器到服务器集成 | Header: `Authorization: Bearer xxx` |\n| OAuth 2.0 | 用户授权应用 | 先获取 code，再兑换 access_token |\n| JWT | 服务账户 | 请求体或专用端点 |\n| HMAC 签名 | Webhook 验证 | 请求头特定字段 |\n\n**Figma 示例：**\n```bash\n# Personal Access Token\ncurl https://api.figma.com/v1/me \\\n -H \"X-Figma-Token: YOUR_PAT\"\n```\n\n**Linear 示例：**\n```bash\ncurl -X POST https://api.linear.app/oauth/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=refresh_token&refresh_token=&client_id=&client_secret=\"\n```\n\n资料来源：[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)\n\n### 2. 速率限制（Rate Limits）\n\n每个技能文档记录平台特定的速率限制策略。\n\n**速率限制信息表结构：**\n\n| 维度 | 说明 |\n|------|------|\n| 请求配额 | 每小时/每分钟允许的请求数 |\n| 复杂度过载 | 基于查询复杂度的积分限制 |\n| 突发限制 | 短期峰值容忍 |\n| 响应头 | 返回剩余配额、重试时间 |\n\n**Linear 速率限制示例：**\n\n| 认证类型 | 请求/小时 | 复杂度积分/小时 | 单次查询最大积分 |\n|---------|----------|----------------|-----------------|\n| API key | 5,000 | 250,000 | 10,000 |\n| OAuth app | 5,000 | 2,000,000 | 10,000 |\n| 未认证 | 60 | 10,000 | 10,000 |\n\n**响应头字段：**\n\n| Header | 描述 |\n|--------|------|\n| `X-RateLimit-Requests-Limit` | 时间窗口内允许的总请求数 |\n| `X-RateLimit-Complexity-Limit` | 复杂度积分上限 |\n| `Retry-After` | 需要等待的秒数 |\n\n资料来源：[skills/linear/skill.md:50-70](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n\n### 3. 常见工作流（Recipes）\n\nRecipes 提供针对典型使用场景的完整代码示例，通常包含：\n\n- 场景描述\n- 所需权限范围\n- 完整可运行的代码片段\n- 错误处理模式\n\n**工作流类型分类：**\n\n```mermaid\ngraph TD\n A[Recipes 工作流] --> B[CRUD 操作]\n A --> C[查询与过滤]\n A --> D[Webhook 配置]\n A --> E[批量操作]\n A --> F[跨系统编排]\n \n B --> B1[创建资源]\n B --> B2[读取详情]\n B --> B3[更新字段]\n B --> B4[删除归档]\n```\n\n**Jira Recipe 示例：**\n```bash\ncurl -s -X PUT \"$BASE/rest/api/3/issue/PROJ-42\" \\\n -H \"Authorization: $AUTH\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"fields\": {\n \"labels\": [\"production\", \"urgent\"]\n }\n }'\n```\n\n资料来源：[skills/jira/skill.md:80-100](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)\n\n### 4. Webhook 配置\n\nWebhook 章节描述事件订阅机制、签名验证和负载结构。\n\n**Webhook 组件：**\n\n| 组件 | 描述 |\n|------|------|\n| 端点注册 | 创建 webhook 的 API 调用 |\n| 事件类型 | 可订阅的事件列表 |\n| 签名验证 | HMAC/SHA256 验证方法 |\n| 负载结构 | 请求体字段说明 |\n\n**Slack Webhook 安全配置：**\n```python\nimport hmac, hashlib, time\n\ndef verify_slack_signature(\n signing_secret: str,\n body: bytes,\n timestamp: str,\n signature: str\n) -> bool:\n base = f\"v0:{timestamp}:{body.decode()}\"\n expected = \"v0=\" + hmac.new(\n signing_secret.encode(),\n base.encode(),\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(expected, signature)\n```\n\n**Jira Webhook 负载示例：**\n```json\n{\n \"timestamp\": 1708357200000,\n \"webhookEvent\": \"jira:issue_updated\",\n \"user\": { \"accountId\": \"5b10a...\" },\n \"issue\": {\n \"id\": \"10023\",\n \"key\": \"PROJ-42\",\n \"fields\": { \"status\": {}, \"summary\": \"...\" }\n },\n \"changelog\": {\n \"items\": [\n { \"field\": \"status\", \"fromString\": \"In Progress\", \"toString\": \"Done\" }\n ]\n }\n}\n```\n\n资料来源：[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)\n\n### 5. 错误处理\n\n错误处理章节列出 API 返回的错误代码和处理策略。\n\n**错误响应模式：**\n\n| 错误类型 | HTTP 状态码 | 处理策略 |\n|---------|------------|---------|\n| 认证失败 | 401 | 检查 token 有效性，刷新或重新授权 |\n| 权限不足 | 403 | 确认应用具备所需 scopes |\n| 资源不存在 | 404 | 验证 ID/键值是否正确 |\n| 速率限制 | 429 | 读取 Retry-After，等待后重试 |\n| 服务器错误 | 500-503 | 指数退避重试 |\n\n**常见错误代码表：**\n\n| 工具 | 错误代码 | 含义 |\n|------|---------|------|\n| Linear | `RATELIMITED` | 请求超出速率限制 |\n| Linear | `ENTITY_NOT_FOUND` | 指定实体不存在 |\n| Slack | `cant_update_message` | 无权修改该消息 |\n| Jira | 多种 | 见 Jira 官方错误文档 |\n\n资料来源：[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)\n\n---\n\n## Playbooks 跨工具编排\n\nPlaybooks 展示如何组合多个工具的 API 实现复杂业务流程。\n\n### 编排结构\n\n```mermaid\ngraph LR\n A[Slack 事件] -->|消息/反应| B[事件提取]\n B --> C[权限验证]\n C --> D{事件类型判断}\n D -->|incident| E[创建 Jira Issue]\n D -->|变更| F[更新现有 Issue]\n E --> G[回复 Slack 线程]\n F --> G\n G --> H[可选: 镜像状态回 Slack]\n```\n\n### 字段映射规则\n\nPlaybooks 定义工具间的数据映射关系：\n\n| Slack 字段 | Jira 字段 |\n|-----------|----------|\n| `event.channel` + `event.ts` | correlation key |\n| 消息文本（首句） | `summary` |\n| 消息全文 + 链接 | `description` |\n| 频道配置 | `priority`, `issuetype`, `project` |\n| `slack-incident` 标签 | 标签标识 |\n\n### 编排最佳实践\n\n1. **幂等性设计**：相同事件多次触发应产生相同结果\n2. **相关性检测**：创建前搜索现有 Issue 避免重复\n3. **状态同步**：可选地将目标系统状态变化同步回源系统\n4. **错误恢复**：记录失败状态，支持人工干预\n\n资料来源：[playbooks/slack-jira-incident.md:1-50](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n\n---\n\n## 开发流程与贡献规范\n\n### 添加新技能的步骤\n\n1. 创建分支：`git checkout -b skill/`\n2. 参考现有模板创建 `skill.md`\n3. 验证端点、速率限制、认证流程\n4. 在文档头部添加 `Last validated:` 日期\n5. 更新 `skills/INDEX.md` 和 `README.md`\n6. 在 `## Sources` 章节添加官方文档链接\n7. 提交 PR 触发 CI 测试\n\n### CI 测试流程\n\n```mermaid\ngraph TD\n A[提交 PR] --> B[npm test]\n B --> C{所有测试通过?}\n C -->|是| D[合并到 main]\n C -->|否| E[显示失败详情]\n E --> F[修复问题]\n F --> A\n \n B --> B1[加载所有技能]\n B1 --> B2[验证 11 个必填章节]\n B2 --> B3[验证摘要行非空]\n B3 --> B4[验证文件 ≥ 5KB]\n```\n\n资料来源：[README.md:20-40](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 版本与发布\n\n### 发布自动化\n\n发布流程通过 GitHub Actions 自动化：\n\n1. 合并代码到 `main` 分支\n2. 前往 GitHub Actions → **Release** 工作流\n3. 运行工作流，选择版本类型：\n - `patch`：补丁版本（bug 修复）\n - `minor`：次版本（新功能）\n - `major`：主版本（breaking changes）\n\n### 版本命名规范\n\n遵循语义化版本（Semantic Versioning）：\n- **Major**：`X.0.0` — 不兼容的 API 变更\n- **Minor**：`X.Y.0` — 向后兼容的新功能\n- **Patch**：`X.Y.Z` — 向后兼容的问题修复\n\n资料来源：[README.md:40-50](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 使用方式\n\n### MCP 服务集成\n\nMCP 服务器提供三个核心工具：\n\n| 工具名称 | 功能 |\n|---------|------|\n| `list_skills` | 列出所有可用的技能文档 |\n| `get_skill` | 获取完整技能或指定章节 |\n| `search_skills` | 全文本搜索所有技能 |\n\n**安装命令：**\n```bash\nnpx -y clawskills-mcp\n```\n\n**Claude Desktop 配置：**\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n### AI 代理集成模式\n\n**模式 1 — 参考特定章节：**\n```\n[paste \"Authentication & permissions\" section]\n\n使用上述内容，写一个 Python 函数交换 JWT 获取 access token 并缓存\n```\n\n**模式 2 — 完整技能作为系统上下文：**\n加载技能文档作为系统提示词的一部分，由 LLM 在运行时参考。\n\n**模式 3 — RAG 知识库：**\n将技能文档分割后索引到向量数据库，供检索增强生成使用。\n\n```python\nfrom langchain.text_splitter import MarkdownHeaderTextSplitter\n\nsplitter = MarkdownHeaderTextSplitter(\n headers_to_split_on=[(\"##\", \"section\"), (\"###\", \"subsection\")]\n)\n```\n\n资料来源：[README.md:50-100](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 维护与更新\n\n### 文档新鲜度\n\n技能文档需要定期验证以保持准确性：\n\n| 验证项目 | 频率 | 负责人 |\n|---------|------|-------|\n| API 端点可用性 | 每季度 | 技能维护者 |\n| 速率限制更新 | 发现变更时 | 提交者 |\n| 认证流程变化 | 发现变更时 | 提交者 |\n| 新功能添加 | 持续 | 社区贡献者 |\n\n### 验证标记\n\n文档头部应包含 `Last validated:` 日期：\n\n```markdown\n---\nLast validated: 2025-11-15\n---\n```\n\n### 问题报告\n\n发现文档错误时：\n\n1. 检查官方 API 文档确认正确行为\n2. 创建 Issue 描述问题\n3. 提交 PR 修复并更新验证日期\n4. 关联相关 Issue\n\n资料来源：[skills/ROADMAP.md:50-80](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n---\n\n## 路线图与未来方向\n\n### 当前阶段状态\n\n| 阶段 | 主题 | 状态 |\n|------|------|------|\n| Phase 1 | 基础（认证 + 核心 CRUD） | ✅ 完成 |\n| Phase 2 | 高频工作流（6-12 条 Recipes） | ✅ 完成 |\n| Phase 3 | 事件驱动与实时 | ✅ 完成 |\n| Phase 4 | 批量与高级操作 | ⚠️ 部分完成 |\n| Phase 5 | 跨工具编排 | ❌ 未开始 |\n\n### 下一阶段重点\n\n**优先级 1 — 新鲜度和准确性流水线**\n- 建立 API 变更监控系统\n- 自动验证文档准确性\n- 社区驱动的更新机制\n\n**优先级 2 — 跨工具编排扩展**\n- 更多 Playbooks 示例\n- 标准化编排模式库\n- 错误恢复和补偿策略\n\n资料来源：[skills/ROADMAP.md:80-120](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n---\n\n## 附录\n\n### 快速参考：技能文档元数据\n\n| 属性 | 要求 |\n|------|------|\n| 文件命名 | `skill.md` |\n| 目录位置 | `skills//` |\n| 最小大小 | 5 KB |\n| 章节数量 | 11 个必填 |\n| 语言 | Markdown |\n| 引用格式 | 指向官方文档的链接 |\n\n---\n\n\n\n## 技能目录总览\n\n### 相关页面\n\n相关主题：[技能文档结构](#page-skill-anatomy), [跨工具工作流剧本](#page-playbooks)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n- [skills/salesforce/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/salesforce/skill.md)\n- [skills/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)\n- [skills/zendesk/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/zendesk/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n- [skills/stripe/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/stripe/skill.md)\n- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)\n- [skills/jira/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)\n- [skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/servicenow/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/servicenow/skill.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# 技能目录总览\n\n## 项目概述\n\n**Clawskills** 是一个开源的集成技能库项目，旨在为 AI 工具（特别是 Claude Code 和 Claude Desktop）提供标准化的第三方服务集成文档。该项目将常见的 SaaS 平台和开发工具的 API 使用方法、认证流程、速率限制和最佳实践整理成结构化的技能文档，使 AI 助手能够准确、高效地帮助用户完成与这些工具的集成工作。资料来源：[README.md:1]()\n\n该技能库目前涵盖 **14 个主流工具**，包括项目管理、设计协作、CRM、客服、财务等多个领域的解决方案。每个技能文档都遵循统一的 11 部分结构，确保一致性和可维护性。资料来源：[README.md:15]()\n\n## 架构设计\n\n### 技能库整体架构\n\n```mermaid\ngraph TD\n A[clawskills 仓库] --> B[技能文档层 skills/]\n A --> C[剧本目录 playbooks/]\n A --> D[MCP 服务器 mcp-server/]\n B --> E[14 个工具技能文档]\n B --> F[INDEX.md 索引]\n B --> G[ROADMAP.md 路线图]\n C --> H[跨工具工作流剧本]\n D --> I[list_skills 工具]\n D --> J[get_skill 工具]\n D --> K[search_skills 工具]\n```\n\n### MCP 服务器集成架构\n\nMCP 服务器作为 AI 工具与技能库之间的桥梁，提供三个核心工具：资料来源：[README.md:80-85]()\n\n```mermaid\nsequenceDiagram\n participant AI as AI 助手\n participant MCP as MCP 服务器\n participant FS as 文件系统\n\n AI->>MCP: list_skills\n MCP->>FS: 读取 skills/ 目录\n FS-->>MCP: 技能列表\n MCP-->>AI: 返回技能索引\n\n AI->>MCP: get_skill(\"jira\", \"auth\")\n MCP->>FS: 读取 skills/jira/skill.md\n FS-->>MCP: 完整文档内容\n MCP-->>AI: 返回认证章节\n\n AI->>MCP: search_skills(\"webhook\")\n MCP->>FS: 全文搜索所有技能\n FS-->>MCP: 匹配结果\n MCP-->>AI: 返回搜索结果\n```\n\n## 技能文档结构\n\n### 标准章节模板\n\n每个技能文档必须包含以下 11 个标准章节，这是项目质量要求的一部分：资料来源：[README.md:22]()\n\n| 章节序号 | 章节名称 | 说明 |\n|---------|---------|------|\n| 1 | 基本信息 | 工具简介、API 基础 URL、版本 |\n| 2 | 认证与权限 | 认证方式、OAuth 流程、权限范围 |\n| 3 | 核心 API 端点 | 主要 REST 端点或 GraphQL 操作 |\n| 4 | 常见工作流 | 典型使用场景的代码示例 |\n| 5 | 速率限制与重试 | API 限制、错误处理策略 |\n| 6 | 错误代码参考 | 常见错误及解决方案 |\n| 7 | Webhook 配置 | 事件订阅、签名验证 |\n| 8 | 批量操作 | 大量数据处理模式 |\n| 9 | 数据模型 | 关键对象结构说明 |\n| 10 | 安全与合规 | 最佳实践、隐私考虑 |\n| 11 | 参考资料 | 官方文档链接 |\n\n### 文档验证机制\n\n项目通过自动化测试确保文档质量：资料来源：[mcp-server/src/index.test.ts:18-40]()\n\n```mermaid\ngraph LR\n A[提交 PR] --> B[CI 运行 npm test]\n B --> C{加载所有技能}\n C --> D{检查摘要行}\n C --> E{检查必需章节}\n C --> F{检查文件大小 ≥5KB}\n D --> G{全部通过?}\n E --> G\n F --> G\n G -->|是| H[PR 允许合并]\n G -->|否| I[CI 失败报告]\n```\n\n测试套件验证以下条件：资料来源：[mcp-server/src/index.test.ts:18-40]()\n\n- 所有 14 个已知技能都已加载\n- 每个技能文件包含非空摘要行\n- 每个技能文件包含全部必需章节\n- 每个技能文件大小至少 5KB\n\n## 支持的工具清单\n\n### 工具分类总览\n\n| 类别 | 工具列表 | 说明 |\n|------|---------|------|\n| 项目管理 | Jira, Linear, Asana, Monday.com | 任务跟踪、敏捷管理 |\n| 设计协作 | Figma | 设计文件、组件库 |\n| CRM | Salesforce, HubSpot, Dynamics 365 | 销售和客户管理 |\n| 客服支持 | Zendesk, ServiceNow | 工单和服务管理 |\n| 通信协作 | Slack | 团队消息和自动化 |\n| 财务管理 | Stripe | 支付和订阅 |\n| 知识管理 | Notion | 文档和数据库 |\n| 开发协作 | GitHub | 代码仓库和 CI/CD |\n\n### 工具认证方式对比\n\n| 工具 | 主要认证方式 | Token 格式 | OAuth 支持 |\n|------|-------------|-----------|-----------|\n| Jira | Basic Auth / API Token | — | ✅ |\n| Linear | API Key | — | ✅ |\n| Asana | Personal Access Token | `1/xxxxxxxx` | ✅ |\n| Monday.com | API Key | — | ✅ |\n| Figma | Personal Access Token | `figd_xxx` | ✅ |\n| Salesforce | OAuth 2.0 | — | ✅ |\n| HubSpot | Private App Token | `pat-xxx` | ✅ |\n| Dynamics 365 | OAuth 2.0 | — | ✅ |\n| Zendesk | API Token | `xxx` | ✅ |\n| ServiceNow | Basic Auth | — | ✅ |\n| Slack | OAuth 2.0 / Bot Token | `xoxb-xxx` | ✅ |\n| Stripe | Secret Key | `sk_xxx` | ❌ |\n| Notion | Internal Integration | `secret_xxx` | ✅ |\n| GitHub | Personal Access Token | `ghp_xxx` | ✅ |\n\n### 速率限制对比\n\n| 工具 | 认证类型 | 请求频率 | 特殊限制 |\n|------|---------|---------|---------|\n| Figma | PAT | 1,000 req/hr | 按计划分级 |\n| Linear | API Key | 5,000 req/hr | 复杂度点限制 |\n| Jira | API Token | 取决于计划 | 付费版更高 |\n| Stripe | Secret Key | 无硬限制 | 建议请求隔离 |\n| Notion | Integration | 3 req/s | 分段限制 |\n| HubSpot | Private App | 100-500 req/10s | 按端点分级 |\n\n## 跨工具工作流剧本\n\n### 剧本目录\n\n项目在 `playbooks/` 目录下维护跨工具集成的工作流剧本。资料来源：[README.md:10]()\n\n```mermaid\ngraph TD\n P[剧本目录] --> S1[Slack-Jira 事故管理]\n P --> S2[跨工具同步流程]\n P --> S3[自动化工作流]\n\n S1 --> T1[Slack 消息监听]\n S1 --> T2[Jira 问题创建]\n S1 --> T3[状态同步]\n\n T1 --> T4[事件类型识别]\n T2 --> T5[字段映射]\n T3 --> T6[回执通知]\n```\n\n### Slack-Jira 事故剧本字段映射\n\n以下是一个跨工具集成的字段映射示例：资料来源：[playbooks/slack-jira-incident.md:1-20]()\n\n| Slack 事件字段 | Jira 目标字段 | 说明 |\n|---------------|---------------|------|\n| `event.channel` + `event.ts` | Correlation Key | 用于去重的关联标识 |\n| `event.text` (首句) | `summary` | 问题摘要，截断至 120 字符 |\n| `permalink` | `description` | Slack 消息永久链接 |\n| `event.thread_ts` | 评论/附件 | 线程上下文 |\n| `slack-incident` 标签 | Label | 事故类型标记 |\n| `correlation_key` | 自定义字段 | 跨系统关联键 |\n\n## 开发贡献流程\n\n### 添加新技能的步骤\n\n项目采用标准化的分支和 PR 流程来管理技能文档的更新：资料来源：[README.md:18-30]()\n\n```mermaid\ngraph LR\n A[创建分支 git checkout -b skill/<toolname>] --> B[遵循模板结构]\n B --> C[验证端点和限制]\n C --> D[添加 Last validated 日期]\n D --> E[更新 INDEX.md 和 README.md]\n E --> F[PR 并等待 CI 通过]\n F --> G[合并到 main]\n G --> H[触发 Release 工作流]\n```\n\n### 贡献质量要求\n\n- 所有 11 个标准章节必须完整填写\n- 端点、速率限制和认证流程必须对照官方文档验证\n- `Last validated` 日期必须更新\n- 引用官方来源，禁止未经验证的声明\n- 至少包含 5 个常见工作流示例\n\n## 发布与维护机制\n\n### 自动化发布流程\n\n项目使用 GitHub Actions 实现完全自动化的发布流程：资料来源：[skills/ROADMAP.md:20-25]()\n\n```mermaid\ngraph LR\n A[合并到 main 分支] --> B[GitHub Actions]\n B --> C[运行 Release 工作流]\n C --> D[选择版本类型]\n D --> E{patch/minor/major}\n E --> F[版本号递增]\n F --> G[创建 Git Tag]\n F --> H[npm publish]\n G --> I[GitHub Release]\n```\n\n### 版本管理策略\n\n| 版本类型 | 适用场景 | 示例 |\n|---------|---------|------|\n| patch | 文档修正、链接更新 | 1.0.0 → 1.0.1 |\n| minor | 新增端点、新增章节 | 1.0.1 → 1.1.0 |\n| major | 新增工具、架构变更 | 1.1.0 → 2.0.0 |\n\n## 未来发展路线\n\n### 已完成阶段\n\n| 阶段 | 主题 | 状态 |\n|------|------|------|\n| Phase 1 | 基础（认证 + 核心 CRUD） | ✅ 全部 14 个工具 |\n| Phase 2 | 高频工作流（6-12 个示例/工具） | ✅ 全部 14 个工具 |\n| Phase 3 | 事件驱动与实时（Webhook） | ✅ 全部 14 个工具 |\n| Phase 4 | 批量与高级操作 | ⚠️ 部分完成 |\n| Phase 5 | 跨工具编排（2+ 工具联动） | ❌ 未开始 |\n\n资料来源：[skills/ROADMAP.md:30-40]()\n\n### 优先级计划\n\n**优先级 1 — 新鲜度和准确性流水线**\n\n随着 14 个核心技能库完成，下一个护城河是确保文档随供应商 API 变化保持准确。资料来源：[skills/ROADMAP.md:45-50]()\n\n计划包括：\n\n- 自动化 API 变更检测\n- 社区贡献的审查流程\n- 定期重新验证机制\n- 版本化技能文档\n\n## 在 Claude Code 中使用\n\n### 项目指令文件示例\n\n在 `.claude/CLAUDE.md` 中配置项目级指令，使 AI 始终使用这些技能文档：资料来源：[README.md:60-75]()\n\n```markdown\n# 集成技能\n\n当编写与以下工具集成的代码时，始终先阅读对应技能文档：\n\n- Monday.com → @skills/monday/skill.md\n- Salesforce → @skills/salesforce/skill.md\n- Jira → @skills/jira/skill.md\n- Dynamics 365 → @skills/dynamics365/skill.md\n- HubSpot → @skills/hubspot/skill.md\n- ServiceNow → @skills/servicenow/skill.md\n- Zendesk → @skills/zendesk/skill.md\n- Asana → @skills/asana/skill.md\n- GitHub → @skills/github/skill.md\n- Figma → @skills/figma/skill.md\n- Slack → @skills/slack/skill.md\n- Stripe → @skills/stripe/skill.md\n- Notion → @skills/notion/skill.md\n- Linear → @skills/linear/skill.md\n\n遵循文档中指定的认证模式、速率限制处理和错误代码。\n```\n\n## 总结\n\n技能目录总览展示了 Clawskills 项目的完整架构和价值主张：\n\n- **14 个主流工具**的标准化集成文档\n- **统一的 11 章节结构**确保一致性和可维护性\n- **MCP 服务器集成**使 AI 工具能够实时访问技能库\n- **自动化测试和发布**保证文档质量\n- **跨工具剧本**支持复杂业务场景\n\n该项目将持续更新以反映供应商 API 的变化，并逐步扩展跨工具编排能力。\n\n---\n\n\n\n## 跨工具工作流剧本\n\n### 相关页面\n\n相关主题：[技能目录总览](#page-skill-catalog), [贡献指南](#page-contributing)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [playbooks/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/INDEX.md)\n- [playbooks/zendesk-jira-bug-escalation.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/zendesk-jira-bug-escalation.md)\n- [playbooks/hubspot-asana-onboarding.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/hubspot-asana-onboarding.md)\n- [playbooks/salesforce-hubspot-lead-sync.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/salesforce-hubspot-lead-sync.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# 跨工具工作流剧本\n\n## 概述\n\n跨工具工作流剧本（Playbooks）是 Clawskills 项目中用于定义和编排多系统集成的核心文档。这些剧本描述了如何将两个或多个工具（如 Slack、Jira、Zendesk、HubSpot、Salesforce、Asana 等）的 API 和事件机制组合起来，实现端到端的业务流程自动化。\n\n剧本的核心价值在于提供经过验证的集成模式，涵盖身份验证、数据映射、事件处理、错误恢复等关键环节，帮助开发者快速实现跨系统的工作流编排。\n\n资料来源：[playbooks/INDEX.md:1-20]()\n\n---\n\n## 剧本架构\n\n### 剧本组成要素\n\n每个剧本通常包含以下核心组件：\n\n| 组件 | 说明 |\n|------|------|\n| 触发器（Trigger） | 启动工作流的事件来源，如消息接收、工单创建、状态变更 |\n| 源系统 | 工作流的起始工具，产生原始事件 |\n| 目标系统 | 工作流的终点，接收处理后的数据 |\n| 数据映射 | 字段对应关系和格式转换规则 |\n| 事件处理 | 对触发事件的响应逻辑 |\n| 错误处理 | 异常情况的处理策略 |\n\n资料来源：[playbooks/slack-jira-incident.md:10-15]()\n\n### 剧本类型分类\n\n根据业务场景，剧本可分为以下类型：\n\n| 类型 | 描述 | 示例 |\n|------|------|------|\n| 事件驱动型 | 响应实时事件自动触发 | Slack 消息 → Jira 工单 |\n| 同步型 | 双向数据保持一致 | Salesforce → HubSpot 线索同步 |\n| 编排型 | 多步骤复杂业务流程 | Zendesk 工单 → Jira Bug → Slack 通知 |\n\n资料来源：[playbooks/INDEX.md:1-30]()\n\n---\n\n## 剧本工作流程\n\n### 标准执行流程\n\n```mermaid\ngraph TD\n A[触发事件] --> B{事件验证}\n B -->|签名无效| C[拒绝请求]\n B -->|验证通过| D[解析事件数据]\n D --> E[数据映射与转换]\n E --> F[调用目标系统 API]\n F --> G{调用成功?}\n G -->|是| H[记录响应]\n G -->|否| I[重试/错误处理]\n H --> J[发送确认通知]\n I --> K{重试次数耗尽?}\n K -->|否| F\n K -->|是| L[告警并记录失败]\n```\n\n### 事件处理模式\n\n```mermaid\ngraph LR\n A[源系统事件] --> B[Webhook 接收端点]\n B --> C{事件类型匹配}\n C -->|issue_created| D[创建目标记录]\n C -->|issue_updated| E[更新目标记录]\n C -->|comment_created| F[添加评论]\n D --> G[响应 200 OK]\n E --> G\n F --> G\n```\n\n资料来源：[playbooks/slack-jira-incident.md:30-50]()\n\n---\n\n## 字段映射规范\n\n### Slack → Jira 字段映射\n\n| Slack 属性 | Jira 字段 | 转换规则 |\n|------------|-----------|----------|\n| `event.item.channel` + `event.item.ts` | correlation key | 格式：`slack:{team_id}:{channel_id}:{ts}` |\n| 消息文本首句 | `summary` | 截断至 120 字符 |\n| 消息全文 + 线程回复 | `description` | 包含 Slack permalink 链接 |\n| 触发器来源 | 标签 | 添加 `slack-incident` 标签 |\n\n资料来源：[playbooks/slack-jira-incident.md:50-60]()\n\n### Salesforce → HubSpot 字段映射\n\n| Salesforce 字段 | HubSpot 字段 | 数据类型 |\n|-----------------|--------------|----------|\n| `Lead.Email` | `email` | string |\n| `Lead.FirstName` | `firstname` | string |\n| `Lead.LastName` | `lastname` | string |\n| `Lead.Company` | `company` | string |\n| `Lead.Phone` | `phone` | string |\n| `Lead.LeadSource` | `hs_lead_status` | enumeration |\n\n资料来源：[playbooks/salesforce-hubspot-lead-sync.md:15-25]()\n\n---\n\n## 认证与安全\n\n### 跨系统认证模式\n\n| 源系统 | 认证方式 | 目标系统 | 认证方式 |\n|--------|----------|----------|----------|\n| Slack | Bot Token (`xoxb-...`) | Jira | API Token + Basic Auth |\n| Zendesk | API Token | Jira | API Token + Basic Auth |\n| HubSpot | OAuth 2.0 / Private App | Asana | Personal Access Token |\n| Salesforce | OAuth 2.0 | HubSpot | Private App Token |\n\n资料来源：[playbooks/zendesk-jira-bug-escalation.md:20-30]()\n\n### Webhook 安全验证\n\n所有入站 Webhook 必须进行签名验证：\n\n```python\n# Slack 签名验证示例\ndef verify_slack_signature(body, timestamp, signature, signing_secret):\n prefix = f\"v0:{timestamp}:\"\n expected = \"v0=\" + hmac.new(\n signing_secret.encode(),\n prefix.encode() + body,\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(expected, signature)\n```\n\n```python\n# Linear 签名验证示例\ndef verify_linear_signature(body, signature, secret):\n expected = hmac.new(\n secret.encode(),\n body,\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(expected, signature)\n```\n\n资料来源：[playbooks/slack-jira-incident.md:70-85]()\n\n---\n\n## 错误处理策略\n\n### 错误响应码处理\n\n| Slack 错误码 | 处理策略 | 说明 |\n|--------------|----------|------|\n| `channel_not_found` | 重新安装应用 | workspace 权限变更导致 |\n| `ratelimited` | 尊重 `Retry-After` 头 | 指数退避重试 |\n| `already_in_channel` | 忽略 | 视为成功 |\n| `cant_update_message` | 跳过更新 | 仅原发布 bot 可更新 |\n| `msg_too_long` | 拆分消息 | 单条限制 40,000 字符 |\n\n资料来源：[skills/slack/skill.md:100-120]()\n\n### 重试机制\n\n```mermaid\ngraph TD\n A[API 调用] --> B{响应状态}\n B -->|2xx| C[成功 - 继续]\n B -->|429| D[读取 Retry-After]\n B -->|5xx| E[重试]\n D --> F[等待后重试]\n E --> F\n F --> A\n B -->|4xx 非 429| G[记录错误]\n G --> H[不重试 - 需修复代码]\n```\n\n资料来源：[playbooks/salesforce-hubspot-lead-sync.md:40-50]()\n\n---\n\n## 剧本示例：Slack-Jira 事件响应\n\n### 业务流程\n\n```mermaid\nsequenceDiagram\n participant S as Slack\n participant A as 事件处理器\n participant J as Jira\n participant H as HubSpot\n\n S->>A: 消息事件 (reaction_added)\n A->>S: 获取 permalink\n A->>J: 搜索相关工单\n alt 找到现有工单\n A->>J: 更新现有工单\n else 未找到工单\n A->>J: 创建新 Jira Issue\n A->>H: 同步客户信息\n end\n A->>S: 回复线程 (工单链接)\n```\n\n### 实现要点\n\n1. **关联键生成**：使用 `slack:{team_id}:{channel_id}:{ts}` 格式确保全局唯一性\n2. **幂等性处理**：创建前先搜索，避免重复工单\n3. **上下文保留**：在 description 中保留 Slack permalink 和消息原文\n4. **异步处理**：返回 200 后在后台执行重操作\n\n资料来源：[playbooks/slack-jira-incident.md:1-30]()\n\n---\n\n## 剧本示例：Zendesk-Jira Bug 升级\n\n### 触发条件\n\n| Zendesk 事件 | 条件 | Jira 操作 |\n|--------------|------|----------|\n| Ticket 创建 | `tags` 包含 `bug` | 创建 Bug 类型 Issue |\n| Ticket 更新 | `priority` 变为 `urgent` | 升级现有 Bug |\n| Ticket 更新 | `status` 变为 `solved` | 同步关闭 Jira Issue |\n\n### 数据映射\n\n| Zendesk 字段 | Jira 字段 | 说明 |\n|--------------|-----------|------|\n| `ticket.id` | `description` 引用 | 保留 Zendesk 链接 |\n| `ticket.subject` | `summary` | Bug 标题 |\n| `ticket.description` | `description` | 详细描述 |\n| `ticket.priority` | `priority` | Urgent → Highest |\n| `ticket.requester.email` | `reporter` | 报告人信息 |\n\n资料来源：[playbooks/zendesk-jira-bug-escalation.md:10-25]()\n\n---\n\n## 剧本示例：HubSpot-Asana 客户入职\n\n### 工作流阶段\n\n```mermaid\ngraph LR\n A[HubSpot Deal 成交] --> B[创建 Asana 项目]\n B --> C[添加项目任务模板]\n C --> D[分配负责人]\n D --> E[发送客户通知]\n E --> F[跟踪里程碑完成]\n F --> G[同步回 HubSpot]\n```\n\n### 配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `project_template_gid` | string | Asana 项目模板 ID |\n| `team_gid` | string | 负责团队 ID |\n| `due_date_offset` | number | 相对成交日期的天数 |\n| `notification_template` | string | 客户通知内容模板 |\n\n资料来源：[playbooks/hubspot-asana-onboarding.md:15-40]()\n\n---\n\n## 剧本示例：Salesforce-HubSpot 线索同步\n\n### 同步策略\n\n```mermaid\ngraph TD\n A[Salesforce Lead 创建/更新] --> B{冲突检测}\n B -->|HubSpot 无对应记录| C[创建 HubSpot Contact]\n B -->|HubSpot 存在记录| D[比较 updatedAt 时间戳]\n D -->|SF 更新更新| E[更新 HubSpot]\n D -->|HubSpot 更新更新| F[跳过 - 保留 HubSpot 数据]\n C --> G[记录同步日志]\n E --> G\n```\n\n### 同步字段配置\n\n| Salesforce | HubSpot | 同步方向 | 冲突处理 |\n|------------|---------|----------|----------|\n| `Email` | `email` | 必填 | 作为唯一标识符 |\n| `FirstName` | `firstname` | SF → HS | 以最新更新为准 |\n| `LastName` | `lastname` | SF → HS | 以最新更新为准 |\n| `Company` | `company` | SF → HS | 以最新更新为准 |\n| `Phone` | `phone` | 双向 | 以最新更新为准 |\n\n资料来源：[playbooks/salesforce-hubspot-lead-sync.md:10-35]()\n\n---\n\n## 最佳实践\n\n### 设计原则\n\n1. **幂等性优先**：所有操作必须可安全重试，避免重复创建资源\n2. **快速响应**：Webhook 端点应立即返回 200，在后台处理复杂逻辑\n3. **签名验证**：所有入站事件必须验证签名，拒绝未授权请求\n4. **数据映射文档化**：明确记录每个字段的转换规则和默认值\n5. **错误可观测性**：记录足够的日志信息便于调试，包括错误码和响应时间\n\n### 性能优化\n\n| 优化点 | 策略 |\n|--------|------|\n| API 调用次数 | 使用批量 API，减少循环调用 |\n| Webhook 处理 | 消息队列异步处理，避免阻塞 |\n| 缓存策略 | 缓存认证 token 和频繁查询的数据 |\n| 复杂度控制 | Linear API 请求优先选择必要的字段 |\n\n资料来源：[skills/linear/skill.md:80-100]()\n\n---\n\n## 相关资源\n\n### 工具技能文档\n\n- [Slack 技能文档](../skills/slack/skill.md)\n- [Jira 技能文档](../skills/jira/skill.md)\n- [HubSpot 技能文档](../skills/hubspot/skill.md)\n- [Salesforce 技能文档](../skills/salesforce/skill.md)\n- [Zendesk 技能文档](../skills/zendesk/skill.md)\n- [Linear 技能文档](../skills/linear/skill.md)\n- [Asana 技能文档](../skills/asana/skill.md)\n\n### 扩展阅读\n\n- [ROADMAP.md](../skills/ROADMAP.md) - 跨工具编排模式规划\n- [CLAUDE.md](https://github.com/Shanksg/clawskills/blob/main/.claude/CLAUDE.md) - Claude Code 集成配置\n\n---\n\n\n\n## 部署指南\n\n### 相关页面\n\n相关主题：[持续集成与发布](#page-cicd), [MCP 服务器架构](#page-mcp-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [package.json](https://github.com/Shanksg/clawskills/blob/main/package.json)\n- [.github/workflows/ci.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/ci.yml) (隐含引用)\n- [.github/workflows/release.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/release.yml) (隐含引用)\n- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md) (隐含引用)\n \n\n# 部署指南\n\n## 概述\n\nclawskills 是一个技能文档库（Skills Documentation Library），为 AI 工具提供集成指南。该项目包含 14 种工具的完整集成文档，并通过 MCP（Model Context Protocol）服务器提供访问接口。\n\n核心部署组件为 `clawskills-mcp` 服务器，它提供三个主要工具供 AI 助手调用：\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `list_skills` | 列出所有可用的技能文档 |\n| `get_skill` | 获取完整的技能文档或指定章节 |\n| `search_skills` | 全文本搜索所有技能文档 |\n\n资料来源：[README.md:1-10]()\n\n## 架构概览\n\n```graph TD\n A[用户/AI 工具] -->|MCP 协议| B[clawskills-mcp 服务器]\n B -->|HTTP| C[GitHub API]\n C -->|返回| B\n B -->|技能文档| A\n D[GitHub Actions] -->|自动化发布| E[npm 仓库]\n E -->|安装| B\n```\n\n## 本地部署方式\n\n### 临时运行（npx）\n\n无需安装，可直接通过 npx 运行 MCP 服务器：\n\n```bash\nnpx -y clawskills-mcp\n```\n\n此方式适用于一次性测试或临时集成场景。服务器启动后，AI 工具（如 Claude Desktop）可通过 MCP 协议连接并调用技能文档。\n\n资料来源：[README.md:71-75]()\n\n### 全局安装\n\n对于长期使用，建议全局安装：\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n全局安装后，MCP 服务器在系统中持久可用，不受当前工作目录限制。\n\n资料来源：[README.md:76-78]()\n\n## Claude Desktop / Claude Code 配置\n\n### 配置步骤\n\n将以下配置添加到 Claude Desktop 或 Claude Code 的配置文件中：\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n### 配置位置\n\n| 平台 | 配置文件路径 |\n|------|-------------|\n| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop (Windows) | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Claude Code | `.claude/settings.json` 或项目级配置 |\n\n### 验证配置\n\n配置完成后，重启 Claude Desktop/Claude Code，然后尝试调用技能工具：\n\n```\nlist_skills\n```\n\n预期返回所有 14 个工具的技能文档列表。\n\n资料来源：[README.md:79-90]()\n\n## MCP 服务器工具详解\n\n### list_skills\n\n返回所有可用的技能文档列表，无需参数。\n\n```json\n// 响应示例\n{\n \"skills\": [\n \"monday\",\n \"salesforce\",\n \"jira\",\n \"dynamics365\",\n \"hubspot\",\n \"servicenow\",\n \"zendesk\",\n \"asana\",\n \"github\",\n \"figma\",\n \"slack\",\n \"stripe\",\n \"notion\",\n \"linear\"\n ]\n}\n```\n\n### get_skill\n\n获取指定技能的完整文档或特定章节。\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `skill_name` | string | 是 | 技能名称（如 `jira`、`linear`） |\n| `section` | string | 否 | 指定章节：`auth`、`rate-limits`、`recipes`、`errors` |\n\n```json\n// 获取 Jira 技能文档的认证部分\n{\n \"skill_name\": \"jira\",\n \"section\": \"auth\"\n}\n```\n\n### search_skills\n\n全文本搜索所有技能文档。\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `query` | string | 是 | 搜索关键词 |\n| `limit` | number | 否 | 返回结果数量限制（默认 10） |\n\n## CI/CD 自动化部署\n\n### 持续集成\n\n每次推送和 PR 合并时触发 CI 流程：\n\n```mermaid\ngraph LR\n A[推送/PR] --> B{GitHub Actions CI}\n B --> C[npm test]\n C --> D{测试通过?}\n D -->|是| E[允许合并]\n D -->|否| F[阻止合并]\n```\n\n测试套件包括：\n- Vitest 单元测试\n- 真实技能文档验证\n- 必需章节检查\n- 文档大小验证（≥5 KB）\n\n资料来源：[skills/ROADMAP.md:1-15]()\n\n### 发布自动化\n\n项目使用 `release.yml` 工作流自动化版本发布：\n\n1. 合并到 `main` 分支\n2. 进入 GitHub Actions → **Release**\n3. 运行工作流，选择版本类型：\n - `patch` — 补丁版本（bug 修复）\n - `minor` — 次版本（新功能）\n - `major` — 主版本（破坏性变更）\n\n发布流程自动完成：\n- 版本号递增\n- Git 标签创建\n- npm 包发布\n\n资料来源：[README.md:35-40]()\n\n### OIDC 认证\n\n发布流程使用 OpenID Connect (OIDC) 与 npm 仓库建立安全连接，无需存储 npm token。\n\n## 部署验证清单\n\n部署完成后，按以下清单验证：\n\n- [ ] Claude Desktop/Code 已重启\n- `list_skills` 调用成功，返回 14 个工具\n- `get_skill` 能获取完整文档\n- `search_skills` 搜索结果准确\n- MCP 连接状态为\"已连接\"\n\n## 项目结构参考\n\n```\nclawskills/\n├── README.md # 主说明文档\n├── package.json # npm 包配置\n├── skills/ # 技能文档目录\n│ ├── INDEX.md # 所有技能索引\n│ ├── jira/\n│ ├── linear/\n│ ├── figma/\n│ └── ... # 其他 11 个工具\n├── playbooks/ # 跨工具工作流\n│ └── slack-jira-incident.md\n└── .github/\n └── workflows/\n ├── ci.yml # 持续集成\n └── release.yml # 发布自动化\n```\n\n## 常见部署问题\n\n| 问题 | 解决方案 |\n|------|---------|\n| MCP 服务器连接失败 | 检查 JSON 配置格式，确保 `command` 为 `npx` |\n| 工具调用超时 | 确认网络连接，可使用全局安装替代 npx |\n| 版本过旧 | 运行 `npm update -g clawskills-mcp` 更新 |\n| 权限错误 | 检查 Claude Desktop 配置文件的读写权限 |\n\n## 相关资源\n\n- 项目主页：https://github.com/Shanksg/clawskills\n- MCP 服务器 npm 包：https://www.npmjs.com/package/clawskills-mcp\n- 技能索引：[skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n- 开发路线图：[skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n---\n\n\n\n## 持续集成与发布\n\n### 相关页面\n\n相关主题：[部署指南](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n- [mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)\n- [.github/workflows/ci.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/ci.yml)\n- [.github/workflows/release.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/release.yml)\n- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n \n\n# 持续集成与发布\n\n## 概述\n\nClawSkills 项目采用自动化持续集成（CI）和持续发布（CD）流程，确保代码质量和发布效率。整个系统基于 GitHub Actions 实现自动化构建、测试和发布流程，涵盖单元测试、技能文档验证、版本管理和 npm 包发布等关键环节。\n\n项目包含两套独立的自动化工作流：\n- **CI 工作流** (`ci.yml`)：在每次 push 和 PR 时自动执行构建和测试\n- **发布工作流** (`release.yml`)：通过手动触发实现语义化版本管理和 npm 发布\n\n## 整体架构\n\n```mermaid\ngraph TD\n A[开发者提交代码] --> B{触发方式}\n B -->|push / PR| C[ci.yml 工作流]\n B -->|workflow_dispatch| D[release.yml 工作流]\n \n C --> E[安装依赖]\n E --> F[npm test]\n F --> G{测试结果}\n G -->|通过| H[CI 成功]\n G -->|失败| I[CI 失败 / 通知]\n \n D --> J[选择版本类型]\n J --> K[patch / minor / major]\n K --> L[更新版本号]\n L --> M[创建 Git Tag]\n M --> N[推送至 npm]\n N --> O[发布完成]\n```\n\n## CI 工作流详解\n\n### 触发条件\n\nCI 工作流在以下场景自动触发：\n\n| 触发事件 | 说明 |\n|---------|------|\n| `push` | 代码推送至 main 分支或 PR 分支 |\n| `pull_request` | 创建或更新 Pull Request |\n\n资料来源：[.github/workflows/ci.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/ci.yml)\n\n### 测试套件\n\n项目使用 Vitest 作为测试框架，测试套件位于 `mcp-server/src/index.test.ts`。测试验证以下关键要求：\n\n```typescript\ndescribe(\"real skills\", () => {\n it(\"loads all expected skills\", () => {\n // 验证所有14个skill都被正确加载\n });\n\n it(\"every skill has a non-empty summary line\", () => {\n // 验证每个skill都有摘要行\n });\n\n it(\"every skill contains the required sections\", () => {\n // 验证每个skill包含所有11个必需部分\n });\n\n it(\"every skill file is at least 5KB\", () => {\n // 验证skill文件大小合理\n });\n});\n```\n\n资料来源：[mcp-server/src/index.test.ts:19-44](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n\n### 必需部分验证\n\n每个 skill 文档必须包含以下 11 个部分：\n\n1. 认证与权限\n2. 核心端点\n3. 常见工作流（Recipes）\n4. 过滤与查询模式\n5. 速率限制与重试策略\n6. 错误处理\n7. Webhook 配置\n8. 数据模型\n9. 安全与隐私\n10. 配额与限制\n11. 相关资源\n\n### npm 测试命令\n\n```json\n{\n \"scripts\": {\n \"test\": \"vitest run\"\n }\n}\n```\n\n资料来源：[mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)\n\n## 发布工作流详解\n\n### 触发方式\n\n发布工作流通过 GitHub Actions 手动触发（workflow_dispatch），开发者可选择发布类型。\n\n```yaml\nworkflow_dispatch:\n inputs:\n release_type:\n description: '发布类型'\n required: true\n type: choice\n options:\n - patch\n - minor\n - major\n```\n\n资料来源：[.github/workflows/release.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/release.yml)\n\n### 发布流程步骤\n\n```mermaid\ngraph LR\n A[选择发布类型] --> B[更新 package.json 版本号]\n B --> C[创建 Git Tag]\n C --> D[提交更改]\n D --> E[推送到 GitHub]\n E --> F[发布到 npm registry]\n```\n\n### 版本管理策略\n\n项目采用语义化版本（SemVer）规范：\n\n| 版本类型 | 说明 | 示例 |\n|---------|------|------|\n| `patch` | 补丁版本，修复问题 | 1.0.0 → 1.0.1 |\n| `minor` | 次版本，新增功能（向后兼容） | 1.0.0 → 1.1.0 |\n| `major` | 主版本，破坏性变更 | 1.0.0 → 2.0.0 |\n\n### OIDC 发布机制\n\n发布工作流使用 OpenID Connect (OIDC) 进行身份验证，确保安全的 npm 发布流程：\n\n```yaml\npermissions:\n id-token: write\n contents: read\n```\n\n此配置允许工作流从 npm 获取短期令牌，无需长期存储凭据。\n\n## MCP Server 包管理\n\n### 包结构\n\n```json\n{\n \"name\": \"clawskills-mcp\",\n \"version\": \"0.2.0\",\n \"description\": \"MCP server exposing ClawSkills API integration docs\",\n \"bin\": {\n \"clawskills-mcp\": \"./dist/index.js\"\n },\n \"engines\": {\n \"node\": \">=18\"\n }\n}\n```\n\n资料来源：[mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)\n\n### 安装方式\n\n| 安装方式 | 命令 | 适用场景 |\n|---------|------|---------|\n| 临时运行（npx） | `npx -y clawskills-mcp` | Claude Desktop / Claude Code |\n| 全局安装 | `npm install -g clawskills-mcp` | 持久化使用 |\n\n## 技能文档同步机制\n\n### 同步脚本\n\n项目提供两个辅助脚本用于管理和同步技能文档：\n\n| 脚本 | 功能 |\n|------|------|\n| `check-skills.mjs` | 验证 skill 文档的完整性和格式 |\n| `sync-skills.mjs` | 同步更新 skill 文档 |\n\n资料来源：[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)\n\n### 可用 Skills 列表\n\n系统支持以下 14 个工具的集成技能文档：\n\n- Asana\n- Dynamics 365\n- Figma\n- GitHub\n- HubSpot\n- Jira\n- Linear\n- Monday.com\n- Notion\n- Salesforce\n- ServiceNow\n- Slack\n- Stripe\n- Zendesk\n\n资料来源：[mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n\n## MCP 工具接口\n\n### 工具列表\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `list_skills` | 列出所有可用的 skill 文档 |\n| `get_skill` | 获取完整的 skill 文档或指定部分 |\n| `search_skills` | 在所有 skill 文档中进行全文搜索 |\n| `list_playbooks` | 列出所有可用的剧本 |\n| `get_playbook` | 获取指定剧本内容 |\n\n### 使用配置\n\n在 Claude Desktop 或 Claude Code 中配置：\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n## 开发贡献流程\n\n### 分支命名规范\n\n```bash\ngit checkout -b skill/<工具名称>\n```\n\n### 提交流程\n\n1. 创建功能分支\n2. 按照模板结构编写或更新 skill 文档（必须包含全部 11 个部分）\n3. 验证所有端点、速率限制和认证流程\n4. 在文档头部添加 `Last validated:` 日期\n5. 更新 `skills/INDEX.md` 和 `README.md`\n6. 在 `## Sources` 部分添加官方文档链接\n7. 提交 Pull Request\n\n### PR 验证\n\n提交 PR 后，CI 流水线自动执行 `npm test`，验证内容：\n\n- skill 文件可正常加载\n- 包含所有必需章节\n- 文件大小不小于 5KB\n\n资料来源：[mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n\n## 最佳实践\n\n### 技能文档编写规范\n\n| 要求 | 说明 |\n|------|------|\n| 章节完整性 | 必须包含全部 11 个必需部分 |\n| 最小长度 | 文件大小至少 5KB |\n| API 验证 | 所有端点需对照官方文档验证 |\n| 认证模式 | 严格按照文档中的认证模式实现 |\n| 速率限制 | 准确记录各 API 的速率限制 |\n| 错误代码 | 列出所有相关的错误代码和处理方式 |\n\n### 发布检查清单\n\n- [ ] 所有测试通过\n- [ ] 版本号正确更新\n- [ ] Git Tag 已创建\n- [ ] CHANGELOG 已更新\n- [ ] npm 发布成功\n\n## 相关资源\n\n- GitHub Actions 文档：https://docs.github.com/actions\n- Vitest 测试框架：https://vitest.dev\n- SemVer 规范：https://semver.org\n\n---\n\n\n\n## 贡献指南\n\n### 相关页面\n\n相关主题：[技能文档结构](#page-skill-anatomy)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n \n\n# 贡献指南\n\n本文档介绍如何为 clawskills 项目贡献代码和技能文档。clawskills 是一个集成技能库，汇集了多种工具（如 Salesforce、Jira、Linear、Slack 等）的 API 集成文档和最佳实践。贡献者可以通过标准的 Git 工作流提交新的技能文档或更新现有内容。\n\n---\n\n## 贡献流程概述\n\n贡献 clawskills 的标准流程包含以下步骤：\n\n```mermaid\ngraph TD\n A[创建功能分支] --> B[遵循 skill.md 模板编写文档]\n A1[git checkout -b skill/<toolname>] --> A\n B --> C[对照官方文档验证内容]\n C --> D[添加 Last validated 日期]\n D --> E[更新 INDEX.md 和 README.md]\n E --> F[提交 Pull Request]\n F --> G[CI 自动测试]\n G --> H{测试通过?}\n H -->|是| I[合并到 main 分支]\n H -->|否| J[修复测试失败]\n J --> F\n I --> K[触发 Release 工作流]\n K --> L[选择版本类型]\n L --> M[发布新版本]\n```\n\n资料来源：[README.md:29-40](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 创建功能分支\n\n所有贡献必须通过 Git 分支工作流进行。创建新技能文档时，请使用以下命名规范：\n\n```bash\ngit checkout -b skill/\n```\n\n其中 `` 是目标工具的名称（小写）。\n\n| 分支前缀 | 用途 | 示例 |\n|---------|------|------|\n| `skill/` | 新增技能文档 | `skill/zendesk` |\n| `skill/` | 更新现有技能 | `skill/salesforce-update` |\n\n资料来源：[README.md:30](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 技能文档结构要求\n\nclawskills 要求所有技能文档严格遵循标准模板结构。文档必须包含 **11 个必需章节**，每个章节都有其特定用途。\n\n### 必需章节列表\n\n| 章节编号 | 章节名称 | 说明 |\n|---------|---------|------|\n| 1 | 概述 | 工具简介和使用场景 |\n| 2 | 认证与权限 | API 密钥、OAuth 等认证方式 |\n| 3 | 核心端点 | 主要 API 端点及其参数 |\n| 4 | 常见工作流 | 典型使用场景和代码示例 |\n| 5 | 错误处理 | 错误代码和解决方案 |\n| 6 | 速率限制 | API 限制和重试策略 |\n| 7 | Webhook | 事件订阅配置 |\n| 8 | 数据模型 | 主要数据类型和字段 |\n| 9 | 可靠性 | 容错和幂等性保证 |\n| 10 | 安全与隐私 | 最佳安全实践 |\n| 11 | 参考来源 | 官方文档链接 |\n\n### 文档验证规则\n\nCI 测试会验证以下条件：\n\n```typescript\nconst REQUIRED_SECTIONS = [\n \"认证与权限\", \"核心端点\", \"常见工作流\",\n \"错误处理\", \"速率限制\", \"可靠性\",\n \"安全与隐私\", \"参考来源\"\n];\n\n// 每个技能文件必须满足以下条件：\n// 1. 包含所有必需章节\n// 2. 文件大小至少 5KB\n// 3. 每个章节内容非空\n```\n\n资料来源：[mcp-server/src/index.test.ts:20-40](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n\n---\n\n## 内容编写规范\n\n### 验证要求\n\n在提交贡献前，必须对照官方供应商文档验证以下信息：\n\n| 验证项 | 说明 |\n|-------|------|\n| 端点地址 | 确保 URL 路径和参数准确 |\n| 速率限制 | 验证当前限制值和计算方式 |\n| 认证流程 | 确认 OAuth scopes 和 token 格式 |\n| 错误代码 | 对照官方错误码文档 |\n\n### 日期标注\n\n每个技能文档的元数据头部必须包含 `Last validated:` 日期：\n\n```markdown\n---\ntool: jira\nversion: \"3.x\"\nlast_validated: 2024-01-15\n---\n```\n\n### 来源引用\n\n`## 参考来源` 章节必须包含指向官方文档的有效链接。禁止添加未经核实的信息：\n\n```markdown\n## 参考来源\n\n- [Jira Cloud REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/)\n- [OAuth 2.0 认证](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)\n```\n\n资料来源：[README.md:33-36](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 索引文件更新\n\n当添加新技能时，必须同步更新以下文件：\n\n| 文件路径 | 更新内容 |\n|---------|---------|\n| `skills/INDEX.md` | 添加新技能的链接和简介 |\n| `README.md` | 在工具列表中补充新工具 |\n\n这些更新确保用户能够发现和访问新增的技能文档。\n\n资料来源：[README.md:37](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## Pull Request 流程\n\n### 提交 PR\n\n完成文档编写和索引更新后，打开 Pull Request：\n\n```bash\ngit add .\ngit commit -m \"feat: add linear skill documentation\"\ngit push origin skill/linear\n```\n\n### CI 测试\n\nPR 提交后，CI 流水线自动执行测试：\n\n```bash\nnpm test\n```\n\n测试内容包括：\n\n- 验证所有必需章节存在\n- 检查文件大小（≥5KB）\n- 确认摘要行非空\n- 加载所有已知技能\n\n| 测试项 | 失败后果 |\n|-------|---------|\n| 必需章节缺失 | PR 被阻止合并 |\n| 文件过短 | 提示可疑的短文件 |\n| 摘要为空 | 返回错误信息 |\n\n资料来源：[README.md:38](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 发布流程\n\n### 版本管理策略\n\nclawskills 使用语义化版本号（SemVer）：\n\n| 版本类型 | 使用场景 | 示例 |\n|---------|---------|------|\n| `patch` | 补丁版本，文档修正 | 1.0.1 → 1.0.2 |\n| `minor` | 次要版本，功能新增 | 1.0.1 → 1.1.0 |\n| `major` | 主要版本，破坏性变更 | 1.0.1 → 2.0.0 |\n\n### 发布步骤\n\n发布流程已完全自动化：\n\n1. 将 PR 合并到 `main` 分支\n2. 进入 GitHub Actions 页面\n3. 选择 **Release** 工作流\n4. 点击 **Run workflow**\n5. 选择版本类型（patch / minor / major）\n\n```mermaid\ngraph LR\n A[合并到 main] --> B[GitHub Actions]\n B --> C[触发 Release 工作流]\n C --> D[选择版本号]\n D --> E[创建 Git Tag]\n E --> F[NPM 包发布]\n F --> G[生成 Release Notes]\n```\n\n资料来源：[README.md:39-40](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 治理与更新机制\n\n### 治理原则\n\n根据 ROADMAP.md，clawskills 采用以下治理策略：\n\n| 原则 | 说明 |\n|-----|------|\n| 准确性优先 | 所有端点和限制必须对照官方文档验证 |\n| 自动化维护 | CI/CD 流水线确保文档一致性 |\n| 版本控制 | 语义化版本管理变更 |\n\n### 内容更新周期\n\n技能文档的优先级排序：\n\n| 优先级 | 类型 | 说明 |\n|-------|------|------|\n| P1 | 准确性更新 | 官方 API 变更时的紧急更新 |\n| P2 | 新功能补充 | 主流工作流添加 |\n| P3 | 完善现有内容 | 边缘案例和高级用法 |\n\n资料来源：[skills/ROADMAP.md:20-30](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n---\n\n## 快速检查清单\n\n在提交贡献前，请确认以下项目：\n\n- [ ] 分支命名符合 `skill/` 规范\n- [ ] 文档包含全部 11 个必需章节\n- [ ] 所有端点和限制已对照官方文档验证\n- [ ] 已添加 `Last validated:` 日期\n- [ ] `skills/INDEX.md` 和 `README.md` 已更新\n- [ ] 参考来源章节包含有效官方链接\n- [ ] CI 测试全部通过\n\n---\n\n## 常见问题\n\n### 技能文档最小长度是多少？\n\n每个技能文档必须至少 **5KB**，CI 测试会检查文件大小。短文件会被标记为可疑并阻止合并。\n\n### 可以跳过某些章节吗？\n\n不可以。claws kills 要求所有 11 个章节都必须存在且非空。\n\n### 如何验证认证流程是否正确？\n\n请直接对照官方供应商文档。例如，Salesforce 的 OAuth 流程应参考官方 Developer Guide。禁止基于第三方资料或推测编写认证内容。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Shanksg/clawskills\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1161910025 | https://github.com/Shanksg/clawskills | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1161910025 | https://github.com/Shanksg/clawskills | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1161910025 | https://github.com/Shanksg/clawskills | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | release_recency=unknown\n\n\n",
"markdown_key": "clawskills",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1161910025",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Shanksg/clawskills"
},
{
"evidence_id": "art_9f396e1561e64b3ebfb6e90dc0470328",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Shanksg/clawskills#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "clawskills 说明书",
"toc": [
"https://github.com/Shanksg/clawskills 项目说明书",
"目录",
"项目概述",
"项目简介",
"核心架构",
"技能文档结构",
"支持的工具列表",
"工作流程配方",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# clawskills-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 clawskills-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`skills/asana/skill.md`, `skills/dynamics365/skill.md`, `skills/figma/skill.md`, `skills/github/skill.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npx -y clawskills-mcp` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npm install -g clawskills-mcp` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`skills/asana/skill.md`, `skills/dynamics365/skill.md`, `skills/figma/skill.md`, `skills/github/skill.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`skills/asana/skill.md`, `skills/dynamics365/skill.md`, `skills/figma/skill.md`, `skills/github/skill.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`skills/asana/skill.md`, `skills/dynamics365/skill.md`, `skills/figma/skill.md`, `skills/github/skill.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `skills/github/skill.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`skills/asana/skill.md`, `skills/dynamics365/skill.md`, `skills/figma/skill.md`, `skills/github/skill.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：38\n- 重要文件覆盖：30/38\n- 证据索引条目：30\n- 角色 / Skill 条目：13\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 clawskills-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 clawskills-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 clawskills-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 13 个角色 / Skill / 项目文档条目。\n\n- **Asana Skill**（skill）：Last validated: 2026-05-13 API: Asana REST API 1.0 REST base URL: https://app.asana.com/api/1.0 Assumed product: Asana cloud. Enterprise controls, SCIM, and admin APIs may require additional scopes and plan-specific access. ⚠️ Changes since 2026-02-19: - Out of Office API 2026-04-27 : new endpoints replace the legacy vacation dates field, which is now deprecated on the user object. Migrate any code that reads/writes… 激活提示：当用户任务与“Asana Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/asana/skill.md`\n- **Microsoft Dynamics 365 Skill**（skill）：Last validated: 2026-05-13 API: Dataverse Web API OData v4 v9.2 Base URL: https://{org-name}.crm.dynamics.com/api/data/v9.2/ Assumed product: Dynamics 365 Sales. Other apps Customer Service, Field Service share the same Web API pattern. Note: Re-confirmed on 2026-05-13: v9.0, v9.1, and v9.2 still have identical Web API behavior with no breaking changes. No v9.3 or v10 announced. The 2026 release waves are PowerApps/… 激活提示：当用户任务与“Microsoft Dynamics 365 Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/dynamics365/skill.md`\n- **Figma Skill Reference**（skill）：Last validated: 2026-02-22 API version: REST API v1 stable Webhooks V2 stable Pin X-Figma-Api-Version not required — versioning is path-based /v1/ , /v2/ Base URL: https://api.figma.com Government: https://api.figma-gov.com 激活提示：当用户任务与“Figma Skill Reference”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/figma/skill.md`\n- **GitHub Skill**（skill）：Last validated: 2026-02-22 API: GitHub REST API + GraphQL API v4 REST base URL: https://api.github.com API version header: X-GitHub-Api-Version: 2022-11-28 current stable Assumed product: GitHub.com cloud . GitHub Enterprise Server differs in base URL and some rate limits. 激活提示：当用户任务与“GitHub Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/github/skill.md`\n- **HubSpot Skill**（skill）：Last validated: 2026-05-11 API: HubSpot CRM API v3 date-based versioning GA — March 30, 2026 Base URL: https://api.hubapi.com/crm/v3/objects/{objectType} Assumed products: CRM Contacts, Companies, Deals + Marketing Hub + Sales Hub ⚠️ Changes since 2024: - Rate limits raised Sep 2024 : Pro/Enterprise burst = 190 req/10s was 150 ; Enterprise daily = 1M was 500k . - CRM Search API max page size raised to 200 records wa… 激活提示：当用户任务与“HubSpot Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/hubspot/skill.md`\n- **Jira Skill**（skill）：Last validated: 2026-05-11 API: Jira Cloud REST API v3 Base URL: https://{your-domain}.atlassian.net/rest/api/3/ Assumed product: Jira Cloud Software or Service Management . Note differences from Jira Data Center where applicable. ⚠️ Breaking changes in 2026: - GET /rest/api/3/search is deprecated — migrate to POST /rest/api/3/search/jql which uses nextPageToken pagination see Recipe 2 . - Field configuration scheme… 激活提示：当用户任务与“Jira Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/jira/skill.md`\n- **Linear Skill**（skill）：Last validated: 2026-03-02 API: GraphQL no versioned URL path GraphQL endpoint: https://api.linear.app/graphql Assumed product: Linear cloud . The same API powers all Linear workspaces. ⚠️ OAuth note: Apps created after October 1, 2025 issue short-lived access tokens 24 hr and require refresh token rotation. Apps created before that date use long-lived tokens until the April 1, 2026 migration deadline. 激活提示：当用户任务与“Linear Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/linear/skill.md`\n- **Monday.com Skill**（skill）：Last validated: 2026-05-11 API: monday.com GraphQL API Current version: 2026-04 April 1, 2026 Note: monday.com uses GraphQL exclusively — not REST. All requests go to a single endpoint. Versions: RC= 2026-07 Current= 2026-04 Maintenance= 2026-01 Deprecated: 2025-10 , 2025-01 , 2024-10 routed to 2025-04 as of Feb 15, 2026 ⚠️ Changed 2026-04-01: 2026-04 is now the stable Current version. If you were pinning 2026-01 ,… 激活提示：当用户任务与“Monday.com Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/monday/skill.md`\n- **Notion Skill**（skill）：Last validated: 2026-03-02 API version: 2025-09-03 latest stable REST base URL: https://api.notion.com/v1/ Assumed product: Notion cloud . The Notion-Version: 2025-09-03 header is required on every request. This version introduced multi-source databases — see the Key concepts section for migration notes. 激活提示：当用户任务与“Notion Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/notion/skill.md`\n- **Salesforce Skill**（skill）：Last validated: 2026-05-13 API: Salesforce REST API + Bulk API v2 Version: v67.0 Summer '26 Assumed product: Sales Cloud CRM . Adjust object availability for other clouds. Version note: v64.0 = Summer '25, v65.0 = Winter '26, v66.0 = Spring '26, v67.0 = Summer '26 current GA . Examples in this doc reference /services/data/v66.0/ — still fully supported under Salesforce's ~3-year API support window. New code should p… 激活提示：当用户任务与“Salesforce Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/salesforce/skill.md`\n- **ServiceNow Skill**（skill）：Last validated: 2026-05-11 API: ServiceNow REST Table API + Attachment API Current release: Yokohama GA March 12, 2025 — re-confirmed against docs.servicenow.com on 2026-05-11 Base URL: https://{instance-name}.service-now.com/api/now/ Assumed product: ITSM Incident, Problem, Change, Request . All APIs are available on other ServiceNow apps using the same Table API pattern. Release history: Xanadu 2024 → Yokohama Mar… 激活提示：当用户任务与“ServiceNow Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/servicenow/skill.md`\n- **Stripe Skill**（skill）：Last validated: 2026-03-01 API version: 2026-02-25.clover latest stable REST base URL: https://api.stripe.com/v1/ Assumed product: Stripe Payments + Billing. Stripe Connect multi-account platform is covered in the Auth and Recipes sections. 激活提示：当用户任务与“Stripe Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/stripe/skill.md`\n- **Zendesk Skill**（skill）：Last validated: 2026-05-13 API: Zendesk Support REST API v2 Base URL: https://{subdomain}.zendesk.com/api/v2/ ⚠️ Breaking changes since 2024: - OAuth implicit grant and password grant flows deprecated as of February 17, 2025 — use Authorization Code grant only. - www.zopim.com/api/v2 legacy Zopim Chat REST API retired February 28, 2025 — use {subdomain}.zendesk.com/api/v2/chat instead. - Old-style HTTP Target webhoo… 激活提示：当用户任务与“Zendesk Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/zendesk/skill.md`\n\n## 证据索引\n\n- 共索引 30 条证据。\n\n- **ClawSkills**（documentation）：A library of integration skill documents for the most common SaaS platforms used in go-to-market and operations workflows. Each skill doc teaches an AI agent, automation builder, or LLM how to reliably use a platform's API with working code examples, rate limit rules, error playbooks, and platform-specific version details. 证据：`README.md`\n- **clawskills-mcp**（documentation）：An MCP Model Context Protocol server that exposes ClawSkills https://github.com/Shanksg/clawskills API integration skill docs to AI agents. 证据：`mcp-server/README.md`\n- **Package**（package_manifest）：{ \"name\": \"clawskills-mcp\", \"version\": \"0.6.0\", \"description\": \"MCP server exposing ClawSkills API integration skill docs to AI agents\", \"license\": \"MIT\", \"author\": \"ClawSkills Contributors\", \"homepage\": \"https://github.com/Shanksg/clawskills readme\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/Shanksg/clawskills.git\" }, \"keywords\": \"mcp\", \"claude\", \"ai\", \"integration\", \"api\", \"skill\", \"salesforce\", \"hubspot\", \"jira\", \"zendesk\", \"slack\", \"crm\", \"saas\" , \"type\": \"module\", \"bin\": { \"clawskills-mcp\": \"dist/index.js\" }, \"files\": \"dist/\", \"skills/\", \"playbooks/\" , \"scripts\": { \"sync:skills\": \"node scripts/sync-skills.mjs\", \"check:skills\": \"node scripts/check-skills.mjs\", \"check… 证据：`mcp-server/package.json`\n- **Asana Skill**（skill_instruction）：Last validated: 2026-05-13 API: Asana REST API 1.0 REST base URL: https://app.asana.com/api/1.0 Assumed product: Asana cloud. Enterprise controls, SCIM, and admin APIs may require additional scopes and plan-specific access. ⚠️ Changes since 2026-02-19: - Out of Office API 2026-04-27 : new endpoints replace the legacy vacation dates field, which is now deprecated on the user object. Migrate any code that reads/writes vacation dates . - RBAC Role API 2026-02-27 : new CRUD endpoints for managing custom roles on Enterprise plans. - Timesheet Approval Status API 2026-03-20 and Categories for Time Tracking Entries 2026-04-01 : new time-tracking primitives — useful for ops/finance workflows. - Pro… 证据：`skills/asana/skill.md`\n- **Microsoft Dynamics 365 Skill**（skill_instruction）：Last validated: 2026-05-13 API: Dataverse Web API OData v4 v9.2 Base URL: https://{org-name}.crm.dynamics.com/api/data/v9.2/ Assumed product: Dynamics 365 Sales. Other apps Customer Service, Field Service share the same Web API pattern. Note: Re-confirmed on 2026-05-13: v9.0, v9.1, and v9.2 still have identical Web API behavior with no breaking changes. No v9.3 or v10 announced. The 2026 release waves are PowerApps/Copilot features, not Web API surface changes. Source: https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/web-api-versions page revision 2026-03-27 证据：`skills/dynamics365/skill.md`\n- **Figma Skill Reference**（skill_instruction）：Last validated: 2026-02-22 API version: REST API v1 stable Webhooks V2 stable Pin X-Figma-Api-Version not required — versioning is path-based /v1/ , /v2/ Base URL: https://api.figma.com Government: https://api.figma-gov.com 证据：`skills/figma/skill.md`\n- **GitHub Skill**（skill_instruction）：Last validated: 2026-02-22 API: GitHub REST API + GraphQL API v4 REST base URL: https://api.github.com API version header: X-GitHub-Api-Version: 2022-11-28 current stable Assumed product: GitHub.com cloud . GitHub Enterprise Server differs in base URL and some rate limits. 证据：`skills/github/skill.md`\n- **HubSpot Skill**（skill_instruction）：Last validated: 2026-05-11 API: HubSpot CRM API v3 date-based versioning GA — March 30, 2026 Base URL: https://api.hubapi.com/crm/v3/objects/{objectType} Assumed products: CRM Contacts, Companies, Deals + Marketing Hub + Sales Hub ⚠️ Changes since 2024: - Rate limits raised Sep 2024 : Pro/Enterprise burst = 190 req/10s was 150 ; Enterprise daily = 1M was 500k . - CRM Search API max page size raised to 200 records was 100 ; rate limit raised to 5 req/s was 4 . - X-HubSpot-RateLimit-Secondly and X-HubSpot-RateLimit-Secondly-Remaining headers deprecated — use X-HubSpot-RateLimit-Remaining instead. - Contact Lists API v1 sunset April 30, 2026 — endpoints now return 404. Use the v3 Lists API. -… 证据：`skills/hubspot/skill.md`\n- **Jira Skill**（skill_instruction）：Last validated: 2026-05-11 API: Jira Cloud REST API v3 Base URL: https://{your-domain}.atlassian.net/rest/api/3/ Assumed product: Jira Cloud Software or Service Management . Note differences from Jira Data Center where applicable. ⚠️ Breaking changes in 2026: - GET /rest/api/3/search is deprecated — migrate to POST /rest/api/3/search/jql which uses nextPageToken pagination see Recipe 2 . - Field configuration scheme APIs will be removed July 2026 — avoid building on fieldconfigurationscheme endpoints. - Atlassian Connect reaches end of support December 2026 — migrate to Atlassian Forge for new apps. End of support for Atlassian Connect Express and Connect Spring Boot announced 2026-04-29. -… 证据：`skills/jira/skill.md`\n- **Linear Skill**（skill_instruction）：Last validated: 2026-03-02 API: GraphQL no versioned URL path GraphQL endpoint: https://api.linear.app/graphql Assumed product: Linear cloud . The same API powers all Linear workspaces. ⚠️ OAuth note: Apps created after October 1, 2025 issue short-lived access tokens 24 hr and require refresh token rotation. Apps created before that date use long-lived tokens until the April 1, 2026 migration deadline. 证据：`skills/linear/skill.md`\n- **Monday.com Skill**（skill_instruction）：Last validated: 2026-05-11 API: monday.com GraphQL API Current version: 2026-04 April 1, 2026 Note: monday.com uses GraphQL exclusively — not REST. All requests go to a single endpoint. Versions: RC= 2026-07 Current= 2026-04 Maintenance= 2026-01 Deprecated: 2025-10 , 2025-01 , 2024-10 routed to 2025-04 as of Feb 15, 2026 ⚠️ Changed 2026-04-01: 2026-04 is now the stable Current version. If you were pinning 2026-01 , that version moved to Maintenance — bug fixes only, no new features. Plan migration before its deprecation window opens. 证据：`skills/monday/skill.md`\n- **Notion Skill**（skill_instruction）：Last validated: 2026-03-02 API version: 2025-09-03 latest stable REST base URL: https://api.notion.com/v1/ Assumed product: Notion cloud . The Notion-Version: 2025-09-03 header is required on every request. This version introduced multi-source databases — see the Key concepts section for migration notes. 证据：`skills/notion/skill.md`\n- **Salesforce Skill**（skill_instruction）：Last validated: 2026-05-13 API: Salesforce REST API + Bulk API v2 Version: v67.0 Summer '26 Assumed product: Sales Cloud CRM . Adjust object availability for other clouds. Version note: v64.0 = Summer '25, v65.0 = Winter '26, v66.0 = Spring '26, v67.0 = Summer '26 current GA . Examples in this doc reference /services/data/v66.0/ — still fully supported under Salesforce's ~3-year API support window. New code should pin v67.0. ⚠️ Changed 2026-05-13: Summer '26 / v67.0 reached production GA. A detailed delta review against the Summer '26 release notes has not yet been performed — the canonical release notes page help.salesforce.com/.../rn api.htm is JS-rendered and unreadable by plain HTTP fet… 证据：`skills/salesforce/skill.md`\n- **ServiceNow Skill**（skill_instruction）：Last validated: 2026-05-11 API: ServiceNow REST Table API + Attachment API Current release: Yokohama GA March 12, 2025 — re-confirmed against docs.servicenow.com on 2026-05-11 Base URL: https://{instance-name}.service-now.com/api/now/ Assumed product: ITSM Incident, Problem, Change, Request . All APIs are available on other ServiceNow apps using the same Table API pattern. Release history: Xanadu 2024 → Yokohama March 12, 2025, current . Yokohama added AI Assets API, AWA Offer Work API, CICD Update Set API, and API Insights. The Table API and Attachment API formats are unchanged between releases. 证据：`skills/servicenow/skill.md`\n- **Stripe Skill**（skill_instruction）：Last validated: 2026-03-01 API version: 2026-02-25.clover latest stable REST base URL: https://api.stripe.com/v1/ Assumed product: Stripe Payments + Billing. Stripe Connect multi-account platform is covered in the Auth and Recipes sections. 证据：`skills/stripe/skill.md`\n- **Zendesk Skill**（skill_instruction）：Last validated: 2026-05-13 API: Zendesk Support REST API v2 Base URL: https://{subdomain}.zendesk.com/api/v2/ ⚠️ Breaking changes since 2024: - OAuth implicit grant and password grant flows deprecated as of February 17, 2025 — use Authorization Code grant only. - www.zopim.com/api/v2 legacy Zopim Chat REST API retired February 28, 2025 — use {subdomain}.zendesk.com/api/v2/chat instead. - Old-style HTTP Target webhooks are superseded by the Webhooks API /api/v2/webhooks — migrate any remaining HTTP targets. ⚠️ Recently enforced deprecations + new in 2026 dates per bullet : - OAuth token TTL enforcement live 2026-02-02, announced 2026-01-16 : global external OAuth clients now have default tok… 证据：`skills/zendesk/skill.md`\n- **License**（source_file）：Copyright c 2025 ClawSkills Contributors 证据：`LICENSE`\n- **Playbooks Index**（documentation）：Workflow playbooks are end-to-end guides for multi-system automations. They complement the per-tool skill.md files by defining the orchestration layer: trigger, source of truth, field mapping, idempotency, failure policy, and operational checks. 证据：`playbooks/INDEX.md`\n- **HubSpot Deal Won - Asana Onboarding Kickoff**（documentation）：HubSpot Deal Won - Asana Onboarding Kickoff 证据：`playbooks/hubspot-asana-onboarding.md`\n- **Salesforce Lead - HubSpot Contact Sync**（documentation）：Salesforce Lead - HubSpot Contact Sync 证据：`playbooks/salesforce-hubspot-lead-sync.md`\n- **Slack Incident - Jira Issue**（documentation）：Capture an incident discussion happening in Slack as a tracked Jira issue, so engineering, on-call, and leadership can follow resolution outside the noisy chat surface. The Slack message remains the conversation record; Jira becomes the accountable work item. 证据：`playbooks/slack-jira-incident.md`\n- **Zendesk Ticket - Jira Bug Escalation**（documentation）：Zendesk Ticket - Jira Bug Escalation 证据：`playbooks/zendesk-jira-bug-escalation.md`\n- **Skills Index**（documentation）：A curated library of integration skill documents for the most common SaaS platforms used in go-to-market and operations workflows. Each skill doc teaches an agent or automation builder how to reliably use that platform's API for high-value, production-grade workflows. 证据：`skills/INDEX.md`\n- **Skills Roadmap**（documentation）：This skill set enables end-to-end automation and integration across the most commonly used SaaS platforms in modern go-to-market and operations stacks. Concretely, it allows an agent or automation builder to: 证据：`skills/ROADMAP.md`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"Node16\", \"moduleResolution\": \"Node16\", \"outDir\": \"dist\", \"rootDir\": \"src\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true }, \"include\": \"src\" } 证据：`mcp-server/tsconfig.json`\n- **Codeowners**（source_file）：@Shanksg 证据：`.github/CODEOWNERS`\n- **Dependencies**（source_file）：Environment .env .env.local .env. .local 证据：`.gitignore`\n- **mcp-server/.gitignore**（source_file）：node modules/ dist/ skills/ playbooks/ 证据：`mcp-server/.gitignore`\n- **Dockerfile**（source_file）：FROM node:22-alpine WORKDIR /app COPY skills/ ./skills/ COPY mcp-server/ ./mcp-server/ WORKDIR /app/mcp-server RUN npm ci && npm run build ENV SKILLS DIR=/app/skills CMD \"node\", \"dist/index.js\" 证据：`mcp-server/Dockerfile`\n- **Vitest.Config**（source_file）：import { defineConfig } from \"vitest/config\"; 证据：`mcp-server/vitest.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `mcp-server/README.md`, `mcp-server/package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `mcp-server/README.md`, `mcp-server/package.json`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, skills/INDEX.md\n- **项目结构**：importance `high`\n - source_paths: README.md, playbooks/INDEX.md, skills/INDEX.md\n- **MCP 服务器架构**：importance `high`\n - source_paths: mcp-server/src/index.ts, mcp-server/package.json, mcp-server/README.md\n- **MCP 工具接口**：importance `high`\n - source_paths: mcp-server/src/index.ts, mcp-server/README.md\n- **技能文档结构**：importance `high`\n - source_paths: skills/figma/skill.md, skills/monday/skill.md, skills/github/skill.md\n- **技能目录总览**：importance `high`\n - source_paths: skills/INDEX.md, skills/salesforce/skill.md, skills/hubspot/skill.md, skills/zendesk/skill.md, skills/slack/skill.md\n- **跨工具工作流剧本**：importance `medium`\n - source_paths: playbooks/INDEX.md, playbooks/zendesk-jira-bug-escalation.md, playbooks/hubspot-asana-onboarding.md, playbooks/salesforce-hubspot-lead-sync.md, playbooks/slack-jira-incident.md\n- **部署指南**：importance `high`\n - source_paths: mcp-server/README.md, mcp-server/Dockerfile, mcp-server/package.json\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1161910025 | https://github.com/Shanksg/clawskills | host_targets=mcp_host, claude\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1161910025 | https://github.com/Shanksg/clawskills | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:1161910025 | https://github.com/Shanksg/clawskills | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：Shanksg/clawskills\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在安全注意事项（medium）：用户安装前需要知道权限边界和敏感操作。 建议检查：转成明确权限清单和安全审查提示。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/Shanksg/clawskills 项目说明书\n\n生成时间：2026-05-13 12:47:35 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [项目结构](#page-project-structure)\n- [MCP 服务器架构](#page-mcp-server-architecture)\n- [MCP 工具接口](#page-mcp-tools)\n- [技能文档结构](#page-skill-anatomy)\n- [技能目录总览](#page-skill-catalog)\n- [跨工具工作流剧本](#page-playbooks)\n- [部署指南](#page-deployment)\n- [持续集成与发布](#page-cicd)\n- [贡献指南](#page-contributing)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[项目结构](#page-project-structure), [技能目录总览](#page-skill-catalog)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)\n- [skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n- [skills/jira/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/stripe/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/stripe/skill.md)\n- [skills/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)\n- [skills/servicenow/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/servicenow/skill.md)\n- [skills/dynamics365/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/dynamics365/skill.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# 项目概述\n\n## 项目简介\n\nclawskills 是一个开源的技能文档库（Skills Repository），旨在为 AI 助手提供与主流第三方工具和服务集成的标准化指南。该项目通过结构化的 Markdown 文档，记录了 14 种常用工具的 API 认证方式、速率限制、错误处理和工作流配方，使 AI 代理能够准确、可靠地与这些平台交互。\n\n该项目核心价值在于**降低 AI 集成错误率**。开发者可以引用对应工具的技能文档，让 AI 遵循正确的认证流程、速率限制处理方式和错误代码规范，而非依赖不完整或过时的知识。\n\n资料来源：[README.md:1]()\n\n## 核心架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[clawskills 仓库] --> B[技能文档库 skills/]\n A --> C[剧本库 playbooks/]\n A --> D[MCP 服务器 clawskills-mcp]\n B --> E[14 个工具技能文档]\n E --> E1[Monday.com]\n E --> E2[Salesforce]\n E --> E3[Jira]\n E --> E4[Dynamics 365]\n E --> E5[HubSpot]\n E --> E6[ServiceNow]\n E --> E7[Zendesk]\n E --> E8[Asana]\n E --> E9[GitHub]\n E --> E10[Figma]\n E --> E11[Slack]\n E --> E12[Stripe]\n E --> E13[Notion]\n E --> E14[Linear]\n D --> F[list_skills]\n D --> G[get_skill]\n D --> H[search_skills]\n```\n\n### MCP 服务器工具\n\nclawskills 提供了 MCP（Model Context Protocol）服务器，使 Claude 等 AI 助手能够动态查询技能文档。MCP 服务器提供三个核心工具：\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `list_skills` | 列出所有可用的技能文档 |\n| `get_skill` | 获取完整的技能文档或指定章节（如 `auth`、`rate-limits`、`recipes`、`errors`） |\n| `search_skills` | 在所有技能文档中进行全文搜索 |\n\n资料来源：[README.md:1]()\n\n## 技能文档结构\n\n### 必选章节\n\n每个工具的技能文档（`skill.md`）必须包含 **11 个标准章节**，确保文档的完整性和一致性：\n\n```mermaid\ngraph LR\n A[必选章节] --> B[认证与权限]\n A --> C[核心资源与字段]\n A --> D[速率限制与重试]\n A --> E[错误代码处理]\n A --> F[常见工作流]\n A --> G[最佳实践]\n A --> H[故障排除]\n A --> I[QA 检查清单]\n A --> J[来源链接]\n A --> K[最后验证日期]\n```\n\n资料来源：[README.md:1]()\n\n### 认证模式对比\n\n| 认证方式 | 适用场景 | 代表性工具 |\n|---------|---------|-----------|\n| Personal Access Token (PAT) | 服务器到服务器集成 | Figma、Linear、GitHub |\n| OAuth 2.0 | 用户授权应用 | Figma、Linear、Slack、Stripe |\n| API Key / Bearer Token | 标准 REST API | Jira、ServiceNow、Dynamics 365、HubSpot、Notion、Stripe |\n| 基本认证 (Basic Auth) | 简单场景 | Zendesk |\n\n资料来源：[skills/figma/skill.md:1]()[skills/linear/skill.md:1]()[skills/slack/skill.md:1]()\n\n## 支持的工具列表\n\n### 工具覆盖范围\n\n| 工具名称 | 主要功能 | API 类型 | 关键认证方式 |\n|---------|---------|---------|------------|\n| Monday.com | 项目管理与工作流 | REST | OAuth 2.0 + API Token |\n| Salesforce | CRM 与销售自动化 | REST + OAuth | Connected App |\n| Jira | 敏捷项目与缺陷跟踪 | REST | API Token / OAuth |\n| Dynamics 365 | 企业 ERP/CRM | OData REST | OAuth 2.0 |\n| HubSpot | 营销与 CRM | REST + Webhooks | Private App Token |\n| ServiceNow | IT 服务管理 | REST | OAuth 2.0 / Basic Auth |\n| Zendesk | 客服与支持工单 | REST | API Token |\n| Asana | 团队协作与任务管理 | REST | Personal Access Token |\n| GitHub | 代码托管与 DevOps | REST + GraphQL | Personal Access Token |\n| Figma | 设计与协作 | REST | Personal Access Token / OAuth |\n| Slack | 企业通讯与自动化 | Web API | Bot Token / User Token |\n| Stripe | 支付与订阅管理 | REST + Webhooks | Secret Key |\n| Notion | 文档与知识管理 | REST | Internal Integration Token |\n| Linear | 开发者项目追踪 | GraphQL | API Key / OAuth |\n\n资料来源：[README.md:1]()[skills/ROADMAP.md:1]()\n\n## 工作流程配方\n\n### 跨工具编排示例\n\n项目中包含跨系统的剧本（Playbook），展示如何编排多个工具的集成：\n\n#### Slack-Jira 事故处理剧本\n\n```mermaid\nsequenceDiagram\n participant S as Slack\n participant B as Bot\n participant J as Jira API\n participant L as Linear API\n \n S->>B: 触发事件
(reaction_added / message)\n B->>S: 获取消息 permalink\n B->>J: 搜索关联 Issue\n alt 存在关联 Issue\n B->>S: 回复已有 Issue 链接\n else 无关联 Issue\n B->>J: 创建新 Issue\n B->>S: 回复新 Issue 链接\n end\n```\n\n**字段映射规则：**\n\n| Slack 事件字段 | Jira 相关字段 |\n|---------------|--------------|\n| `event.item.channel` + `event.item.ts` | Correlation Key |\n| 消息文本（首句，截断至 ~120 字符） | Issue Summary |\n| 消息内容 + Thread 回复 | Issue Description |\n| 触发事件的频道 | Issue Project / Components |\n| Slack Permalink | Description 中的链接 |\n\n资料来源：[playbooks/slack-jira-incident.md:1]()\n\n## 开发流程\n\n### 贡献者工作流\n\n```mermaid\ngraph LR\n A[创建分支
git checkout -b skill/] --> B[遵循模板结构
11 个必选章节]\n B --> C[验证端点与速率限制
对照官方文档]\n C --> D[添加 Last validated 日期]\n D --> E[更新 INDEX.md
和 README.md]\n E --> F[添加 Sources 链接]\n F --> G[提交 PR
CI 运行 npm test]\n```\n\n### 分支命名规范\n\n| 分支类型 | 命名格式 | 示例 |\n|---------|---------|-----|\n| 新增工具技能 | `skill/` | `skill/notion` |\n| 功能改进 | `feat/` | `feat/add-vertex-ai` |\n| 文档修复 | `fix/` | `fix/correct-oauth-url` |\n\n资料来源：[README.md:1]()\n\n### CI/CD 流水线\n\n| 阶段 | 触发条件 | 验证内容 |\n|-----|---------|---------|\n| 构建测试 | 每次 Push / PR | `npm test` 执行单元测试 |\n| 技能验证 | PR 提交时 | 必选章节完整性、最小文件大小（≥5 KB）、所有 14 个工具验证 |\n| 发布 | GitHub Actions → Release Workflow | patch / minor / major 版本选择、npm publish |\n\n资料来源：[skills/ROADMAP.md:1]()\n\n## 版本与发布\n\n### 自动化发布\n\n项目使用 GitHub Actions 实现自动化发布流程：\n\n```mermaid\ngraph TD\n A[合并到 main 分支] --> B[手动触发 Release Workflow]\n B --> C{版本类型选择}\n C -->|patch| D[0.0.x 补丁版本]\n C -->|minor| E[0.x.0 次版本]\n C -->|major| F[x.0.0 主版本]\n D --> G[更新版本号]\n E --> G\n F --> G\n G --> H[创建 Git Tag]\n H --> I[npm publish]\n I --> J[生成 Release Notes]\n```\n\n发布流程通过 OIDC（OpenID Connect）身份验证确保安全性，无需存储长期 npm 凭据。\n\n资料来源：[skills/ROADMAP.md:1]()\n\n## 安装与使用\n\n### MCP 服务器安装\n\n**临时使用（npx 方式）：**\n\n```bash\nnpx -y clawskills-mcp\n```\n\n**全局安装：**\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n**Claude Desktop 配置示例：**\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:1]()\n\n### 在项目中使用\n\n开发者可以通过在 `.claude/CLAUDE.md` 文件中配置项目指令，引导 AI 始终使用对应的技能文档：\n\n```markdown\n# Integration Skills\n\n当编写与以下工具集成的代码时，始终先阅读对应技能文档：\n\n- Jira → @skills/jira/skill.md\n- Slack → @skills/slack/skill.md\n- GitHub → @skills/github/skill.md\n- ... 其他工具\n\n遵循文档中的认证模式、速率限制处理和错误代码规范。\n```\n\n资料来源：[README.md:1]()\n\n## 开发路线图\n\n### 当前完成状态\n\n| 阶段 | 主题 | 状态 | 说明 |\n|-----|------|------|------|\n| Phase 1 | 基础（认证 + 核心 CRUD） | ✅ 完成 | 14 个工具全覆盖 |\n| Phase 2 | 高频工作流 | ✅ 完成 | 每个工具 6-12 个配方 |\n| Phase 3 | 事件驱动与实时 | ✅ 完成 | Webhook 设置与签名验证 |\n| Phase 4 | 批量与高级操作 | ⚠️ 部分 | 大多数工具已记录，>500 条记录示例未全部完成 |\n| Phase 5 | 跨工具编排 | ❌ 未开始 | INDEX.md 中有模式描述，无专门配方 |\n\n资料来源：[skills/ROADMAP.md:1]()\n\n### 未来发展方向\n\n**优先级 1 — 内容准确性流水线**\n\n随着供应商 API 持续演进，维护准确性将成为项目核心竞争优势。计划包括：\n\n- 自动化验证官方文档变更\n- 社区贡献审核机制\n- 供应商 API 变更告警系统\n\n资料来源：[skills/ROADMAP.md:1]()\n\n## 项目结构\n\n```\nclawskills/\n├── README.md # 项目主文档\n├── skills/\n│ ├── INDEX.md # 技能索引\n│ ├── ROADMAP.md # 开发路线图\n│ ├── figma/\n│ │ └── skill.md\n│ ├── github/\n│ │ └── skill.md\n│ ├── jira/\n│ │ └── skill.md\n│ ├── linear/\n│ │ └── skill.md\n│ ├── monday/\n│ │ └── skill.md\n│ ├── salesforce/\n│ │ └── skill.md\n│ ├── servicenow/\n│ │ └── skill.md\n│ ├── slack/\n│ │ └── skill.md\n│ ├── stripe/\n│ │ └── skill.md\n│ ├── notion/\n│ │ └── skill.md\n│ ├── dynamics365/\n│ │ └── skill.md\n│ ├── hubspot/\n│ │ └── skill.md\n│ ├── asana/\n│ │ └── skill.md\n│ └── zendesk/\n│ └── skill.md\n├── playbooks/\n│ └── slack-jira-incident.md # 跨工具剧本\n└── .github/\n └── workflows/\n ├── ci.yml # CI 测试流水线\n └── release.yml # 自动化发布\n```\n\n资料来源：[README.md:1]()[skills/ROADMAP.md:1]()\n\n## 许可证与贡献\n\n本项目采用 MIT 许可证开源，完全公开可用。项目欢迎社区贡献，所有贡献者需遵循以下准则：\n\n1. 每个技能文档必须包含全部 11 个必选章节\n2. 所有端点、速率限制和认证流程必须对照官方文档验证\n3. 必须在文档中标注 \"Last validated\" 日期\n4. 必须链接官方来源，禁止无验证的声明\n\n资料来源：[README.md:1]()[skills/ROADMAP.md:1]()\n\n---\n\n\n\n## 项目结构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [MCP 服务器架构](#page-mcp-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n \n\n# 项目结构\n\n## 概述\n\n`clawskills` 是一个技能文档（Skills Documentation）仓库，旨在为 AI 工具提供标准化的第三方 API 集成指南。每个技能文档涵盖单一工具（如 Jira、Figma、Linear）的认证方式、API 端点、速率限制、错误处理和工作流程。\n\n```mermaid\ngraph TD\n A[clawskills 仓库] --> B[skills/ 技能文档]\n A --> C[mcp-server/ MCP服务器]\n A --> D[playbooks/ 工作流剧本]\n \n B --> B1[figma/skill.md]\n B --> B2[jira/skill.md]\n B --> B3[linear/skill.md]\n B --> B14[... 共14个工具]\n \n C --> C1[src/index.ts]\n C --> C2[src/index.test.ts]\n \n D --> D1[zendesk-jira-bug-escalation.md]\n D --> D2[hubspot-asana-onboarding.md]\n```\n\n## 目录结构\n\n```\nclawskills/\n├── README.md # 仓库主文档\n├── package.json # npm 包配置\n├── skills/ # 技能文档目录\n│ ├── INDEX.md # 技能索引\n│ ├── ROADMAP.md # 开发路线图\n│ ├── figma/skill.md # Figma 技能文档\n│ ├── github/skill.md # GitHub 技能文档\n│ ├── hubspot/skill.md # HubSpot 技能文档\n│ ├── jira/skill.md # Jira 技能文档\n│ ├── linear/skill.md # Linear 技能文档\n│ ├── monday/skill.md # Monday.com 技能文档\n│ ├── notion/skill.md # Notion 技能文档\n│ ├── salesforce/skill.md # Salesforce 技能文档\n│ ├── servicenow/skill.md # ServiceNow 技能文档\n│ ├── slack/skill.md # Slack 技能文档\n│ ├── stripe/skill.md # Stripe 技能文档\n│ ├── zendesk/skill.md # Zendesk 技能文档\n│ ├── asana/skill.md # Asana 技能文档\n│ └── dynamics365/skill.md # Dynamics 365 技能文档\n├── playbooks/ # 工作流剧本目录\n│ ├── INDEX.md # 剧本索引\n│ ├── zendesk-jira-bug-escalation.md\n│ └── hubspot-asana-onboarding.md\n└── mcp-server/ # MCP 服务器实现\n ├── README.md # MCP 服务器文档\n ├── package.json # MCP 服务包配置\n └── src/\n ├── index.ts # 主服务器逻辑\n └── index.test.ts # 单元测试\n```\n\n## 技能文档结构（skill.md）\n\n每个工具的技能文档都遵循统一的 11 节模板结构，确保一致性和完整性。资料来源：[skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n\n| 章节 | 用途 |\n|------|------|\n| Overview | 工具简介、认证前置条件 |\n| Authentication & permissions | 认证方式、权限范围 |\n| Reliability: rate limits, retries, idempotency | 速率限制、重试策略 |\n| Error handling & troubleshooting | 错误码、调试技巧 |\n| Common workflows (recipes) | 常用 API 调用模式（6-12 个） |\n| Webhooks | 事件订阅、签名验证 |\n| Available tools / API endpoints | 端点清单 |\n| Data model: entities & fields | 数据实体、字段说明 |\n| Pagination | 分页方式 |\n| Code samples | 代码示例 |\n| Resources & references | 官方文档链接 |\n\n### 技能覆盖的工具\n\n仓库目前包含 **14 个主要工具**的技能文档：\n\n| 工具 | 主要功能 |\n|------|----------|\n| Figma | 设计协作、组件导出 |\n| GitHub | 代码仓库、Issue、PR |\n| HubSpot | CRM、营销自动化 |\n| Jira | 项目追踪、Bug 管理 |\n| Linear | 敏捷项目管理 |\n| Monday.com | 团队协作 |\n| Notion | 文档、知识库 |\n| Salesforce | 企业 CRM |\n| ServiceNow | IT 服务管理 |\n| Slack | 团队通讯 |\n| Stripe | 支付处理 |\n| Zendesk | 客服工单 |\n| Asana | 任务管理 |\n| Dynamics 365 | 微软企业套件 |\n\n## MCP 服务器架构\n\nMCP（Model Context Protocol）服务器是 Claude AI 与技能文档之间的桥梁，允许 AI 动态查询技能信息。资料来源：[mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n```mermaid\ngraph LR\n A[Claude AI] -->|list_skills| B[MCP 服务器]\n A -->|get_skill| B\n A -->|search_skills| B\n A -->|list_playbooks| B\n A -->|get_playbook| B\n A -->|search_playbooks| B\n \n B -->|读取| C[skills/*.md]\n B -->|读取| D[playbooks/*.md]\n \n B -->|JSON响应| A\n```\n\n### MCP 工具接口\n\n| 工具名 | 功能 |\n|--------|------|\n| `list_skills` | 列出所有可用技能 |\n| `get_skill` | 获取完整技能文档或指定章节 |\n| `search_skills` | 全文搜索技能文档 |\n| `list_playbooks` | 列出所有工作流剧本 |\n| `get_playbook` | 获取指定剧本内容 |\n| `search_playbooks` | 搜索剧本内容 |\n| `search_clawskills` | 全局搜索 |\n\n资料来源：[mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n\n### 技能加载机制\n\n```typescript\n// 从 skills/ 目录加载所有 .md 文件\nfunction loadSkills(skillsDir: string): Map {\n const skills = new Map();\n const entries = fs.readdirSync(skillsDir, { withFileTypes: true });\n for (const entry of entries) {\n if (!entry.isFile() || !entry.name.endsWith(\".md\") || entry.name === \"INDEX.md\") continue;\n const slug = entry.name.replace(/\\.md$/, \"\");\n const content = fs.readFileSync(path.join(skillsDir, entry.name), \"utf-8\");\n skills.set(slug, content);\n }\n return skills;\n}\n```\n\n资料来源：[mcp-server/src/index.ts:1-15](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n## 剧本（Playbooks）\n\n剧本是跨工具的工作流集成方案，串联多个工具的 API 实现复杂业务场景。资料来源：[playbooks/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/INDEX.md)\n\n### 当前剧本\n\n| 剧本名称 | 描述 |\n|----------|------|\n| `zendesk-jira-bug-escalation` | Zendesk 工单自动升级到 Jira Bug |\n| `hubspot-asana-onboarding` | HubSpot 联系人同步到 Asana 任务 |\n\n### 剧本搜索功能\n\n剧本支持以下搜索参数：\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `query` | string | 是 | 搜索词，如 \"idempotency\"、\"rollback\"、\"closed won\" |\n\n## 开发流程与贡献规范\n\n### 添加新技能的流程\n\n1. **创建分支**：`git checkout -b skill/`\n2. **遵循模板**：参照现有 `skill.md` 的 11 节结构\n3. **验证准确性**：对照官方文档确认端点、速率限制和认证流程\n4. **添加验证日期**：在文档头部添加 `Last validated:` 日期\n5. **更新索引**：修改 `skills/INDEX.md` 和 `README.md`\n6. **引用来源**：在 `Sources` 章节提供官方文档链接\n7. **提交 PR**：CI 会运行 `npm test` 验证格式\n\n### 质量保证\n\n| 测试项 | 说明 |\n|--------|------|\n| 技能加载测试 | 所有 14 个工具技能必须可加载 |\n| 摘要行检查 | 每个技能必须有非空摘要 |\n| 章节完整性 | 必须包含全部 11 个必需章节 |\n| 文件大小 | 每个技能文件至少 5KB |\n\n```typescript\nit(\"every skill file is at least 5KB\", () => {\n for (const [slug, content] of skills.entries()) {\n expect(content.length, `${slug}: suspiciously short skill file`)\n .toBeGreaterThan(5000);\n }\n});\n```\n\n资料来源：[mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n\n## 发布与自动化\n\n### 发布流程\n\n1. 合并 PR 到 `main` 分支\n2. 进入 GitHub Actions → **Release** 工作流\n3. 点击 \"Run workflow\"\n4. 选择版本类型：`patch` / `minor` / `major`\n\n### CI/CD 流水线\n\n| 组件 | 功能 |\n|------|------|\n| `ci.yml` | 构建 + 测试（每次 push/PR） |\n| `release.yml` | 版本发布、npm 包发布（通过 OIDC） |\n\n资料来源：[skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n## 章节别名系统\n\nMCP 服务器支持灵活的章节查询，使用别名快速定位内容：\n\n| 别名 | 对应章节 |\n|------|----------|\n| `auth` / `authentication` | Authentication & permissions |\n| `rate-limits` / `rate_limits` / `ratelimits` / `reliability` | Reliability: rate limits, retries, idempotency |\n| `errors` / `error-handling` | Error handling & troubleshooting |\n| `recipes` | Common workflows |\n| `pagination` | Pagination |\n| `webhooks` | Webhooks |\n| `overview` | Overview |\n| `fields` | Data model: entities & fields |\n\n资料来源：[mcp-server/src/index.ts:60-80](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n## 使用方式\n\n### MCP 服务器安装\n\n```bash\n# 临时使用\nnpx -y clawskills-mcp\n\n# 永久安装\nnpm install -g clawskills-mcp\n```\n\n### Claude Desktop 配置\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n\n\n## MCP 服务器架构\n\n### 相关页面\n\n相关主题：[MCP 工具接口](#page-mcp-tools), [项目结构](#page-project-structure)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)\n- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n \n\n# MCP 服务器架构\n\n## 1. 概述\n\n`clawskills-mcp` 是一个基于 **Model Context Protocol (MCP)** 的服务器实现，用于将 [ClawSkills](https://github.com/Shanksg/clawskills) 项目中的 API 集成技能文档以结构化的方式暴露给 AI agents。\n\n### 1.1 核心定位\n\n该 MCP 服务器充当 AI 代理与外部 API 集成文档之间的桥梁，使 AI 工具（如 Claude Desktop、Claude Code）能够动态获取 14 个工具的认证流程、速率限制、错误处理和工作流配方等关键信息。资料来源：[mcp-server/README.md:1-10]()\n\n### 1.2 解决的问题\n\n在 AI 编码助手执行跨平台集成任务时，传统的静态提示词方式难以保持 API 文档的时效性。MCP 服务器通过以下方式解决此问题：\n\n- 提供动态查询接口，实时获取最新的 API 技能文档\n- 支持全文检索，快速定位特定 API 端点或错误处理方案\n- 解耦文档维护与 AI 推理逻辑，便于独立更新 API 文档\n\n## 2. 系统架构\n\n### 2.1 架构分层\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n A[Claude Desktop]\n B[Claude Code]\n C[其他 MCP 客户端]\n end\n \n subgraph \"MCP 协议层\"\n D[MCP 协议处理器]\n end\n \n subgraph \"clawskills-mcp 服务器\"\n E[工具路由]\n F[文档加载器]\n G[全文索引]\n end\n \n subgraph \"数据层\"\n H[skills/\\*.md 技能文档]\n I[playbooks/\\*.md 工作流文档]\n J[skills/INDEX.md 索引]\n end\n \n A --> D\n B --> D\n C --> D\n D --> E\n E --> F\n E --> G\n F --> H\n F --> I\n G --> J\n```\n\n### 2.2 核心组件\n\n| 组件 | 职责 | 文件位置 |\n|------|------|----------|\n| MCP 协议处理器 | 解析客户端请求，序列化和反序列化消息 | `mcp-server/src/` |\n| 工具路由 | 根据工具名称分发请求到对应处理器 | `mcp-server/src/index.ts` |\n| 文档加载器 | 读取和解析 Markdown 格式的技能文档 | `mcp-server/src/` |\n| 全文索引 | 建立和维护文档内容的搜索索引 | `mcp-server/src/` |\n\n## 3. 安装与部署\n\n### 3.1 环境要求\n\n| 要求 | 规格 |\n|------|------|\n| Node.js | >= 18.0.0 |\n| 包管理器 | npm |\n| 容器运行时 | Docker（可选） |\n\n资料来源：[mcp-server/package.json]()\n\n### 3.2 安装方式对比\n\n| 方式 | 命令 | 适用场景 |\n|------|------|----------|\n| npx 即时运行 | `npx -y clawskills-mcp` | 临时使用、快速测试 |\n| 全局安装 | `npm install -g clawskills-mcp` | 长期使用、命令行调用 |\n| Docker 容器 | `docker build -t clawskills-mcp -f mcp-server/Dockerfile .` | 生产环境隔离部署 |\n\n资料来源：[mcp-server/README.md:27-42]()\n\n### 3.3 Docker 部署流程\n\n```bash\n# 1. 从仓库根目录构建镜像\ndocker build -t clawskills-mcp -f mcp-server/Dockerfile .\n\n# 2. 运行容器\ndocker run --rm -i clawskills-mcp\n```\n\nDocker 方式确保了与宿主机环境的隔离，适合在生产环境中部署。\n\n## 4. 客户端配置\n\n### 4.1 Claude Desktop 配置\n\n**配置文件路径：**\n\n| 操作系统 | 路径 |\n|----------|------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n\n**配置结构：**\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[mcp-server/README.md:14-21]()\n\n### 4.2 Claude Code 配置\n\n| 作用域 | 配置文件位置 |\n|--------|--------------|\n| 项目级别 | `.claude/settings.json` |\n| 全局级别 | `~/.claude/settings.json` |\n\n配置格式与 Claude Desktop 相同，均使用 `mcpServers` 配置块。\n\n## 5. 工具 API\n\nMCP 服务器暴露以下四个核心工具：\n\n### 5.1 工具总览\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `list_skills` | 列出所有可用的技能文档 slug 及其描述 |\n| `get_skill` | 获取完整的技能文档或指定章节内容 |\n| `search_skills` | 在所有技能文档中执行全文搜索 |\n| `list_playbooks` | 列出可用的跨工具工作流文档 |\n\n资料来源：[mcp-server/README.md:44-49]()\n\n### 5.2 list_skills\n\n列出所有已注册的 API 集成技能。\n\n**返回结构：**\n\n```json\n{\n \"skills\": [\n {\n \"slug\": \"jira\",\n \"description\": \"Jira Cloud API integration guide\"\n },\n {\n \"slug\": \"slack\",\n \"description\": \"Slack Web API and Events API integration\"\n }\n ]\n}\n```\n\n### 5.3 get_skill\n\n获取指定技能文档的完整内容或特定部分。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `slug` | string | 是 | 技能文档标识符 |\n| `section` | string | 否 | 指定章节名称（如 `auth`、`rate-limits`） |\n\n**section 参数可选值：**\n\n| 章节标识 | 对应内容 |\n|----------|----------|\n| `auth` | 认证方式与权限配置 |\n| `rate-limits` | API 速率限制与重试策略 |\n| `errors` | 错误码与故障排查 |\n| `recipes` | 常见工作流配方 |\n\n资料来源：[mcp-server/README.md:44-49]()\n\n### 5.4 search_skills\n\n跨所有技能文档执行全文检索。\n\n**使用场景：**\n- 查找特定错误码的处理方案\n- 搜索某个 API 端点的使用方法\n- 发现所有涉及某项权限的文档\n\n### 5.5 list_playbooks\n\n列出跨工具自动化工作流文档。\n\n**当前支持的 Playbook：**\n\n| Playbook | 功能描述 |\n|----------|----------|\n| `slack-jira-incident` | Slack 消息触发 Jira 事件创建的自动化流程 |\n\n资料来源：[playbooks/slack-jira-incident.md]()\n\n## 6. 数据流与请求处理\n\n### 6.1 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant C as Claude 客户端\n participant M as MCP 服务器\n participant D as 文档系统\n participant I as 索引系统\n\n C->>M: MCP 请求 (工具名 + 参数)\n M->>M: 解析请求 JSON\n alt list_skills / list_playbooks\n M->>D: 加载索引文件\n D-->>M: 返回项目列表\n else get_skill\n M->>D: 定位技能文档\n D-->>M: 返回文档内容\n alt 指定 section\n M->>M: 提取章节内容\n end\n else search_skills\n M->>I: 执行全文搜索\n I-->>M: 返回匹配结果\n end\n M-->>C: 返回结果 JSON\n```\n\n### 6.2 技能文档结构\n\n每个技能文档（`skills//skill.md`）遵循统一的 11 节结构：\n\n| 章节 | 内容 |\n|------|------|\n| 头部元数据 | API 版本、最后验证日期 |\n| 认证与权限 | OAuth、PAT、API Key 等认证方式 |\n| 基础端点 | 核心 API 端点说明 |\n| 常见工作流 | 5-12 个可复制的配方 |\n| 速率限制 | 请求限额与复杂度计算 |\n| 错误处理 | 错误码与故障排查 |\n| Webhook 配置 | 事件订阅与签名验证 |\n| 批量操作 | 大数据量处理模式 |\n| 安全与合规 | 隐私保护建议 |\n\n资料来源：[skills/notion/skill.md](), [skills/figma/skill.md]()\n\n## 7. 支持的 API 集成\n\n### 7.1 技能库覆盖\n\n当前 ClawSkills 包含 **14 个工具**的完整 API 集成文档：\n\n| 工具 | 主要功能 |\n|------|----------|\n| Monday.com | 项目管理、看板操作 |\n| Salesforce | CRM 自动化 |\n| Jira | 敏捷项目管理、缺陷追踪 |\n| Dynamics 365 | 企业资源规划 |\n| HubSpot | 营销自动化 |\n| ServiceNow | IT 服务管理 |\n| Zendesk | 客户支持 |\n| Asana | 团队协作 |\n| GitHub | 代码托管与 CI/CD |\n| Figma | 设计协作 |\n| Slack | 团队通讯 |\n| Stripe | 支付处理 |\n| Notion | 知识管理 |\n| Linear | 开发者项目管理 |\n\n资料来源：[mcp-server/README.md:4-7]()\n\n### 7.2 跨工具编排\n\nPhase 5（跨工具编排）处于规划阶段，计划实现多系统联动工作流，例如：\n\n```mermaid\ngraph LR\n A[Slack 告警] --> B{事件分类}\n B -->|安全事件| C[创建 Jira Bug]\n B -->|客户投诉| D[创建 Zendesk 工单]\n C --> E[通知 Slack 频道]\n D --> E\n```\n\n## 8. 错误处理与调试\n\n### 8.1 常见配置错误\n\n| 症状 | 原因 | 解决方案 |\n|------|------|----------|\n| MCP 服务器未启动 | npx 缓存问题 | 添加 `-y` 参数强制重新下载 |\n| 工具调用超时 | 网络问题或文档过大 | 检查网络连接 |\n| 搜索无结果 | 索引未更新 | 确认文档已正确放置在 `skills/` 目录 |\n\n### 8.2 日志记录\n\nMCP 服务器应在 DEBUG 模式下记录以下信息：\n\n| 日志级别 | 记录内容 |\n|----------|----------|\n| INFO | 工具调用、文档加载成功 |\n| WARN | 部分文档缺失、搜索结果为空 |\n| ERROR | MCP 协议解析失败、文件系统错误 |\n\n## 9. 安全考虑\n\n### 9.1 敏感信息处理\n\n| 信息类型 | 处理建议 |\n|----------|----------|\n| API Token | 不记录在日志中 |\n| 用户数据 | 脱敏处理后再输出 |\n| 错误详情 | 仅返回给授权客户端 |\n\n### 9.2 权限控制\n\nMCP 服务器本身不实现额外的访问控制，权限管理依赖于：\n- Claude 客户端的认证机制\n- 操作系统层面的文件系统权限\n- Docker 容器的网络隔离策略\n\n## 10. 维护与更新\n\n### 10.1 文档更新流程\n\n```mermaid\ngraph LR\n A[更新 skill.md] --> B[添加 Last validated 日期]\n B --> C[更新 skills/INDEX.md]\n C --> D[提交 PR]\n D --> E[CI 验证]\n E --> F[合并到 main]\n F --> G[自动发布新版本]\n```\n\n### 10.2 CI/CD 自动化\n\n| 阶段 | 工具 | 验证内容 |\n|------|------|----------|\n| 构建 | GitHub Actions | 依赖安装、类型检查 |\n| 测试 | Vitest | 单元测试 + 文档结构验证 |\n| 发布 | release.yml | 版本号递增、npm 发布 |\n\n资料来源：[skills/ROADMAP.md]()\n\n## 11. 扩展指南\n\n### 11.1 添加新技能\n\n1. 创建分支：`git checkout -b skill/`\n2. 遵循模板结构创建 `skill.md`，确保包含全部 11 个章节\n3. 验证所有端点、速率限制和认证流程\n4. 更新 `skills/INDEX.md` 和 `README.md`\n5. 提交 PR 触发 CI 验证\n\n### 11.2 添加新工具至 MCP 服务器\n\n在 `mcp-server/src/index.ts` 中注册新的工具处理器：\n\n```typescript\nimport { getSkill, searchSkills } from './handlers';\n\n// 新增工具注册\nserver.registerTool('get_skill', getSkill);\nserver.registerTool('search_skills', searchSkills);\n```\n\n## 12. 参考资料\n\n| 资料 | 链接 |\n|------|------|\n| GitHub 仓库 | https://github.com/Shanksg/clawskills |\n| MCP 服务器源码 | `mcp-server/src/index.ts` |\n| npm 包 | `clawskills-mcp` |\n| 技能索引 | `skills/INDEX.md` |\n\n---\n\n\n\n## MCP 工具接口\n\n### 相关页面\n\n相关主题：[MCP 服务器架构](#page-mcp-server-architecture), [技能文档结构](#page-skill-anatomy)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n \n\n# MCP 工具接口\n\n## 概述\n\nMCP（Model Context Protocol）工具接口是 clawskills 项目为 AI 助手提供的标准化工具集，允许 Claude 等 AI 工具直接调用技能文档库中的内容。通过 MCP 协议，AI 可以在对话过程中实时获取各种第三方服务的集成指南、API 文档和工作流配方。\n\nMCP 工具接口是 clawskills 项目与 AI 运行时之间的桥梁，提供了三大核心能力：\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `list_skills` | 列出所有可用的技能文档 |\n| `get_skill` | 获取完整技能文档或特定章节 |\n| `search_skills` | 全文本搜索所有技能文档 |\n\n资料来源：[README.md:1-100]()\n\n## 架构设计\n\n### MCP 服务器角色\n\nclawskills 的 MCP 服务器封装了对技能文档库的访问逻辑，作为中间层将 AI 的自然语言请求转换为结构化的文档查询。其核心职责包括：\n\n1. **技能发现** — 维护技能索引，支持按名称或分类列出所有可用工具\n2. **内容检索** — 按需加载完整的技能文档或指定章节\n3. **全文搜索** — 跨所有技能文档执行关键词匹配\n\n```mermaid\ngraph TD\n A[Claude AI] -->|MCP Protocol| B[clawskills-mcp Server]\n B --> C{请求类型}\n C -->|list_skills| D[skills/INDEX.md]\n C -->|get_skill| E[skills/{tool}/skill.md]\n C -->|search_skills| F[全文索引]\n D --> G[技能列表响应]\n E --> H[完整文档/章节响应]\n F --> I[搜索结果响应]\n G --> A\n H --> A\n I --> A\n```\n\n### 工具与技能的映射关系\n\nMCP 工具与底层技能文档的对应关系如下：\n\n| MCP 工具 | 底层资源 | 返回内容 |\n|---------|---------|---------|\n| `list_skills` | `skills/INDEX.md` | 所有技能的索引列表 |\n| `get_skill` | `skills/{tool}/skill.md` | 指定工具的完整文档 |\n| `search_skills` | 所有 `skill.md` 文件 | 匹配的技能文档片段 |\n\n资料来源：[README.md:80-90]()\n\n## 安装与配置\n\n### 临时运行方式\n\n使用 npx 直接运行，无需本地安装：\n\n```bash\nnpx -y clawskills-mcp\n```\n\n### 全局安装方式\n\n将 MCP 服务器安装为全局 npm 包：\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n### Claude Desktop 配置\n\n在 Claude Desktop 的配置文件中添加 MCP 服务器连接：\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n### Claude Code 配置\n\n对于 Claude Code 项目，可在 `.claude/CLAUDE.md` 中配置为项目级指令：\n\n```markdown\n# Integration Skills\n\n当编写与以下工具集成的代码时，始终在编写代码前阅读对应的技能文档：\n\n- Monday.com → @skills/monday/skill.md\n- Salesforce → @skills/salesforce/skill.md\n- Jira → @skills/jira/skill.md\n- HubSpot → @skills/hubspot/skill.md\n- Zendesk → @skills/zendesk/skill.md\n- GitHub → @skills/github/skill.md\n- Figma → @skills/figma/skill.md\n- Slack → @skills/slack/skill.md\n- Stripe → @skills/stripe/skill.md\n- Notion → @skills/notion/skill.md\n- Linear → @skills/linear/skill.md\n```\n\n资料来源：[README.md:95-115]()\n\n## 三大核心工具详解\n\n### list_skills — 技能列表\n\n列出所有已注册的技能文档，AI 可据此了解项目支持的集成范围。\n\n**使用场景：**\n- 探索项目能力边界\n- 在不确定具体工具时浏览可用选项\n- 验证特定工具是否在支持列表中\n\n### get_skill — 技能获取\n\n获取指定技能的完整文档或特定章节。支持的章节筛选包括：\n\n| 章节标识 | 内容范围 |\n|---------|---------|\n| `auth` | 认证与授权流程 |\n| `rate-limits` | 速率限制说明 |\n| `recipes` | 工作流配方 |\n| `errors` | 错误代码与处理 |\n\n**使用场景：**\n- 在开始集成前获取完整认证指南\n- 调试时查阅特定错误代码含义\n- 提取特定工作流配方\n\n### search_skills — 全文搜索\n\n跨所有技能文档执行关键词搜索，返回匹配结果。\n\n**使用场景：**\n- 快速定位包含特定 API 端点的技能\n- 搜索特定错误消息的解决方案\n- 查找包含特定认证机制的文档\n\n## 支持的工具生态\n\n当前 MCP 接口覆盖以下 14 种第三方工具：\n\n| 类别 | 支持的工具 |\n|------|-----------|\n| 项目管理 | Jira, Asana, Monday.com, Linear, Notion |\n| 客户关系 | Salesforce, HubSpot, Zendesk |\n| 开发协作 | GitHub, Figma |\n| 通信 | Slack |\n| 支付 | Stripe |\n| 企业系统 | Dynamics 365, ServiceNow |\n\n资料来源：[skills/ROADMAP.md:1-50]()\n\n## 开发阶段与路线图\n\n根据项目路线图，MCP 工具接口已实现以下阶段：\n\n| 阶段 | 内容 | 状态 |\n|------|------|------|\n| Phase 1 — 基础 | 认证流、基本 CRUD、重试模式 | ✅ 完成 |\n| Phase 2 — 高频工作流 | 每个工具 6-12 个配方 | ✅ 完成 |\n| Phase 3 — 事件驱动 | Webhook 设置、签名验证、事件处理 | ✅ 完成 |\n| Phase 4 — 批量操作 | 批量 API、大容量模式 | ⚠️ 部分完成 |\n| Phase 5 — 跨工具编排 | 跨 2+ 工具的多系统配方 | ❌ 未开始 |\n\n资料来源：[skills/ROADMAP.md:50-80]()\n\n### 未来发展方向\n\n**优先级 1 — 新鲜度与准确性管道**\n\n核心 14 工具库建立后的下一步是确保文档随供应商 API 变化保持准确：\n\n- **Phase A** — 建立文档变更检测机制\n- **Phase B** — 自动化验证与测试\n- **Phase C** — 社区驱动的更新流程\n\n资料来源：[skills/ROADMAP.md:80-100]()\n\n## 最佳实践\n\n### 在提示词中引用技能文档\n\n| 目标 | 提示词结构 |\n|------|-----------|\n| 引用特定章节 | 粘贴目标章节内容，明确说明用途 |\n| 完整技能作为上下文 | 将技能文档加载为系统提示词的一部分 |\n\n**示例：**\n\n```\n[粘贴 skills/salesforce/skill.md 中的\"Authentication & permissions\"章节]\n\n基于以上内容，编写一个将 JWT 兑换为访问令牌并缓存至过期前 5 分钟的 Python 函数。\n```\n\n### 遵循文档规范\n\n使用 MCP 工具获取的技能文档时，应严格遵循其中的：\n- 认证模式\n- 速率限制处理\n- 错误代码处理\n- API 版本标头要求\n\n## 持续集成与发布\n\n项目维护以下自动化流程：\n\n| 组件 | 功能 | 状态 |\n|------|------|------|\n| `ci.yml` | 每次 push/PR 触发构建与测试 | ✅ 运行中 |\n| `release.yml` | 手动触发版本发布、npm 发布 | ✅ 运行中 |\n| 测试套件 | Vitest 单元测试 + 真实技能验证 | ✅ 运行中 |\n\n版本号遵循语义化版本（patch/minor/major），发布流程通过 GitHub Actions 手动触发。\n\n资料来源：[skills/ROADMAP.md:20-30]()\n\n## 相关资源\n\n- NPM 包：`clawskills-mcp`\n- MCP 协议版本：Model Context Protocol 标准\n- 技能文档路径：`skills/{toolname}/skill.md`\n- 索引文件：`skills/INDEX.md`\n\n---\n\n\n\n## 技能文档结构\n\n### 相关页面\n\n相关主题：[技能目录总览](#page-skill-catalog), [MCP 工具接口](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)\n- [skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n- [skills/jira/skill.md](https://github.com/Shanksg/Shanksg/clawskills/blob/main/skills/jira/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# 技能文档结构\n\n## 概述\n\n技能文档（Skill Documentation）是 clawskills 项目的核心资产，为 14 种主流工具和平台提供标准化的 API 集成指南。这些文档采用统一模板编写，包含身份验证、速率限制、常见工作流、错误处理等 11 个必填章节，确保 AI 代理能够准确、可靠地与外部系统交互。\n\n技能文档的主要作用包括：\n\n- 为 AI 代理提供可信赖的集成参考\n- 标准化跨平台的 API 调用模式\n- 降低集成错误率和开发时间\n- 支持 RAG（检索增强生成）流程\n\n资料来源：[README.md:1-20](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 文档模板结构\n\n### 必填章节清单\n\n每个技能文档必须包含以下 11 个章节，CI 测试会验证所有章节的完整性：\n\n| 章节编号 | 章节名称 | 说明 |\n|---------|---------|------|\n| 1 | 概述 | 工具简介、API 版本、基础 URL |\n| 2 | 身份验证与权限 | 认证方式、OAuth 流程、令牌管理 |\n| 3 | 速率限制 | 请求配额、重试策略、复杂度过载 |\n| 4 | 核心 API 端点 | 主要接口列表及参数说明 |\n| 5 | 常见工作流（Recipes） | 典型使用场景的代码示例 |\n| 6 | Webhook 配置 | 事件订阅、签名验证、负载结构 |\n| 7 | 错误处理 | 错误代码分类、异常处理模式 |\n| 8 | 安全与隐私 | 最佳实践、合规要求 |\n| 9 | 相关资源 | 官方文档链接、示例代码 |\n| 10 | 变更日志 | 版本历史、breaking changes |\n| 11 | 维护指南 | 文档更新流程、验证要求 |\n\n资料来源：[mcp-server/src/index.test.ts:1-30](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n\n### 文档质量标准\n\n```\n┌─────────────────────────────────────────────┐\n│ 技能文档质量检查 │\n├─────────────────────────────────────────────┤\n│ ✓ 所有 11 个必填章节完整 │\n│ ✓ 摘要行非空 │\n│ ✓ 文件大小 ≥ 5KB（内容充实度） │\n│ ✓ 端点、速率限制、认证流程经官方文档验证 │\n│ ✓ 包含 Last validated 日期 │\n│ ✓ 链接到官方 Sources 章节 │\n└─────────────────────────────────────────────┘\n```\n\n资料来源：[README.md:25-35](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 技能库组织架构\n\n### 目录结构\n\n```\nclawskills/\n├── skills/\n│ ├── INDEX.md # 技能总索引\n│ ├── ROADMAP.md # 路线图和开发阶段\n│ ├── asana/\n│ │ └── skill.md\n│ ├── dynamics365/\n│ │ └── skill.md\n│ ├── figma/\n│ │ └── skill.md\n│ ├── github/\n│ │ └── skill.md\n│ ├── hubspot/\n│ │ └── skill.md\n│ ├── jira/\n│ │ └── skill.md\n│ ├── linear/\n│ │ └── skill.md\n│ ├── monday/\n│ │ └── skill.md\n│ ├── notion/\n│ │ └── skill.md\n│ ├── salesforce/\n│ │ └── skill.md\n│ ├── servicenow/\n│ │ └── skill.md\n│ ├── slack/\n│ │ └── skill.md\n│ ├── stripe/\n│ │ └── skill.md\n│ └── zendesk/\n│ └── skill.md\n├── playbooks/ # 跨工具编排手册\n│ └── slack-jira-incident.md\n└── mcp-server/ # MCP 服务端实现\n```\n\n资料来源：[skills/ROADMAP.md:1-50](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n### 覆盖的工具\n\n| 类别 | 工具 | 协议类型 |\n|------|------|----------|\n| 项目管理 | Jira, Linear, Monday.com, Asana | REST API / GraphQL |\n| CRM/销售 | Salesforce, HubSpot, Dynamics 365 | REST API |\n| 客服 | Zendesk, ServiceNow | REST API |\n| 开发工具 | GitHub | REST API |\n| 设计协作 | Figma | REST API |\n| 消息 | Slack | Web API / WebSocket |\n| 支付 | Stripe | REST API |\n| 知识管理 | Notion | REST API |\n\n---\n\n## 章节内容详解\n\n### 1. 身份验证与权限（Authentication & Permissions）\n\n此章节描述与工具交互所需的认证机制，包括 API Key、OAuth 2.0、JWT 等方式。\n\n**典型认证模式：**\n\n| 认证方式 | 适用场景 | Token 位置 |\n|---------|---------|-----------|\n| API Key / PAT | 服务器到服务器集成 | Header: `Authorization: Bearer xxx` |\n| OAuth 2.0 | 用户授权应用 | 先获取 code，再兑换 access_token |\n| JWT | 服务账户 | 请求体或专用端点 |\n| HMAC 签名 | Webhook 验证 | 请求头特定字段 |\n\n**Figma 示例：**\n```bash\n# Personal Access Token\ncurl https://api.figma.com/v1/me \\\n -H \"X-Figma-Token: YOUR_PAT\"\n```\n\n**Linear 示例：**\n```bash\ncurl -X POST https://api.linear.app/oauth/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=refresh_token&refresh_token=&client_id=&client_secret=\"\n```\n\n资料来源：[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)\n\n### 2. 速率限制（Rate Limits）\n\n每个技能文档记录平台特定的速率限制策略。\n\n**速率限制信息表结构：**\n\n| 维度 | 说明 |\n|------|------|\n| 请求配额 | 每小时/每分钟允许的请求数 |\n| 复杂度过载 | 基于查询复杂度的积分限制 |\n| 突发限制 | 短期峰值容忍 |\n| 响应头 | 返回剩余配额、重试时间 |\n\n**Linear 速率限制示例：**\n\n| 认证类型 | 请求/小时 | 复杂度积分/小时 | 单次查询最大积分 |\n|---------|----------|----------------|-----------------|\n| API key | 5,000 | 250,000 | 10,000 |\n| OAuth app | 5,000 | 2,000,000 | 10,000 |\n| 未认证 | 60 | 10,000 | 10,000 |\n\n**响应头字段：**\n\n| Header | 描述 |\n|--------|------|\n| `X-RateLimit-Requests-Limit` | 时间窗口内允许的总请求数 |\n| `X-RateLimit-Complexity-Limit` | 复杂度积分上限 |\n| `Retry-After` | 需要等待的秒数 |\n\n资料来源：[skills/linear/skill.md:50-70](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n\n### 3. 常见工作流（Recipes）\n\nRecipes 提供针对典型使用场景的完整代码示例，通常包含：\n\n- 场景描述\n- 所需权限范围\n- 完整可运行的代码片段\n- 错误处理模式\n\n**工作流类型分类：**\n\n```mermaid\ngraph TD\n A[Recipes 工作流] --> B[CRUD 操作]\n A --> C[查询与过滤]\n A --> D[Webhook 配置]\n A --> E[批量操作]\n A --> F[跨系统编排]\n \n B --> B1[创建资源]\n B --> B2[读取详情]\n B --> B3[更新字段]\n B --> B4[删除归档]\n```\n\n**Jira Recipe 示例：**\n```bash\ncurl -s -X PUT \"$BASE/rest/api/3/issue/PROJ-42\" \\\n -H \"Authorization: $AUTH\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"fields\": {\n \"labels\": [\"production\", \"urgent\"]\n }\n }'\n```\n\n资料来源：[skills/jira/skill.md:80-100](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)\n\n### 4. Webhook 配置\n\nWebhook 章节描述事件订阅机制、签名验证和负载结构。\n\n**Webhook 组件：**\n\n| 组件 | 描述 |\n|------|------|\n| 端点注册 | 创建 webhook 的 API 调用 |\n| 事件类型 | 可订阅的事件列表 |\n| 签名验证 | HMAC/SHA256 验证方法 |\n| 负载结构 | 请求体字段说明 |\n\n**Slack Webhook 安全配置：**\n```python\nimport hmac, hashlib, time\n\ndef verify_slack_signature(\n signing_secret: str,\n body: bytes,\n timestamp: str,\n signature: str\n) -> bool:\n base = f\"v0:{timestamp}:{body.decode()}\"\n expected = \"v0=\" + hmac.new(\n signing_secret.encode(),\n base.encode(),\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(expected, signature)\n```\n\n**Jira Webhook 负载示例：**\n```json\n{\n \"timestamp\": 1708357200000,\n \"webhookEvent\": \"jira:issue_updated\",\n \"user\": { \"accountId\": \"5b10a...\" },\n \"issue\": {\n \"id\": \"10023\",\n \"key\": \"PROJ-42\",\n \"fields\": { \"status\": {}, \"summary\": \"...\" }\n },\n \"changelog\": {\n \"items\": [\n { \"field\": \"status\", \"fromString\": \"In Progress\", \"toString\": \"Done\" }\n ]\n }\n}\n```\n\n资料来源：[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)\n\n### 5. 错误处理\n\n错误处理章节列出 API 返回的错误代码和处理策略。\n\n**错误响应模式：**\n\n| 错误类型 | HTTP 状态码 | 处理策略 |\n|---------|------------|---------|\n| 认证失败 | 401 | 检查 token 有效性，刷新或重新授权 |\n| 权限不足 | 403 | 确认应用具备所需 scopes |\n| 资源不存在 | 404 | 验证 ID/键值是否正确 |\n| 速率限制 | 429 | 读取 Retry-After，等待后重试 |\n| 服务器错误 | 500-503 | 指数退避重试 |\n\n**常见错误代码表：**\n\n| 工具 | 错误代码 | 含义 |\n|------|---------|------|\n| Linear | `RATELIMITED` | 请求超出速率限制 |\n| Linear | `ENTITY_NOT_FOUND` | 指定实体不存在 |\n| Slack | `cant_update_message` | 无权修改该消息 |\n| Jira | 多种 | 见 Jira 官方错误文档 |\n\n资料来源：[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)\n\n---\n\n## Playbooks 跨工具编排\n\nPlaybooks 展示如何组合多个工具的 API 实现复杂业务流程。\n\n### 编排结构\n\n```mermaid\ngraph LR\n A[Slack 事件] -->|消息/反应| B[事件提取]\n B --> C[权限验证]\n C --> D{事件类型判断}\n D -->|incident| E[创建 Jira Issue]\n D -->|变更| F[更新现有 Issue]\n E --> G[回复 Slack 线程]\n F --> G\n G --> H[可选: 镜像状态回 Slack]\n```\n\n### 字段映射规则\n\nPlaybooks 定义工具间的数据映射关系：\n\n| Slack 字段 | Jira 字段 |\n|-----------|----------|\n| `event.channel` + `event.ts` | correlation key |\n| 消息文本（首句） | `summary` |\n| 消息全文 + 链接 | `description` |\n| 频道配置 | `priority`, `issuetype`, `project` |\n| `slack-incident` 标签 | 标签标识 |\n\n### 编排最佳实践\n\n1. **幂等性设计**：相同事件多次触发应产生相同结果\n2. **相关性检测**：创建前搜索现有 Issue 避免重复\n3. **状态同步**：可选地将目标系统状态变化同步回源系统\n4. **错误恢复**：记录失败状态，支持人工干预\n\n资料来源：[playbooks/slack-jira-incident.md:1-50](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n\n---\n\n## 开发流程与贡献规范\n\n### 添加新技能的步骤\n\n1. 创建分支：`git checkout -b skill/`\n2. 参考现有模板创建 `skill.md`\n3. 验证端点、速率限制、认证流程\n4. 在文档头部添加 `Last validated:` 日期\n5. 更新 `skills/INDEX.md` 和 `README.md`\n6. 在 `## Sources` 章节添加官方文档链接\n7. 提交 PR 触发 CI 测试\n\n### CI 测试流程\n\n```mermaid\ngraph TD\n A[提交 PR] --> B[npm test]\n B --> C{所有测试通过?}\n C -->|是| D[合并到 main]\n C -->|否| E[显示失败详情]\n E --> F[修复问题]\n F --> A\n \n B --> B1[加载所有技能]\n B1 --> B2[验证 11 个必填章节]\n B2 --> B3[验证摘要行非空]\n B3 --> B4[验证文件 ≥ 5KB]\n```\n\n资料来源：[README.md:20-40](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 版本与发布\n\n### 发布自动化\n\n发布流程通过 GitHub Actions 自动化：\n\n1. 合并代码到 `main` 分支\n2. 前往 GitHub Actions → **Release** 工作流\n3. 运行工作流，选择版本类型：\n - `patch`：补丁版本（bug 修复）\n - `minor`：次版本（新功能）\n - `major`：主版本（breaking changes）\n\n### 版本命名规范\n\n遵循语义化版本（Semantic Versioning）：\n- **Major**：`X.0.0` — 不兼容的 API 变更\n- **Minor**：`X.Y.0` — 向后兼容的新功能\n- **Patch**：`X.Y.Z` — 向后兼容的问题修复\n\n资料来源：[README.md:40-50](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 使用方式\n\n### MCP 服务集成\n\nMCP 服务器提供三个核心工具：\n\n| 工具名称 | 功能 |\n|---------|------|\n| `list_skills` | 列出所有可用的技能文档 |\n| `get_skill` | 获取完整技能或指定章节 |\n| `search_skills` | 全文本搜索所有技能 |\n\n**安装命令：**\n```bash\nnpx -y clawskills-mcp\n```\n\n**Claude Desktop 配置：**\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n### AI 代理集成模式\n\n**模式 1 — 参考特定章节：**\n```\n[paste \"Authentication & permissions\" section]\n\n使用上述内容，写一个 Python 函数交换 JWT 获取 access token 并缓存\n```\n\n**模式 2 — 完整技能作为系统上下文：**\n加载技能文档作为系统提示词的一部分，由 LLM 在运行时参考。\n\n**模式 3 — RAG 知识库：**\n将技能文档分割后索引到向量数据库，供检索增强生成使用。\n\n```python\nfrom langchain.text_splitter import MarkdownHeaderTextSplitter\n\nsplitter = MarkdownHeaderTextSplitter(\n headers_to_split_on=[(\"##\", \"section\"), (\"###\", \"subsection\")]\n)\n```\n\n资料来源：[README.md:50-100](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 维护与更新\n\n### 文档新鲜度\n\n技能文档需要定期验证以保持准确性：\n\n| 验证项目 | 频率 | 负责人 |\n|---------|------|-------|\n| API 端点可用性 | 每季度 | 技能维护者 |\n| 速率限制更新 | 发现变更时 | 提交者 |\n| 认证流程变化 | 发现变更时 | 提交者 |\n| 新功能添加 | 持续 | 社区贡献者 |\n\n### 验证标记\n\n文档头部应包含 `Last validated:` 日期：\n\n```markdown\n---\nLast validated: 2025-11-15\n---\n```\n\n### 问题报告\n\n发现文档错误时：\n\n1. 检查官方 API 文档确认正确行为\n2. 创建 Issue 描述问题\n3. 提交 PR 修复并更新验证日期\n4. 关联相关 Issue\n\n资料来源：[skills/ROADMAP.md:50-80](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n---\n\n## 路线图与未来方向\n\n### 当前阶段状态\n\n| 阶段 | 主题 | 状态 |\n|------|------|------|\n| Phase 1 | 基础（认证 + 核心 CRUD） | ✅ 完成 |\n| Phase 2 | 高频工作流（6-12 条 Recipes） | ✅ 完成 |\n| Phase 3 | 事件驱动与实时 | ✅ 完成 |\n| Phase 4 | 批量与高级操作 | ⚠️ 部分完成 |\n| Phase 5 | 跨工具编排 | ❌ 未开始 |\n\n### 下一阶段重点\n\n**优先级 1 — 新鲜度和准确性流水线**\n- 建立 API 变更监控系统\n- 自动验证文档准确性\n- 社区驱动的更新机制\n\n**优先级 2 — 跨工具编排扩展**\n- 更多 Playbooks 示例\n- 标准化编排模式库\n- 错误恢复和补偿策略\n\n资料来源：[skills/ROADMAP.md:80-120](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n---\n\n## 附录\n\n### 快速参考：技能文档元数据\n\n| 属性 | 要求 |\n|------|------|\n| 文件命名 | `skill.md` |\n| 目录位置 | `skills//` |\n| 最小大小 | 5 KB |\n| 章节数量 | 11 个必填 |\n| 语言 | Markdown |\n| 引用格式 | 指向官方文档的链接 |\n\n---\n\n\n\n## 技能目录总览\n\n### 相关页面\n\n相关主题：[技能文档结构](#page-skill-anatomy), [跨工具工作流剧本](#page-playbooks)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n- [skills/salesforce/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/salesforce/skill.md)\n- [skills/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)\n- [skills/zendesk/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/zendesk/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n- [skills/stripe/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/stripe/skill.md)\n- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)\n- [skills/jira/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)\n- [skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n- [skills/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/servicenow/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/servicenow/skill.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# 技能目录总览\n\n## 项目概述\n\n**Clawskills** 是一个开源的集成技能库项目，旨在为 AI 工具（特别是 Claude Code 和 Claude Desktop）提供标准化的第三方服务集成文档。该项目将常见的 SaaS 平台和开发工具的 API 使用方法、认证流程、速率限制和最佳实践整理成结构化的技能文档，使 AI 助手能够准确、高效地帮助用户完成与这些工具的集成工作。资料来源：[README.md:1]()\n\n该技能库目前涵盖 **14 个主流工具**，包括项目管理、设计协作、CRM、客服、财务等多个领域的解决方案。每个技能文档都遵循统一的 11 部分结构，确保一致性和可维护性。资料来源：[README.md:15]()\n\n## 架构设计\n\n### 技能库整体架构\n\n```mermaid\ngraph TD\n A[clawskills 仓库] --> B[技能文档层 skills/]\n A --> C[剧本目录 playbooks/]\n A --> D[MCP 服务器 mcp-server/]\n B --> E[14 个工具技能文档]\n B --> F[INDEX.md 索引]\n B --> G[ROADMAP.md 路线图]\n C --> H[跨工具工作流剧本]\n D --> I[list_skills 工具]\n D --> J[get_skill 工具]\n D --> K[search_skills 工具]\n```\n\n### MCP 服务器集成架构\n\nMCP 服务器作为 AI 工具与技能库之间的桥梁，提供三个核心工具：资料来源：[README.md:80-85]()\n\n```mermaid\nsequenceDiagram\n participant AI as AI 助手\n participant MCP as MCP 服务器\n participant FS as 文件系统\n\n AI->>MCP: list_skills\n MCP->>FS: 读取 skills/ 目录\n FS-->>MCP: 技能列表\n MCP-->>AI: 返回技能索引\n\n AI->>MCP: get_skill(\"jira\", \"auth\")\n MCP->>FS: 读取 skills/jira/skill.md\n FS-->>MCP: 完整文档内容\n MCP-->>AI: 返回认证章节\n\n AI->>MCP: search_skills(\"webhook\")\n MCP->>FS: 全文搜索所有技能\n FS-->>MCP: 匹配结果\n MCP-->>AI: 返回搜索结果\n```\n\n## 技能文档结构\n\n### 标准章节模板\n\n每个技能文档必须包含以下 11 个标准章节，这是项目质量要求的一部分：资料来源：[README.md:22]()\n\n| 章节序号 | 章节名称 | 说明 |\n|---------|---------|------|\n| 1 | 基本信息 | 工具简介、API 基础 URL、版本 |\n| 2 | 认证与权限 | 认证方式、OAuth 流程、权限范围 |\n| 3 | 核心 API 端点 | 主要 REST 端点或 GraphQL 操作 |\n| 4 | 常见工作流 | 典型使用场景的代码示例 |\n| 5 | 速率限制与重试 | API 限制、错误处理策略 |\n| 6 | 错误代码参考 | 常见错误及解决方案 |\n| 7 | Webhook 配置 | 事件订阅、签名验证 |\n| 8 | 批量操作 | 大量数据处理模式 |\n| 9 | 数据模型 | 关键对象结构说明 |\n| 10 | 安全与合规 | 最佳实践、隐私考虑 |\n| 11 | 参考资料 | 官方文档链接 |\n\n### 文档验证机制\n\n项目通过自动化测试确保文档质量：资料来源：[mcp-server/src/index.test.ts:18-40]()\n\n```mermaid\ngraph LR\n A[提交 PR] --> B[CI 运行 npm test]\n B --> C{加载所有技能}\n C --> D{检查摘要行}\n C --> E{检查必需章节}\n C --> F{检查文件大小 ≥5KB}\n D --> G{全部通过?}\n E --> G\n F --> G\n G -->|是| H[PR 允许合并]\n G -->|否| I[CI 失败报告]\n```\n\n测试套件验证以下条件：资料来源：[mcp-server/src/index.test.ts:18-40]()\n\n- 所有 14 个已知技能都已加载\n- 每个技能文件包含非空摘要行\n- 每个技能文件包含全部必需章节\n- 每个技能文件大小至少 5KB\n\n## 支持的工具清单\n\n### 工具分类总览\n\n| 类别 | 工具列表 | 说明 |\n|------|---------|------|\n| 项目管理 | Jira, Linear, Asana, Monday.com | 任务跟踪、敏捷管理 |\n| 设计协作 | Figma | 设计文件、组件库 |\n| CRM | Salesforce, HubSpot, Dynamics 365 | 销售和客户管理 |\n| 客服支持 | Zendesk, ServiceNow | 工单和服务管理 |\n| 通信协作 | Slack | 团队消息和自动化 |\n| 财务管理 | Stripe | 支付和订阅 |\n| 知识管理 | Notion | 文档和数据库 |\n| 开发协作 | GitHub | 代码仓库和 CI/CD |\n\n### 工具认证方式对比\n\n| 工具 | 主要认证方式 | Token 格式 | OAuth 支持 |\n|------|-------------|-----------|-----------|\n| Jira | Basic Auth / API Token | — | ✅ |\n| Linear | API Key | — | ✅ |\n| Asana | Personal Access Token | `1/xxxxxxxx` | ✅ |\n| Monday.com | API Key | — | ✅ |\n| Figma | Personal Access Token | `figd_xxx` | ✅ |\n| Salesforce | OAuth 2.0 | — | ✅ |\n| HubSpot | Private App Token | `pat-xxx` | ✅ |\n| Dynamics 365 | OAuth 2.0 | — | ✅ |\n| Zendesk | API Token | `xxx` | ✅ |\n| ServiceNow | Basic Auth | — | ✅ |\n| Slack | OAuth 2.0 / Bot Token | `xoxb-xxx` | ✅ |\n| Stripe | Secret Key | `sk_xxx` | ❌ |\n| Notion | Internal Integration | `secret_xxx` | ✅ |\n| GitHub | Personal Access Token | `ghp_xxx` | ✅ |\n\n### 速率限制对比\n\n| 工具 | 认证类型 | 请求频率 | 特殊限制 |\n|------|---------|---------|---------|\n| Figma | PAT | 1,000 req/hr | 按计划分级 |\n| Linear | API Key | 5,000 req/hr | 复杂度点限制 |\n| Jira | API Token | 取决于计划 | 付费版更高 |\n| Stripe | Secret Key | 无硬限制 | 建议请求隔离 |\n| Notion | Integration | 3 req/s | 分段限制 |\n| HubSpot | Private App | 100-500 req/10s | 按端点分级 |\n\n## 跨工具工作流剧本\n\n### 剧本目录\n\n项目在 `playbooks/` 目录下维护跨工具集成的工作流剧本。资料来源：[README.md:10]()\n\n```mermaid\ngraph TD\n P[剧本目录] --> S1[Slack-Jira 事故管理]\n P --> S2[跨工具同步流程]\n P --> S3[自动化工作流]\n\n S1 --> T1[Slack 消息监听]\n S1 --> T2[Jira 问题创建]\n S1 --> T3[状态同步]\n\n T1 --> T4[事件类型识别]\n T2 --> T5[字段映射]\n T3 --> T6[回执通知]\n```\n\n### Slack-Jira 事故剧本字段映射\n\n以下是一个跨工具集成的字段映射示例：资料来源：[playbooks/slack-jira-incident.md:1-20]()\n\n| Slack 事件字段 | Jira 目标字段 | 说明 |\n|---------------|---------------|------|\n| `event.channel` + `event.ts` | Correlation Key | 用于去重的关联标识 |\n| `event.text` (首句) | `summary` | 问题摘要，截断至 120 字符 |\n| `permalink` | `description` | Slack 消息永久链接 |\n| `event.thread_ts` | 评论/附件 | 线程上下文 |\n| `slack-incident` 标签 | Label | 事故类型标记 |\n| `correlation_key` | 自定义字段 | 跨系统关联键 |\n\n## 开发贡献流程\n\n### 添加新技能的步骤\n\n项目采用标准化的分支和 PR 流程来管理技能文档的更新：资料来源：[README.md:18-30]()\n\n```mermaid\ngraph LR\n A[创建分支 git checkout -b skill/<toolname>] --> B[遵循模板结构]\n B --> C[验证端点和限制]\n C --> D[添加 Last validated 日期]\n D --> E[更新 INDEX.md 和 README.md]\n E --> F[PR 并等待 CI 通过]\n F --> G[合并到 main]\n G --> H[触发 Release 工作流]\n```\n\n### 贡献质量要求\n\n- 所有 11 个标准章节必须完整填写\n- 端点、速率限制和认证流程必须对照官方文档验证\n- `Last validated` 日期必须更新\n- 引用官方来源，禁止未经验证的声明\n- 至少包含 5 个常见工作流示例\n\n## 发布与维护机制\n\n### 自动化发布流程\n\n项目使用 GitHub Actions 实现完全自动化的发布流程：资料来源：[skills/ROADMAP.md:20-25]()\n\n```mermaid\ngraph LR\n A[合并到 main 分支] --> B[GitHub Actions]\n B --> C[运行 Release 工作流]\n C --> D[选择版本类型]\n D --> E{patch/minor/major}\n E --> F[版本号递增]\n F --> G[创建 Git Tag]\n F --> H[npm publish]\n G --> I[GitHub Release]\n```\n\n### 版本管理策略\n\n| 版本类型 | 适用场景 | 示例 |\n|---------|---------|------|\n| patch | 文档修正、链接更新 | 1.0.0 → 1.0.1 |\n| minor | 新增端点、新增章节 | 1.0.1 → 1.1.0 |\n| major | 新增工具、架构变更 | 1.1.0 → 2.0.0 |\n\n## 未来发展路线\n\n### 已完成阶段\n\n| 阶段 | 主题 | 状态 |\n|------|------|------|\n| Phase 1 | 基础（认证 + 核心 CRUD） | ✅ 全部 14 个工具 |\n| Phase 2 | 高频工作流（6-12 个示例/工具） | ✅ 全部 14 个工具 |\n| Phase 3 | 事件驱动与实时（Webhook） | ✅ 全部 14 个工具 |\n| Phase 4 | 批量与高级操作 | ⚠️ 部分完成 |\n| Phase 5 | 跨工具编排（2+ 工具联动） | ❌ 未开始 |\n\n资料来源：[skills/ROADMAP.md:30-40]()\n\n### 优先级计划\n\n**优先级 1 — 新鲜度和准确性流水线**\n\n随着 14 个核心技能库完成，下一个护城河是确保文档随供应商 API 变化保持准确。资料来源：[skills/ROADMAP.md:45-50]()\n\n计划包括：\n\n- 自动化 API 变更检测\n- 社区贡献的审查流程\n- 定期重新验证机制\n- 版本化技能文档\n\n## 在 Claude Code 中使用\n\n### 项目指令文件示例\n\n在 `.claude/CLAUDE.md` 中配置项目级指令，使 AI 始终使用这些技能文档：资料来源：[README.md:60-75]()\n\n```markdown\n# 集成技能\n\n当编写与以下工具集成的代码时，始终先阅读对应技能文档：\n\n- Monday.com → @skills/monday/skill.md\n- Salesforce → @skills/salesforce/skill.md\n- Jira → @skills/jira/skill.md\n- Dynamics 365 → @skills/dynamics365/skill.md\n- HubSpot → @skills/hubspot/skill.md\n- ServiceNow → @skills/servicenow/skill.md\n- Zendesk → @skills/zendesk/skill.md\n- Asana → @skills/asana/skill.md\n- GitHub → @skills/github/skill.md\n- Figma → @skills/figma/skill.md\n- Slack → @skills/slack/skill.md\n- Stripe → @skills/stripe/skill.md\n- Notion → @skills/notion/skill.md\n- Linear → @skills/linear/skill.md\n\n遵循文档中指定的认证模式、速率限制处理和错误代码。\n```\n\n## 总结\n\n技能目录总览展示了 Clawskills 项目的完整架构和价值主张：\n\n- **14 个主流工具**的标准化集成文档\n- **统一的 11 章节结构**确保一致性和可维护性\n- **MCP 服务器集成**使 AI 工具能够实时访问技能库\n- **自动化测试和发布**保证文档质量\n- **跨工具剧本**支持复杂业务场景\n\n该项目将持续更新以反映供应商 API 的变化，并逐步扩展跨工具编排能力。\n\n---\n\n\n\n## 跨工具工作流剧本\n\n### 相关页面\n\n相关主题：[技能目录总览](#page-skill-catalog), [贡献指南](#page-contributing)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [playbooks/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/INDEX.md)\n- [playbooks/zendesk-jira-bug-escalation.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/zendesk-jira-bug-escalation.md)\n- [playbooks/hubspot-asana-onboarding.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/hubspot-asana-onboarding.md)\n- [playbooks/salesforce-hubspot-lead-sync.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/salesforce-hubspot-lead-sync.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# 跨工具工作流剧本\n\n## 概述\n\n跨工具工作流剧本（Playbooks）是 Clawskills 项目中用于定义和编排多系统集成的核心文档。这些剧本描述了如何将两个或多个工具（如 Slack、Jira、Zendesk、HubSpot、Salesforce、Asana 等）的 API 和事件机制组合起来，实现端到端的业务流程自动化。\n\n剧本的核心价值在于提供经过验证的集成模式，涵盖身份验证、数据映射、事件处理、错误恢复等关键环节，帮助开发者快速实现跨系统的工作流编排。\n\n资料来源：[playbooks/INDEX.md:1-20]()\n\n---\n\n## 剧本架构\n\n### 剧本组成要素\n\n每个剧本通常包含以下核心组件：\n\n| 组件 | 说明 |\n|------|------|\n| 触发器（Trigger） | 启动工作流的事件来源，如消息接收、工单创建、状态变更 |\n| 源系统 | 工作流的起始工具，产生原始事件 |\n| 目标系统 | 工作流的终点，接收处理后的数据 |\n| 数据映射 | 字段对应关系和格式转换规则 |\n| 事件处理 | 对触发事件的响应逻辑 |\n| 错误处理 | 异常情况的处理策略 |\n\n资料来源：[playbooks/slack-jira-incident.md:10-15]()\n\n### 剧本类型分类\n\n根据业务场景，剧本可分为以下类型：\n\n| 类型 | 描述 | 示例 |\n|------|------|------|\n| 事件驱动型 | 响应实时事件自动触发 | Slack 消息 → Jira 工单 |\n| 同步型 | 双向数据保持一致 | Salesforce → HubSpot 线索同步 |\n| 编排型 | 多步骤复杂业务流程 | Zendesk 工单 → Jira Bug → Slack 通知 |\n\n资料来源：[playbooks/INDEX.md:1-30]()\n\n---\n\n## 剧本工作流程\n\n### 标准执行流程\n\n```mermaid\ngraph TD\n A[触发事件] --> B{事件验证}\n B -->|签名无效| C[拒绝请求]\n B -->|验证通过| D[解析事件数据]\n D --> E[数据映射与转换]\n E --> F[调用目标系统 API]\n F --> G{调用成功?}\n G -->|是| H[记录响应]\n G -->|否| I[重试/错误处理]\n H --> J[发送确认通知]\n I --> K{重试次数耗尽?}\n K -->|否| F\n K -->|是| L[告警并记录失败]\n```\n\n### 事件处理模式\n\n```mermaid\ngraph LR\n A[源系统事件] --> B[Webhook 接收端点]\n B --> C{事件类型匹配}\n C -->|issue_created| D[创建目标记录]\n C -->|issue_updated| E[更新目标记录]\n C -->|comment_created| F[添加评论]\n D --> G[响应 200 OK]\n E --> G\n F --> G\n```\n\n资料来源：[playbooks/slack-jira-incident.md:30-50]()\n\n---\n\n## 字段映射规范\n\n### Slack → Jira 字段映射\n\n| Slack 属性 | Jira 字段 | 转换规则 |\n|------------|-----------|----------|\n| `event.item.channel` + `event.item.ts` | correlation key | 格式：`slack:{team_id}:{channel_id}:{ts}` |\n| 消息文本首句 | `summary` | 截断至 120 字符 |\n| 消息全文 + 线程回复 | `description` | 包含 Slack permalink 链接 |\n| 触发器来源 | 标签 | 添加 `slack-incident` 标签 |\n\n资料来源：[playbooks/slack-jira-incident.md:50-60]()\n\n### Salesforce → HubSpot 字段映射\n\n| Salesforce 字段 | HubSpot 字段 | 数据类型 |\n|-----------------|--------------|----------|\n| `Lead.Email` | `email` | string |\n| `Lead.FirstName` | `firstname` | string |\n| `Lead.LastName` | `lastname` | string |\n| `Lead.Company` | `company` | string |\n| `Lead.Phone` | `phone` | string |\n| `Lead.LeadSource` | `hs_lead_status` | enumeration |\n\n资料来源：[playbooks/salesforce-hubspot-lead-sync.md:15-25]()\n\n---\n\n## 认证与安全\n\n### 跨系统认证模式\n\n| 源系统 | 认证方式 | 目标系统 | 认证方式 |\n|--------|----------|----------|----------|\n| Slack | Bot Token (`xoxb-...`) | Jira | API Token + Basic Auth |\n| Zendesk | API Token | Jira | API Token + Basic Auth |\n| HubSpot | OAuth 2.0 / Private App | Asana | Personal Access Token |\n| Salesforce | OAuth 2.0 | HubSpot | Private App Token |\n\n资料来源：[playbooks/zendesk-jira-bug-escalation.md:20-30]()\n\n### Webhook 安全验证\n\n所有入站 Webhook 必须进行签名验证：\n\n```python\n# Slack 签名验证示例\ndef verify_slack_signature(body, timestamp, signature, signing_secret):\n prefix = f\"v0:{timestamp}:\"\n expected = \"v0=\" + hmac.new(\n signing_secret.encode(),\n prefix.encode() + body,\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(expected, signature)\n```\n\n```python\n# Linear 签名验证示例\ndef verify_linear_signature(body, signature, secret):\n expected = hmac.new(\n secret.encode(),\n body,\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(expected, signature)\n```\n\n资料来源：[playbooks/slack-jira-incident.md:70-85]()\n\n---\n\n## 错误处理策略\n\n### 错误响应码处理\n\n| Slack 错误码 | 处理策略 | 说明 |\n|--------------|----------|------|\n| `channel_not_found` | 重新安装应用 | workspace 权限变更导致 |\n| `ratelimited` | 尊重 `Retry-After` 头 | 指数退避重试 |\n| `already_in_channel` | 忽略 | 视为成功 |\n| `cant_update_message` | 跳过更新 | 仅原发布 bot 可更新 |\n| `msg_too_long` | 拆分消息 | 单条限制 40,000 字符 |\n\n资料来源：[skills/slack/skill.md:100-120]()\n\n### 重试机制\n\n```mermaid\ngraph TD\n A[API 调用] --> B{响应状态}\n B -->|2xx| C[成功 - 继续]\n B -->|429| D[读取 Retry-After]\n B -->|5xx| E[重试]\n D --> F[等待后重试]\n E --> F\n F --> A\n B -->|4xx 非 429| G[记录错误]\n G --> H[不重试 - 需修复代码]\n```\n\n资料来源：[playbooks/salesforce-hubspot-lead-sync.md:40-50]()\n\n---\n\n## 剧本示例：Slack-Jira 事件响应\n\n### 业务流程\n\n```mermaid\nsequenceDiagram\n participant S as Slack\n participant A as 事件处理器\n participant J as Jira\n participant H as HubSpot\n\n S->>A: 消息事件 (reaction_added)\n A->>S: 获取 permalink\n A->>J: 搜索相关工单\n alt 找到现有工单\n A->>J: 更新现有工单\n else 未找到工单\n A->>J: 创建新 Jira Issue\n A->>H: 同步客户信息\n end\n A->>S: 回复线程 (工单链接)\n```\n\n### 实现要点\n\n1. **关联键生成**：使用 `slack:{team_id}:{channel_id}:{ts}` 格式确保全局唯一性\n2. **幂等性处理**：创建前先搜索，避免重复工单\n3. **上下文保留**：在 description 中保留 Slack permalink 和消息原文\n4. **异步处理**：返回 200 后在后台执行重操作\n\n资料来源：[playbooks/slack-jira-incident.md:1-30]()\n\n---\n\n## 剧本示例：Zendesk-Jira Bug 升级\n\n### 触发条件\n\n| Zendesk 事件 | 条件 | Jira 操作 |\n|--------------|------|----------|\n| Ticket 创建 | `tags` 包含 `bug` | 创建 Bug 类型 Issue |\n| Ticket 更新 | `priority` 变为 `urgent` | 升级现有 Bug |\n| Ticket 更新 | `status` 变为 `solved` | 同步关闭 Jira Issue |\n\n### 数据映射\n\n| Zendesk 字段 | Jira 字段 | 说明 |\n|--------------|-----------|------|\n| `ticket.id` | `description` 引用 | 保留 Zendesk 链接 |\n| `ticket.subject` | `summary` | Bug 标题 |\n| `ticket.description` | `description` | 详细描述 |\n| `ticket.priority` | `priority` | Urgent → Highest |\n| `ticket.requester.email` | `reporter` | 报告人信息 |\n\n资料来源：[playbooks/zendesk-jira-bug-escalation.md:10-25]()\n\n---\n\n## 剧本示例：HubSpot-Asana 客户入职\n\n### 工作流阶段\n\n```mermaid\ngraph LR\n A[HubSpot Deal 成交] --> B[创建 Asana 项目]\n B --> C[添加项目任务模板]\n C --> D[分配负责人]\n D --> E[发送客户通知]\n E --> F[跟踪里程碑完成]\n F --> G[同步回 HubSpot]\n```\n\n### 配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `project_template_gid` | string | Asana 项目模板 ID |\n| `team_gid` | string | 负责团队 ID |\n| `due_date_offset` | number | 相对成交日期的天数 |\n| `notification_template` | string | 客户通知内容模板 |\n\n资料来源：[playbooks/hubspot-asana-onboarding.md:15-40]()\n\n---\n\n## 剧本示例：Salesforce-HubSpot 线索同步\n\n### 同步策略\n\n```mermaid\ngraph TD\n A[Salesforce Lead 创建/更新] --> B{冲突检测}\n B -->|HubSpot 无对应记录| C[创建 HubSpot Contact]\n B -->|HubSpot 存在记录| D[比较 updatedAt 时间戳]\n D -->|SF 更新更新| E[更新 HubSpot]\n D -->|HubSpot 更新更新| F[跳过 - 保留 HubSpot 数据]\n C --> G[记录同步日志]\n E --> G\n```\n\n### 同步字段配置\n\n| Salesforce | HubSpot | 同步方向 | 冲突处理 |\n|------------|---------|----------|----------|\n| `Email` | `email` | 必填 | 作为唯一标识符 |\n| `FirstName` | `firstname` | SF → HS | 以最新更新为准 |\n| `LastName` | `lastname` | SF → HS | 以最新更新为准 |\n| `Company` | `company` | SF → HS | 以最新更新为准 |\n| `Phone` | `phone` | 双向 | 以最新更新为准 |\n\n资料来源：[playbooks/salesforce-hubspot-lead-sync.md:10-35]()\n\n---\n\n## 最佳实践\n\n### 设计原则\n\n1. **幂等性优先**：所有操作必须可安全重试，避免重复创建资源\n2. **快速响应**：Webhook 端点应立即返回 200，在后台处理复杂逻辑\n3. **签名验证**：所有入站事件必须验证签名，拒绝未授权请求\n4. **数据映射文档化**：明确记录每个字段的转换规则和默认值\n5. **错误可观测性**：记录足够的日志信息便于调试，包括错误码和响应时间\n\n### 性能优化\n\n| 优化点 | 策略 |\n|--------|------|\n| API 调用次数 | 使用批量 API，减少循环调用 |\n| Webhook 处理 | 消息队列异步处理，避免阻塞 |\n| 缓存策略 | 缓存认证 token 和频繁查询的数据 |\n| 复杂度控制 | Linear API 请求优先选择必要的字段 |\n\n资料来源：[skills/linear/skill.md:80-100]()\n\n---\n\n## 相关资源\n\n### 工具技能文档\n\n- [Slack 技能文档](../skills/slack/skill.md)\n- [Jira 技能文档](../skills/jira/skill.md)\n- [HubSpot 技能文档](../skills/hubspot/skill.md)\n- [Salesforce 技能文档](../skills/salesforce/skill.md)\n- [Zendesk 技能文档](../skills/zendesk/skill.md)\n- [Linear 技能文档](../skills/linear/skill.md)\n- [Asana 技能文档](../skills/asana/skill.md)\n\n### 扩展阅读\n\n- [ROADMAP.md](../skills/ROADMAP.md) - 跨工具编排模式规划\n- [CLAUDE.md](https://github.com/Shanksg/clawskills/blob/main/.claude/CLAUDE.md) - Claude Code 集成配置\n\n---\n\n\n\n## 部署指南\n\n### 相关页面\n\n相关主题：[持续集成与发布](#page-cicd), [MCP 服务器架构](#page-mcp-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [package.json](https://github.com/Shanksg/clawskills/blob/main/package.json)\n- [.github/workflows/ci.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/ci.yml) (隐含引用)\n- [.github/workflows/release.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/release.yml) (隐含引用)\n- [skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md) (隐含引用)\n \n\n# 部署指南\n\n## 概述\n\nclawskills 是一个技能文档库（Skills Documentation Library），为 AI 工具提供集成指南。该项目包含 14 种工具的完整集成文档，并通过 MCP（Model Context Protocol）服务器提供访问接口。\n\n核心部署组件为 `clawskills-mcp` 服务器，它提供三个主要工具供 AI 助手调用：\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `list_skills` | 列出所有可用的技能文档 |\n| `get_skill` | 获取完整的技能文档或指定章节 |\n| `search_skills` | 全文本搜索所有技能文档 |\n\n资料来源：[README.md:1-10]()\n\n## 架构概览\n\n```graph TD\n A[用户/AI 工具] -->|MCP 协议| B[clawskills-mcp 服务器]\n B -->|HTTP| C[GitHub API]\n C -->|返回| B\n B -->|技能文档| A\n D[GitHub Actions] -->|自动化发布| E[npm 仓库]\n E -->|安装| B\n```\n\n## 本地部署方式\n\n### 临时运行（npx）\n\n无需安装，可直接通过 npx 运行 MCP 服务器：\n\n```bash\nnpx -y clawskills-mcp\n```\n\n此方式适用于一次性测试或临时集成场景。服务器启动后，AI 工具（如 Claude Desktop）可通过 MCP 协议连接并调用技能文档。\n\n资料来源：[README.md:71-75]()\n\n### 全局安装\n\n对于长期使用，建议全局安装：\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n全局安装后，MCP 服务器在系统中持久可用，不受当前工作目录限制。\n\n资料来源：[README.md:76-78]()\n\n## Claude Desktop / Claude Code 配置\n\n### 配置步骤\n\n将以下配置添加到 Claude Desktop 或 Claude Code 的配置文件中：\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n### 配置位置\n\n| 平台 | 配置文件路径 |\n|------|-------------|\n| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop (Windows) | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Claude Code | `.claude/settings.json` 或项目级配置 |\n\n### 验证配置\n\n配置完成后，重启 Claude Desktop/Claude Code，然后尝试调用技能工具：\n\n```\nlist_skills\n```\n\n预期返回所有 14 个工具的技能文档列表。\n\n资料来源：[README.md:79-90]()\n\n## MCP 服务器工具详解\n\n### list_skills\n\n返回所有可用的技能文档列表，无需参数。\n\n```json\n// 响应示例\n{\n \"skills\": [\n \"monday\",\n \"salesforce\",\n \"jira\",\n \"dynamics365\",\n \"hubspot\",\n \"servicenow\",\n \"zendesk\",\n \"asana\",\n \"github\",\n \"figma\",\n \"slack\",\n \"stripe\",\n \"notion\",\n \"linear\"\n ]\n}\n```\n\n### get_skill\n\n获取指定技能的完整文档或特定章节。\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `skill_name` | string | 是 | 技能名称（如 `jira`、`linear`） |\n| `section` | string | 否 | 指定章节：`auth`、`rate-limits`、`recipes`、`errors` |\n\n```json\n// 获取 Jira 技能文档的认证部分\n{\n \"skill_name\": \"jira\",\n \"section\": \"auth\"\n}\n```\n\n### search_skills\n\n全文本搜索所有技能文档。\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `query` | string | 是 | 搜索关键词 |\n| `limit` | number | 否 | 返回结果数量限制（默认 10） |\n\n## CI/CD 自动化部署\n\n### 持续集成\n\n每次推送和 PR 合并时触发 CI 流程：\n\n```mermaid\ngraph LR\n A[推送/PR] --> B{GitHub Actions CI}\n B --> C[npm test]\n C --> D{测试通过?}\n D -->|是| E[允许合并]\n D -->|否| F[阻止合并]\n```\n\n测试套件包括：\n- Vitest 单元测试\n- 真实技能文档验证\n- 必需章节检查\n- 文档大小验证（≥5 KB）\n\n资料来源：[skills/ROADMAP.md:1-15]()\n\n### 发布自动化\n\n项目使用 `release.yml` 工作流自动化版本发布：\n\n1. 合并到 `main` 分支\n2. 进入 GitHub Actions → **Release**\n3. 运行工作流，选择版本类型：\n - `patch` — 补丁版本（bug 修复）\n - `minor` — 次版本（新功能）\n - `major` — 主版本（破坏性变更）\n\n发布流程自动完成：\n- 版本号递增\n- Git 标签创建\n- npm 包发布\n\n资料来源：[README.md:35-40]()\n\n### OIDC 认证\n\n发布流程使用 OpenID Connect (OIDC) 与 npm 仓库建立安全连接，无需存储 npm token。\n\n## 部署验证清单\n\n部署完成后，按以下清单验证：\n\n- [ ] Claude Desktop/Code 已重启\n- `list_skills` 调用成功，返回 14 个工具\n- `get_skill` 能获取完整文档\n- `search_skills` 搜索结果准确\n- MCP 连接状态为\"已连接\"\n\n## 项目结构参考\n\n```\nclawskills/\n├── README.md # 主说明文档\n├── package.json # npm 包配置\n├── skills/ # 技能文档目录\n│ ├── INDEX.md # 所有技能索引\n│ ├── jira/\n│ ├── linear/\n│ ├── figma/\n│ └── ... # 其他 11 个工具\n├── playbooks/ # 跨工具工作流\n│ └── slack-jira-incident.md\n└── .github/\n └── workflows/\n ├── ci.yml # 持续集成\n └── release.yml # 发布自动化\n```\n\n## 常见部署问题\n\n| 问题 | 解决方案 |\n|------|---------|\n| MCP 服务器连接失败 | 检查 JSON 配置格式，确保 `command` 为 `npx` |\n| 工具调用超时 | 确认网络连接，可使用全局安装替代 npx |\n| 版本过旧 | 运行 `npm update -g clawskills-mcp` 更新 |\n| 权限错误 | 检查 Claude Desktop 配置文件的读写权限 |\n\n## 相关资源\n\n- 项目主页：https://github.com/Shanksg/clawskills\n- MCP 服务器 npm 包：https://www.npmjs.com/package/clawskills-mcp\n- 技能索引：[skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n- 开发路线图：[skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n---\n\n\n\n## 持续集成与发布\n\n### 相关页面\n\n相关主题：[部署指南](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n- [mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)\n- [.github/workflows/ci.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/ci.yml)\n- [.github/workflows/release.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/release.yml)\n- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n \n\n# 持续集成与发布\n\n## 概述\n\nClawSkills 项目采用自动化持续集成（CI）和持续发布（CD）流程，确保代码质量和发布效率。整个系统基于 GitHub Actions 实现自动化构建、测试和发布流程，涵盖单元测试、技能文档验证、版本管理和 npm 包发布等关键环节。\n\n项目包含两套独立的自动化工作流：\n- **CI 工作流** (`ci.yml`)：在每次 push 和 PR 时自动执行构建和测试\n- **发布工作流** (`release.yml`)：通过手动触发实现语义化版本管理和 npm 发布\n\n## 整体架构\n\n```mermaid\ngraph TD\n A[开发者提交代码] --> B{触发方式}\n B -->|push / PR| C[ci.yml 工作流]\n B -->|workflow_dispatch| D[release.yml 工作流]\n \n C --> E[安装依赖]\n E --> F[npm test]\n F --> G{测试结果}\n G -->|通过| H[CI 成功]\n G -->|失败| I[CI 失败 / 通知]\n \n D --> J[选择版本类型]\n J --> K[patch / minor / major]\n K --> L[更新版本号]\n L --> M[创建 Git Tag]\n M --> N[推送至 npm]\n N --> O[发布完成]\n```\n\n## CI 工作流详解\n\n### 触发条件\n\nCI 工作流在以下场景自动触发：\n\n| 触发事件 | 说明 |\n|---------|------|\n| `push` | 代码推送至 main 分支或 PR 分支 |\n| `pull_request` | 创建或更新 Pull Request |\n\n资料来源：[.github/workflows/ci.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/ci.yml)\n\n### 测试套件\n\n项目使用 Vitest 作为测试框架，测试套件位于 `mcp-server/src/index.test.ts`。测试验证以下关键要求：\n\n```typescript\ndescribe(\"real skills\", () => {\n it(\"loads all expected skills\", () => {\n // 验证所有14个skill都被正确加载\n });\n\n it(\"every skill has a non-empty summary line\", () => {\n // 验证每个skill都有摘要行\n });\n\n it(\"every skill contains the required sections\", () => {\n // 验证每个skill包含所有11个必需部分\n });\n\n it(\"every skill file is at least 5KB\", () => {\n // 验证skill文件大小合理\n });\n});\n```\n\n资料来源：[mcp-server/src/index.test.ts:19-44](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n\n### 必需部分验证\n\n每个 skill 文档必须包含以下 11 个部分：\n\n1. 认证与权限\n2. 核心端点\n3. 常见工作流（Recipes）\n4. 过滤与查询模式\n5. 速率限制与重试策略\n6. 错误处理\n7. Webhook 配置\n8. 数据模型\n9. 安全与隐私\n10. 配额与限制\n11. 相关资源\n\n### npm 测试命令\n\n```json\n{\n \"scripts\": {\n \"test\": \"vitest run\"\n }\n}\n```\n\n资料来源：[mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)\n\n## 发布工作流详解\n\n### 触发方式\n\n发布工作流通过 GitHub Actions 手动触发（workflow_dispatch），开发者可选择发布类型。\n\n```yaml\nworkflow_dispatch:\n inputs:\n release_type:\n description: '发布类型'\n required: true\n type: choice\n options:\n - patch\n - minor\n - major\n```\n\n资料来源：[.github/workflows/release.yml](https://github.com/Shanksg/clawskills/blob/main/.github/workflows/release.yml)\n\n### 发布流程步骤\n\n```mermaid\ngraph LR\n A[选择发布类型] --> B[更新 package.json 版本号]\n B --> C[创建 Git Tag]\n C --> D[提交更改]\n D --> E[推送到 GitHub]\n E --> F[发布到 npm registry]\n```\n\n### 版本管理策略\n\n项目采用语义化版本（SemVer）规范：\n\n| 版本类型 | 说明 | 示例 |\n|---------|------|------|\n| `patch` | 补丁版本，修复问题 | 1.0.0 → 1.0.1 |\n| `minor` | 次版本，新增功能（向后兼容） | 1.0.0 → 1.1.0 |\n| `major` | 主版本，破坏性变更 | 1.0.0 → 2.0.0 |\n\n### OIDC 发布机制\n\n发布工作流使用 OpenID Connect (OIDC) 进行身份验证，确保安全的 npm 发布流程：\n\n```yaml\npermissions:\n id-token: write\n contents: read\n```\n\n此配置允许工作流从 npm 获取短期令牌，无需长期存储凭据。\n\n## MCP Server 包管理\n\n### 包结构\n\n```json\n{\n \"name\": \"clawskills-mcp\",\n \"version\": \"0.2.0\",\n \"description\": \"MCP server exposing ClawSkills API integration docs\",\n \"bin\": {\n \"clawskills-mcp\": \"./dist/index.js\"\n },\n \"engines\": {\n \"node\": \">=18\"\n }\n}\n```\n\n资料来源：[mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)\n\n### 安装方式\n\n| 安装方式 | 命令 | 适用场景 |\n|---------|------|---------|\n| 临时运行（npx） | `npx -y clawskills-mcp` | Claude Desktop / Claude Code |\n| 全局安装 | `npm install -g clawskills-mcp` | 持久化使用 |\n\n## 技能文档同步机制\n\n### 同步脚本\n\n项目提供两个辅助脚本用于管理和同步技能文档：\n\n| 脚本 | 功能 |\n|------|------|\n| `check-skills.mjs` | 验证 skill 文档的完整性和格式 |\n| `sync-skills.mjs` | 同步更新 skill 文档 |\n\n资料来源：[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)\n\n### 可用 Skills 列表\n\n系统支持以下 14 个工具的集成技能文档：\n\n- Asana\n- Dynamics 365\n- Figma\n- GitHub\n- HubSpot\n- Jira\n- Linear\n- Monday.com\n- Notion\n- Salesforce\n- ServiceNow\n- Slack\n- Stripe\n- Zendesk\n\n资料来源：[mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n\n## MCP 工具接口\n\n### 工具列表\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `list_skills` | 列出所有可用的 skill 文档 |\n| `get_skill` | 获取完整的 skill 文档或指定部分 |\n| `search_skills` | 在所有 skill 文档中进行全文搜索 |\n| `list_playbooks` | 列出所有可用的剧本 |\n| `get_playbook` | 获取指定剧本内容 |\n\n### 使用配置\n\n在 Claude Desktop 或 Claude Code 中配置：\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n## 开发贡献流程\n\n### 分支命名规范\n\n```bash\ngit checkout -b skill/<工具名称>\n```\n\n### 提交流程\n\n1. 创建功能分支\n2. 按照模板结构编写或更新 skill 文档（必须包含全部 11 个部分）\n3. 验证所有端点、速率限制和认证流程\n4. 在文档头部添加 `Last validated:` 日期\n5. 更新 `skills/INDEX.md` 和 `README.md`\n6. 在 `## Sources` 部分添加官方文档链接\n7. 提交 Pull Request\n\n### PR 验证\n\n提交 PR 后，CI 流水线自动执行 `npm test`，验证内容：\n\n- skill 文件可正常加载\n- 包含所有必需章节\n- 文件大小不小于 5KB\n\n资料来源：[mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n\n## 最佳实践\n\n### 技能文档编写规范\n\n| 要求 | 说明 |\n|------|------|\n| 章节完整性 | 必须包含全部 11 个必需部分 |\n| 最小长度 | 文件大小至少 5KB |\n| API 验证 | 所有端点需对照官方文档验证 |\n| 认证模式 | 严格按照文档中的认证模式实现 |\n| 速率限制 | 准确记录各 API 的速率限制 |\n| 错误代码 | 列出所有相关的错误代码和处理方式 |\n\n### 发布检查清单\n\n- [ ] 所有测试通过\n- [ ] 版本号正确更新\n- [ ] Git Tag 已创建\n- [ ] CHANGELOG 已更新\n- [ ] npm 发布成功\n\n## 相关资源\n\n- GitHub Actions 文档：https://docs.github.com/actions\n- Vitest 测试框架：https://vitest.dev\n- SemVer 规范：https://semver.org\n\n---\n\n\n\n## 贡献指南\n\n### 相关页面\n\n相关主题：[技能文档结构](#page-skill-anatomy)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n- [skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n \n\n# 贡献指南\n\n本文档介绍如何为 clawskills 项目贡献代码和技能文档。clawskills 是一个集成技能库，汇集了多种工具（如 Salesforce、Jira、Linear、Slack 等）的 API 集成文档和最佳实践。贡献者可以通过标准的 Git 工作流提交新的技能文档或更新现有内容。\n\n---\n\n## 贡献流程概述\n\n贡献 clawskills 的标准流程包含以下步骤：\n\n```mermaid\ngraph TD\n A[创建功能分支] --> B[遵循 skill.md 模板编写文档]\n A1[git checkout -b skill/<toolname>] --> A\n B --> C[对照官方文档验证内容]\n C --> D[添加 Last validated 日期]\n D --> E[更新 INDEX.md 和 README.md]\n E --> F[提交 Pull Request]\n F --> G[CI 自动测试]\n G --> H{测试通过?}\n H -->|是| I[合并到 main 分支]\n H -->|否| J[修复测试失败]\n J --> F\n I --> K[触发 Release 工作流]\n K --> L[选择版本类型]\n L --> M[发布新版本]\n```\n\n资料来源：[README.md:29-40](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 创建功能分支\n\n所有贡献必须通过 Git 分支工作流进行。创建新技能文档时，请使用以下命名规范：\n\n```bash\ngit checkout -b skill/\n```\n\n其中 `` 是目标工具的名称（小写）。\n\n| 分支前缀 | 用途 | 示例 |\n|---------|------|------|\n| `skill/` | 新增技能文档 | `skill/zendesk` |\n| `skill/` | 更新现有技能 | `skill/salesforce-update` |\n\n资料来源：[README.md:30](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 技能文档结构要求\n\nclawskills 要求所有技能文档严格遵循标准模板结构。文档必须包含 **11 个必需章节**，每个章节都有其特定用途。\n\n### 必需章节列表\n\n| 章节编号 | 章节名称 | 说明 |\n|---------|---------|------|\n| 1 | 概述 | 工具简介和使用场景 |\n| 2 | 认证与权限 | API 密钥、OAuth 等认证方式 |\n| 3 | 核心端点 | 主要 API 端点及其参数 |\n| 4 | 常见工作流 | 典型使用场景和代码示例 |\n| 5 | 错误处理 | 错误代码和解决方案 |\n| 6 | 速率限制 | API 限制和重试策略 |\n| 7 | Webhook | 事件订阅配置 |\n| 8 | 数据模型 | 主要数据类型和字段 |\n| 9 | 可靠性 | 容错和幂等性保证 |\n| 10 | 安全与隐私 | 最佳安全实践 |\n| 11 | 参考来源 | 官方文档链接 |\n\n### 文档验证规则\n\nCI 测试会验证以下条件：\n\n```typescript\nconst REQUIRED_SECTIONS = [\n \"认证与权限\", \"核心端点\", \"常见工作流\",\n \"错误处理\", \"速率限制\", \"可靠性\",\n \"安全与隐私\", \"参考来源\"\n];\n\n// 每个技能文件必须满足以下条件：\n// 1. 包含所有必需章节\n// 2. 文件大小至少 5KB\n// 3. 每个章节内容非空\n```\n\n资料来源：[mcp-server/src/index.test.ts:20-40](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n\n---\n\n## 内容编写规范\n\n### 验证要求\n\n在提交贡献前，必须对照官方供应商文档验证以下信息：\n\n| 验证项 | 说明 |\n|-------|------|\n| 端点地址 | 确保 URL 路径和参数准确 |\n| 速率限制 | 验证当前限制值和计算方式 |\n| 认证流程 | 确认 OAuth scopes 和 token 格式 |\n| 错误代码 | 对照官方错误码文档 |\n\n### 日期标注\n\n每个技能文档的元数据头部必须包含 `Last validated:` 日期：\n\n```markdown\n---\ntool: jira\nversion: \"3.x\"\nlast_validated: 2024-01-15\n---\n```\n\n### 来源引用\n\n`## 参考来源` 章节必须包含指向官方文档的有效链接。禁止添加未经核实的信息：\n\n```markdown\n## 参考来源\n\n- [Jira Cloud REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/)\n- [OAuth 2.0 认证](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)\n```\n\n资料来源：[README.md:33-36](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 索引文件更新\n\n当添加新技能时，必须同步更新以下文件：\n\n| 文件路径 | 更新内容 |\n|---------|---------|\n| `skills/INDEX.md` | 添加新技能的链接和简介 |\n| `README.md` | 在工具列表中补充新工具 |\n\n这些更新确保用户能够发现和访问新增的技能文档。\n\n资料来源：[README.md:37](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## Pull Request 流程\n\n### 提交 PR\n\n完成文档编写和索引更新后，打开 Pull Request：\n\n```bash\ngit add .\ngit commit -m \"feat: add linear skill documentation\"\ngit push origin skill/linear\n```\n\n### CI 测试\n\nPR 提交后，CI 流水线自动执行测试：\n\n```bash\nnpm test\n```\n\n测试内容包括：\n\n- 验证所有必需章节存在\n- 检查文件大小（≥5KB）\n- 确认摘要行非空\n- 加载所有已知技能\n\n| 测试项 | 失败后果 |\n|-------|---------|\n| 必需章节缺失 | PR 被阻止合并 |\n| 文件过短 | 提示可疑的短文件 |\n| 摘要为空 | 返回错误信息 |\n\n资料来源：[README.md:38](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 发布流程\n\n### 版本管理策略\n\nclawskills 使用语义化版本号（SemVer）：\n\n| 版本类型 | 使用场景 | 示例 |\n|---------|---------|------|\n| `patch` | 补丁版本，文档修正 | 1.0.1 → 1.0.2 |\n| `minor` | 次要版本，功能新增 | 1.0.1 → 1.1.0 |\n| `major` | 主要版本，破坏性变更 | 1.0.1 → 2.0.0 |\n\n### 发布步骤\n\n发布流程已完全自动化：\n\n1. 将 PR 合并到 `main` 分支\n2. 进入 GitHub Actions 页面\n3. 选择 **Release** 工作流\n4. 点击 **Run workflow**\n5. 选择版本类型（patch / minor / major）\n\n```mermaid\ngraph LR\n A[合并到 main] --> B[GitHub Actions]\n B --> C[触发 Release 工作流]\n C --> D[选择版本号]\n D --> E[创建 Git Tag]\n E --> F[NPM 包发布]\n F --> G[生成 Release Notes]\n```\n\n资料来源：[README.md:39-40](https://github.com/Shanksg/clawskills/blob/main/README.md)\n\n---\n\n## 治理与更新机制\n\n### 治理原则\n\n根据 ROADMAP.md，clawskills 采用以下治理策略：\n\n| 原则 | 说明 |\n|-----|------|\n| 准确性优先 | 所有端点和限制必须对照官方文档验证 |\n| 自动化维护 | CI/CD 流水线确保文档一致性 |\n| 版本控制 | 语义化版本管理变更 |\n\n### 内容更新周期\n\n技能文档的优先级排序：\n\n| 优先级 | 类型 | 说明 |\n|-------|------|------|\n| P1 | 准确性更新 | 官方 API 变更时的紧急更新 |\n| P2 | 新功能补充 | 主流工作流添加 |\n| P3 | 完善现有内容 | 边缘案例和高级用法 |\n\n资料来源：[skills/ROADMAP.md:20-30](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n---\n\n## 快速检查清单\n\n在提交贡献前，请确认以下项目：\n\n- [ ] 分支命名符合 `skill/` 规范\n- [ ] 文档包含全部 11 个必需章节\n- [ ] 所有端点和限制已对照官方文档验证\n- [ ] 已添加 `Last validated:` 日期\n- [ ] `skills/INDEX.md` 和 `README.md` 已更新\n- [ ] 参考来源章节包含有效官方链接\n- [ ] CI 测试全部通过\n\n---\n\n## 常见问题\n\n### 技能文档最小长度是多少？\n\n每个技能文档必须至少 **5KB**，CI 测试会检查文件大小。短文件会被标记为可疑并阻止合并。\n\n### 可以跳过某些章节吗？\n\n不可以。claws kills 要求所有 11 个章节都必须存在且非空。\n\n### 如何验证认证流程是否正确？\n\n请直接对照官方供应商文档。例如，Salesforce 的 OAuth 流程应参考官方 Developer Guide。禁止基于第三方资料或推测编写认证内容。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Shanksg/clawskills\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1161910025 | https://github.com/Shanksg/clawskills | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1161910025 | https://github.com/Shanksg/clawskills | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1161910025 | https://github.com/Shanksg/clawskills | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：Shanksg/clawskills\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1161910025 | https://github.com/Shanksg/clawskills | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1161910025 | https://github.com/Shanksg/clawskills | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1161910025 | https://github.com/Shanksg/clawskills | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# clawskills - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 clawskills 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-project-structure：项目结构。围绕“项目结构”模拟一次用户任务，不展示安装或运行结果。\n3. page-mcp-server-architecture：MCP 服务器架构。围绕“MCP 服务器架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-mcp-tools：MCP 工具接口。围绕“MCP 工具接口”模拟一次用户任务，不展示安装或运行结果。\n5. page-skill-anatomy：技能文档结构。围绕“技能文档结构”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-project-structure\n输入：用户提供的“项目结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-mcp-server-architecture\n输入：用户提供的“MCP 服务器架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-mcp-tools\n输入：用户提供的“MCP 工具接口”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-skill-anatomy\n输入：用户提供的“技能文档结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-project-structure：Step 2 必须围绕“项目结构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-mcp-server-architecture：Step 3 必须围绕“MCP 服务器架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-mcp-tools：Step 4 必须围绕“MCP 工具接口”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-skill-anatomy：Step 5 必须围绕“技能文档结构”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Shanksg/clawskills\n- https://github.com/Shanksg/clawskills#readme\n- skills/asana/skill.md\n- skills/dynamics365/skill.md\n- skills/figma/skill.md\n- skills/github/skill.md\n- skills/hubspot/skill.md\n- skills/jira/skill.md\n- skills/linear/skill.md\n- skills/monday/skill.md\n- skills/notion/skill.md\n- skills/salesforce/skill.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 clawskills 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：Shanksg/clawskills\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx -y clawskills-mcp\n```\n\n来源：https://github.com/Shanksg/clawskills#readme\n\n## 来源\n\n- repo: https://github.com/Shanksg/clawskills\n- docs: https://github.com/Shanksg/clawskills#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_5c9a84a2c3d84783bc392d5f713cfdc7"
}