{
"canonical_name": "Shanksg/clawskills",
"compilation_id": "pack_c1083f92e3db4493ae5040e6f5995140",
"created_at": "2026-05-24T13:34:28.343039+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": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"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": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-data-extraction",
"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": "Open Source Tool",
"label_zh": "开源工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-open-source-tool",
"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": [
"安全审查与权限治理",
"知识库问答",
"结构化数据提取",
"节点式流程编排",
"开源工具"
],
"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": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_3ca25afbd8c246fa9810ea334a993872 | https://github.com/Shanksg/clawskills/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"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_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；最高优先级：安装坑 - 来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs。",
"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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for Shanksg/clawskills.\n\nProject:\n- Name: clawskills\n- Repository: https://github.com/Shanksg/clawskills\n- Summary: MCP server + skill docs teaching AI agents to reliably integrate with 14 SaaS APIs — auth, rate limits, recipes, and cross-tool playbooks.\n- Host target: mcp_host, claude\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: MCP server + skill docs teaching AI agents to reliably integrate with 14 SaaS APIs — auth, rate limits, recipes, and cross-tool playbooks.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. quick-start: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n2. skills-overview: Skills Library Overview. Produce one small intermediate artifact and wait for confirmation.\n3. skill-structure: Skill Document Structure. Produce one small intermediate artifact and wait for confirmation.\n4. playbooks-index: Playbooks Index. Produce one small intermediate artifact and wait for confirmation.\n5. mcp-server-architecture: MCP Server Architecture. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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": [
"安全审查与权限治理",
"知识库问答",
"结构化数据提取",
"节点式流程编排",
"开源工具"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/Shanksg/clawskills 项目说明书\n\n生成时间：2026-05-15 11:47:55 UTC\n\n## 目录\n\n- [Home - ClawSkills Overview](#home)\n- [Installation Guide](#installation)\n- [Quick Start Guide](#quick-start)\n- [Skills Library Overview](#skills-overview)\n- [Skill Document Structure](#skill-structure)\n- [Playbooks Index](#playbooks-index)\n- [MCP Server Architecture](#mcp-server-architecture)\n- [MCP Tools Reference](#mcp-tools)\n- [AI Tool Integration Guide](#ai-integration)\n- [Contributing Guide](#contributing)\n\n\n\n## Home - ClawSkills Overview\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [Skills Library Overview](#skills-overview), [MCP Server Architecture](#mcp-server-architecture)\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/servicenow/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/servicenow/skill.md)\n- [skills/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)\n \n\n# Home - ClawSkills Overview\n\n## What is ClawSkills?\n\nClawSkills is an open-source, community-driven collection of integration skill documentation for 14 popular developer tools and SaaS platforms. It provides AI-augmented developers with comprehensive, verified API reference materials delivered as a Model Context Protocol (MCP) server.\n\nThe project serves as a centralized knowledge base containing authentication patterns, rate limits, error handling, and production-ready code recipes for each integrated tool.\n\n资料来源：[README.md:1]()\n\n## Architecture\n\n### MCP Server Architecture\n\nClawSkills operates as an MCP server that AI assistants like Claude can connect to for retrieving skill documentation on demand.\n\n```mermaid\ngraph TD\n A[Claude / Claude Code] -->|MCP Protocol| B[clawskills-mcp Server]\n B --> C[Skill Files Repository]\n C --> D[skills/*.md]\n C --> E[skills/INDEX.md]\n B --> F[list_skills Tool]\n B --> G[get_skill Tool]\n B --> H[search_skills Tool]\n```\n\n### Skill Document Structure\n\nEach skill document follows a standardized 11-section template ensuring consistency across all integrations.\n\n```mermaid\ngraph TD\n A[Skill Document] --> B[Metadata & Headers]\n A --> C[Overview]\n A --> D[Authentication & Permissions]\n A --> E[Core Endpoints]\n A --> F[Common Workflows / Recipes]\n A --> G[Error Handling]\n A --> H[Rate Limits]\n A --> I[Webhooks]\n A --> J[Reliability Patterns]\n A --> K[QA Checklist]\n A --> L[Sources]\n```\n\n资料来源：[README.md:24]()\n\n## Supported Tools\n\nThe project currently covers 14 widely-used enterprise tools.\n\n| Category | Tools Supported |\n|----------|-----------------|\n| **Project Management** | Jira, Linear, Asana, Monday.com |\n| **CRM & Sales** | Salesforce, HubSpot, Dynamics 365 |\n| **Design** | Figma |\n| **IT Service Management** | ServiceNow |\n| **Communication** | Slack |\n| **Finance** | Stripe |\n| **Knowledge Management** | Notion |\n| **Version Control** | GitHub |\n\n资料来源：[skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n\n## Available MCP Tools\n\nThe ClawSkills MCP server exposes three tools for AI assistants:\n\n### list_skills\n\nReturns a list of all available skill documents in the repository.\n\n### get_skill\n\nRetrieves a complete skill document or a specific section. Supports partial retrieval of:\n- `auth` — Authentication and permissions\n- `rate-limits` — Rate limiting information\n- `recipes` — Common workflow patterns\n- `errors` — Error handling patterns\n\n### search_skills\n\nPerforms full-text search across all skill documents to find relevant content.\n\n资料来源：[README.md:45-50]()\n\n## Installation\n\n### Quick Start (npx)\n\n```bash\nnpx -y clawskills-mcp\n```\n\n### Permanent Installation\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n### Claude Desktop Configuration\n\nAdd to your Claude Desktop or Claude Code configuration file:\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:38-43]()\n\n## Development Phases\n\nThe project follows a structured 5-phase development roadmap:\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 | Foundation (Auth + Core CRUD) | ✅ Complete — all 14 tools |\n| Phase 2 | High-Frequency Workflows (6-12 recipes per tool) | ✅ Complete — all 14 tools |\n| Phase 3 | Event-Driven & Real-Time (webhooks, signatures) | ✅ Complete — all 14 tools |\n| Phase 4 | Bulk & Advanced Operations | ⚠️ Partial |\n| Phase 5 | Cross-Tool Orchestration | ❌ Not started |\n\n资料来源：[skills/ROADMAP.md:1-30]()\n\n## CI/CD Pipeline\n\nThe project includes automated quality assurance:\n\n### Release Automation\n\nReleases are fully automated via GitHub Actions:\n1. Merge to `main` branch\n2. Navigate to GitHub Actions → **Release** workflow\n3. Run workflow with desired version bump (patch/minor/major)\n\n### Testing Pipeline\n\nThe CI pipeline (`ci.yml`) runs on every push and pull request:\n- Build verification\n- Unit tests with Vitest\n- Real-skills validation (all 14 tools must have required sections)\n- Minimum file size requirements (≥5 KB per skill)\n\n资料来源：[skills/ROADMAP.md:18-22]()\n\n## Contributing Guidelines\n\n### Adding a New Skill\n\n1. **Create a branch**: `git checkout -b skill/`\n2. **Follow the template**: Use any existing `skill.md` as reference — all 11 sections required\n3. **Verify documentation**: Test all endpoints, rate limits, and auth flows against official vendor documentation\n4. **Add validation date**: Include `Last validated:` date in the doc header\n5. **Update indices**: Modify `skills/INDEX.md` and `README.md`\n6. **Add sources**: Link to official sources in the `## Sources` section\n7. **Open PR**: CI automatically runs `npm test` for validation\n\n资料来源：[README.md:10-18]()\n\n## Rate Limit Management\n\nEach skill document includes platform-specific rate limiting patterns. Key patterns observed across tools:\n\n| Platform | Key Characteristic |\n|----------|-------------------|\n| Linear | Complexity-based scoring with `X-Complexity` header |\n| Dynamics 365 | 6,000 requests per 5 minutes, 52 concurrent max |\n| Notion | 3 requests/second limit |\n| Stripe | 25 requests/second burst limit |\n| Figma | Plan-dependent varying limits |\n\n资料来源：[skills/linear/skill.md:100-105](), [skills/dynamics365/skill.md:150-155](), [skills/ROADMAP.md:8]()\n\n## Authentication Patterns\n\nCommon authentication methods across supported tools:\n\n```mermaid\ngraph TD\n A[Authentication Methods] --> B[OAuth 2.0]\n A --> C[API Keys / PAT]\n A --> D[Bearer Tokens]\n A --> E[Webhook Signatures]\n \n B --> B1[Authorization Code Flow]\n B --> B2[Client Credentials]\n \n C --> C1[Linear API Keys]\n C --> C2[Figma PAT]\n C --> C3[ServiceNow Basic Auth]\n```\n\n资料来源：[skills/linear/skill.md:1-15](), [skills/figma/skill.md:40-60]()\n\n## Best Practices\n\n### For AI Tool Integration\n\n1. **Reference specific sections**: Load only the relevant authentication or endpoint section\n2. **Use full skill as context**: For complex workflows, load the complete skill document as system prompt\n3. **Follow documented patterns**: Always use the exact auth patterns, rate limit handling, and error codes specified in the skill docs\n\n### Example: Loading Skill as Context\n\n```python\nimport anthropic\n\nwith open(\"skills/jira/skill.md\") as f:\n jira_skill = f.read()\n\nclient = anthropic.Anthropic()\nresponse = client.messages.create(\n model=\"claude-sonnet-4-20250514\",\n max_tokens=1024,\n system=jira_skill,\n messages=[{\"role\": \"user\", \"content\": \"Write code to...\"}]\n)\n```\n\n资料来源：[README.md:60-72]()\n\n## Project Status\n\nClawSkills is production-ready with the following characteristics:\n\n| Aspect | Status |\n|--------|--------|\n| License | MIT |\n| Package | Public npm registry |\n| Documentation | All 14 tools complete |\n| CI/CD | Automated releases via GitHub Actions |\n| OIDC Authentication | Enabled for secure publishing |\n\n资料来源：[skills/ROADMAP.md:22-25]()\n\n## Next Development Phase\n\n### Priority 1 — Freshness and Accuracy Pipeline\n\nThe project maintainers are focused on keeping documentation accurate as vendor APIs evolve. A pipeline to automatically validate and update skill documents against official API changes is planned.\n\n资料来源：[skills/ROADMAP.md:33-36]()\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Home - ClawSkills Overview](#home), [Quick Start Guide](#quick-start), [MCP Server Architecture](#mcp-server-architecture)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\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- [mcp-server/Dockerfile](https://github.com/Shanksg/clawskills/blob/main/mcp-server/Dockerfile)\n \n\n# Installation Guide\n\n## Overview\n\nThis guide covers all installation methods for **clawskills**, a skill documentation library providing integration guides for 14 enterprise tools including Jira, Salesforce, Figma, Slack, Linear, and others. The repository can be used as a standalone skill reference or as an MCP (Model Context Protocol) server that AI assistants like Claude can query dynamically.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[clawskills Repository] --> B[MCP Server]\n A --> C[Static Skill Docs]\n B --> D[Claude Desktop]\n B --> E[Claude Code]\n B --> F[Custom AI Apps]\n \n G[MCP Tools] --> H[list_skills]\n G --> I[get_skill]\n G --> J[search_skills]\n \n B --> G\n```\n\n## Installation Methods\n\n### Method 1: NPX (Temporary Use)\n\nExecute the MCP server without installation using npx:\n\n```bash\nnpx -y clawskills-mcp\n```\n\nThis method is useful for:\n- One-time testing\n- CI/CD pipelines\n- Temporary integrations\n\n资料来源：[README.md:1]()\n\n### Method 2: Global NPM Installation\n\nInstall the package globally for persistent access:\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n**Prerequisites:**\n- Node.js 18.x or higher\n- npm 9.x or higher\n\n资料来源：[mcp-server/README.md]()\n\n### Method 3: Docker Deployment\n\nDeploy the MCP server as a containerized service:\n\n```bash\ndocker build -t clawskills-mcp ./mcp-server\ndocker run -p 3000:3000 clawskills-mcp\n```\n\n**Docker Configuration:**\n\n| Port | Protocol | Purpose |\n|------|----------|---------|\n| 3000 | HTTP | MCP server endpoint |\n| 3001 | HTTPS | Secure MCP endpoint (with TLS) |\n\n资料来源：[mcp-server/Dockerfile]()\n\n## MCP Client Configuration\n\n### Claude Desktop Configuration\n\nAdd the clawskills MCP server to your Claude Desktop configuration file:\n\n**File Location:**\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n**Configuration Template:**\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n**Alternative: Using Global Installation Path**\n\nIf installed globally, reference the installed binary:\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"clawskills-mcp\",\n \"args\": []\n }\n }\n}\n```\n\n资料来源：[README.md:1]()\n\n### Claude Code Configuration\n\nFor Claude Code, add the same configuration to your Claude Code settings file:\n\n**File Location:** `~/.claude/settings.json` or project `.claude/CLAUDE.md`\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## Available MCP Tools\n\nOnce connected, the following three tools are available:\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `list_skills` | List all available skill documentation | None |\n| `get_skill` | Fetch a specific skill doc | `skill_name`, `section` (optional) |\n| `search_skills` | Full-text search across all skills | `query` |\n\n**Tool Usage Example:**\n\n```python\n# Example: List all available skills\nresult = list_skills()\n\n# Example: Get specific skill documentation\nresult = get_skill(skill_name=\"jira\", section=\"auth\")\n\n# Example: Search for specific content\nresult = search_skills(query=\"webhook signature verification\")\n```\n\n资料来源：[README.md:1]()\n\n## Environment Configuration\n\n### Package.json Dependencies\n\nThe MCP server requires the following runtime dependencies:\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| `mcp` | ^1.0.0 | MCP protocol implementation |\n| `typescript` | ^5.0.0 | Type safety |\n| `zod` | ^3.0.0 | Schema validation |\n\n资料来源：[mcp-server/package.json]()\n\n### Runtime Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `NODE_ENV` | No | `production` | Runtime environment |\n| `PORT` | No | `3000` | Server port |\n| `LOG_LEVEL` | No | `info` | Logging verbosity |\n\n## Verification\n\n### Test the Installation\n\nVerify the MCP server is correctly installed and accessible:\n\n```bash\n# Test npx execution\nnpx -y clawskills-mcp --version\n\n# Test Docker container\ndocker run clawskills-mcp --health-check\n```\n\n### Verify MCP Connection\n\nAfter configuring Claude Desktop:\n\n1. Restart Claude Desktop\n2. Check for the clawskills server in the MCP servers list\n3. Send a test query: `list_skills`\n\n## Integration with Claude Code\n\n### Project-Level Integration\n\nCreate a `.claude/CLAUDE.md` file in your project to define when to use skill docs:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the\ncorresponding skill doc before writing code:\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\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\nAlways pin API version headers where specified.\n```\n\n资料来源：[README.md:1]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| `npx: command not found` | Node.js not installed | Install Node.js 18+ |\n| MCP server not connecting | Configuration file error | Validate JSON syntax |\n| Skills not loading | Outdated package version | Run `npm update -g clawskills-mcp` |\n| Docker port conflict | Port 3000 in use | Change port mapping: `-p 3001:3000` |\n\n### Health Check Endpoint\n\nWhen running in Docker or as a standalone server:\n\n```bash\ncurl http://localhost:3000/health\n```\n\nExpected response:\n\n```json\n{\n \"status\": \"healthy\",\n \"version\": \"1.0.0\",\n \"uptime\": 3600\n}\n```\n\n## Next Steps\n\nAfter installation, proceed to:\n\n1. **Authentication Setup** — Configure credentials for your target tools\n2. **Skill Selection** — Identify relevant skills for your integration\n3. **Recipe Implementation** — Follow the workflow recipes in each skill doc\n4. **Rate Limit Planning** — Review rate limiting for your use case\n\n资料来源：[skills/ROADMAP.md:1]()\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [MCP Tools Reference](#mcp-tools), [AI Tool Integration Guide](#ai-integration)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\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- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.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 \n\n# Quick Start Guide\n\n## Overview\n\nClawSkills is a comprehensive skill documentation library for integrating AI tools with popular SaaS platforms. It provides standardized documentation covering authentication patterns, rate limits, API workflows, error handling, and cross-tool orchestration recipes for 14 supported tools.\n\n资料来源：[README.md:1]()\n\n## Supported Tools\n\n| Category | Tools |\n|----------|-------|\n| **Project Management** | Jira, Linear, Asana, Monday.com |\n| **Communication** | Slack |\n| **Design** | Figma |\n| **CRM & Sales** | Salesforce, HubSpot, Dynamics 365 |\n| **IT Service Management** | ServiceNow |\n| **Customer Support** | Zendesk |\n| **Development** | GitHub |\n| **Documentation** | Notion, Stripe |\n\n资料来源：[README.md:18-31]()\n\n## Installation\n\n### Option 1: Quick Run (npx)\n\n```bash\nnpx -y clawskills-mcp\n```\n\n资料来源：[README.md:64]()\n\n### Option 2: Global Installation\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n资料来源：[README.md:68]()\n\n## MCP Server Configuration\n\nAdd ClawSkills to your Claude Desktop or Claude Code configuration:\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:73-80]()\n\n## Available Tools\n\nThe MCP server exposes three tools for accessing skill documentation:\n\n| Tool | Purpose | Parameters |\n|------|---------|-------------|\n| `list_skills` | List all available skill documents | None |\n| `get_skill` | Fetch full skill or specific section | `skill_name`, `section` (optional) |\n| `search_skills` | Full-text search across all skills | `query` |\n\n资料来源：[mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n## Authentication Patterns\n\n### Personal Access Tokens (PAT)\n\nRecommended for server-to-server integrations:\n\n```bash\n# Figma example\ncurl https://api.figma.com/v1/me \\\n -H \"X-Figma-Token: YOUR_PAT\"\n```\n\n资料来源：[skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)\n\n### OAuth 2.0\n\nRecommended for user-facing applications:\n\n```bash\n# Linear OAuth flow\nGET https://api.linear.app/oauth/token\n ?client_id=...\n &client_secret=...\n &redirect_uri=...\n &grant_type=authorization_code\n```\n\n资料来源：[skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n\n### API Token + Basic Auth\n\nCommon for Jira Cloud integrations:\n\n```bash\nAUTH=\"Basic $(echo -n 'email:api_token' | base64)\"\ncurl -H \"Authorization: $AUTH\" \"$BASE/rest/api/3/issue/PROJ-42\"\n```\n\n资料来源：[skills/jira/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)\n\n## Usage with Claude\n\n### Method 1: Reference Skill Sections\n\nPaste relevant skill documentation into your conversation:\n\n```\n[paste the \"Authentication & permissions\" section from skills/salesforce/skill.md]\n\nWrite a Python function that exchanges a JWT for an access token\nand caches it until 5 minutes before expiry.\n```\n\n资料来源：[README.md:91-97]()\n\n### Method 2: Load Skill as System Context\n\n```python\nimport anthropic\n\nwith open(\"skills/jira/skill.md\") as f:\n jira_skill = f.read()\n\nclient = anthropic.Anthropic()\nresponse = client.messages.create(\n model=\"claude-sonnet-4-20250514\",\n max_tokens=1024,\n system=f\"Follow the auth patterns, rate limit handling, and error codes exactly as documented in:\\n{jira_skill}\",\n messages=[\n {\"role\": \"user\", \"content\": \"Create a Jira issue for a new bug report\"}\n ]\n)\n```\n\n资料来源：[README.md:107-123]()\n\n## Integration Agent Pattern\n\nFor multi-tool workflows, use the integration agent pattern:\n\n```python\nimport anthropic\n\nclient = anthropic.Anthropic()\n\ndef run_integration_agent(task: str, tools_needed: list[str]) -> str:\n \"\"\"Route a cross-tool integration task to Claude with relevant skills.\"\"\"\n \n # Load required skill docs\n skills_context = []\n for tool in tools_needed:\n try:\n with open(f\"skills/{tool}/skill.md\") as f:\n skills_context.append(f\"# {tool.upper()} Skill\\n{f.read()}\")\n except FileNotFoundError:\n pass\n \n response = client.messages.create(\n model=\"claude-sonnet-4-20250514\",\n max_tokens=2048,\n system=\"You are an integration specialist. Follow the skill documentation exactly.\",\n messages=[\n {\"role\": \"system\", \"content\": \"\\n\\n---\\n\\n\".join(skills_context)},\n {\"role\": \"user\", \"content\": task}\n ]\n )\n return response.content[0].text\n\n# Example\nresult = run_integration_agent(\n task=\"Write a Python script that syncs Zendesk tickets (status=open, priority=urgent) to Jira bugs.\",\n tools_needed=[\"zendesk\", \"jira\"]\n)\n```\n\n资料来源：[README.md:42-58]()\n\n## Project Instruction Integration\n\nFor Claude Code users, add skill references to your project instruction file:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the\ncorresponding skill doc before writing code:\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\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\nAlways pin API version headers where specified.\n```\n\n资料来源：[README.md:126-148]()\n\n## Cross-Tool Workflow Example\n\nThe Slack-Jira incident playbook demonstrates multi-tool integration:\n\n```mermaid\ngraph TD\n A[Slack Alert Received] --> B{Existing Jira Issue?}\n B -->|No| C[Create Jira Issue]\n B -->|Yes| D[Update Existing Issue]\n C --> E[Post Link to Slack Thread]\n D --> E\n E --> F{Optional: Status Sync}\n F -->|Enabled| G[Mirror Jira Status → Slack]\n```\n\n资料来源：[playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n\nKey workflow steps:\n1. Detect incident trigger in Slack channel\n2. Extract correlation key from message context\n3. Resolve Slack message permalink\n4. Search Jira for existing issue with correlation key\n5. Create or update Jira issue with Slack context\n6. Reply in Slack thread with Jira link\n\n## Rate Limit Handling\n\nEach skill documents specific rate limits. General patterns:\n\n| Tool | Auth Type | Requests/Hour | Notes |\n|------|-----------|---------------|-------|\n| Linear | API key | 5,000 | 250,000 complexity pts/hr |\n| Linear | OAuth | 5,000 | 2,000,000 complexity pts/hr |\n| Figma | PAT | 1,000 | Per API token |\n\nAlways implement retry logic with `Retry-After` header respect:\n\n```python\ndef make_request(url, headers, max_retries=3):\n for attempt in range(max_retries):\n response = requests.get(url, headers=headers)\n if response.status_code == 429:\n wait_time = int(response.headers.get(\"Retry-After\", 60))\n time.sleep(wait_time)\n continue\n return response\n raise Exception(\"Max retries exceeded\")\n```\n\n## Skill Document Structure\n\nEach skill follows an 11-section template:\n\n| Section | Content |\n|---------|---------|\n| Overview | Tool description, API type, key capabilities |\n| Authentication & permissions | Auth methods, scopes, token lifetimes |\n| Core capabilities | API resources and endpoints |\n| Common workflows (recipes) | 6-12 working examples per tool |\n| Rate limits & reliability | Limits, retries, idempotency |\n| Error codes & handling | Error responses and solutions |\n| Security & compliance | Privacy, data handling |\n| Testing checklist | Verification procedures |\n| Sources | Official vendor documentation links |\n\n资料来源：[README.md:33-35]()\n\n## Contributing New Skills\n\n1. Create branch: `git checkout -b skill/`\n2. Follow the template structure in any existing `skill.md`\n3. Verify all endpoints, rate limits, and auth flows against official docs\n4. Add `Last validated:` date to doc header\n5. Update `skills/INDEX.md` and `README.md`\n6. Open PR — CI runs `npm test` to validate skill loads with all required sections\n\n资料来源：[README.md:33-45]()\n\n## Release Process\n\nReleases are automated:\n1. Merge PR to `main`\n2. Navigate to GitHub Actions → **Release** → Run workflow\n3. Select version bump: `patch` / `minor` / `major`\n\n资料来源：[README.md:51-53]()\n\n## Roadmap\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 | Foundation (Auth + Core CRUD) | ✅ Complete |\n| Phase 2 | High-Frequency Workflows | ✅ Complete |\n| Phase 3 | Event-Driven & Real-Time | ✅ Complete |\n| Phase 4 | Bulk & Advanced Operations | ⚠️ Partial |\n| Phase 5 | Cross-Tool Orchestration | ❌ Not started |\n\n资料来源：[skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n---\n\n\n\n## Skills Library Overview\n\n### 相关页面\n\n相关主题：[Skill Document Structure](#skill-structure), [Playbooks Index](#playbooks-index), [Home - ClawSkills Overview](#home)\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/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.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/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# Skills Library Overview\n\n## 1. Introduction\n\nThe ClawSkills repository is a comprehensive library of integration skill documentation for connecting AI assistants with popular enterprise tools and SaaS platforms. It provides standardized, production-ready documentation that covers authentication flows, API endpoints, rate limits, error handling, and common workflow recipes for 14 different tools.\n\n资料来源：[README.md:1-30]()\n\n### 1.1 Purpose and Scope\n\nThe library serves as a unified reference for developers building integrations with external services. Each skill document follows a consistent 11-section structure that ensures complete coverage of:\n\n- Authentication mechanisms (API keys, OAuth 2.0, JWT)\n- Rate limiting policies and retry strategies\n- Core API operations (CRUD operations)\n- Common workflow patterns (recipes)\n- Error codes and troubleshooting\n- Webhook configurations for event-driven architectures\n\n### 1.2 Supported Tools\n\nThe library currently includes comprehensive documentation for 14 enterprise tools:\n\n| Category | Tools |\n|----------|-------|\n| Project Management | Jira, Linear, Monday.com, Asana |\n| CRM/Sales | Salesforce, HubSpot, Dynamics 365 |\n| Support/Service | Zendesk, ServiceNow |\n| Communication | Slack |\n| Design | Figma |\n| Development | GitHub |\n| Payments | Stripe |\n| Knowledge Base | Notion |\n\n资料来源：[README.md:80-95]()\n\n---\n\n## 2. Architecture\n\n### 2.1 Repository Structure\n\n```\nclawskills/\n├── skills/ # Skill documentation files\n│ ├── INDEX.md # Master index of all skills\n│ ├── ROADMAP.md # Development roadmap\n│ ├── monday/skill.md\n│ ├── salesforce/skill.md\n│ ├── jira/skill.md\n│ ├── dynamics365/skill.md\n│ ├── hubspot/skill.md\n│ ├── servicenow/skill.md\n│ ├── zendesk/skill.md\n│ ├── asana/skill.md\n│ ├── github/skill.md\n│ ├── figma/skill.md\n│ ├── slack/skill.md\n│ ├── stripe/skill.md\n│ ├── notion/skill.md\n│ └── linear/skill.md\n├── playbooks/ # Cross-tool orchestration recipes\n│ ├── slack-jira-incident.md\n│ └── ...\n├── mcp-server/ # Model Context Protocol server\n│ ├── src/\n│ │ ├── index.ts\n│ │ └── index.test.ts\n│ └── package.json\n└── README.md\n```\n\n### 2.2 Skill Document Structure\n\nEach skill follows a mandatory 11-section template that ensures consistency across all tool documentation:\n\n```mermaid\ngraph TD\n A[Skill Document] --> B[Authentication & Permissions]\n A --> C[Base URL & API Version]\n A --> D[Core Operations]\n A --> E[Rate Limits & Retries]\n A --> F[Error Handling]\n A --> G[Webhook Configuration]\n A --> H[Recipes]\n A --> I[Data Models]\n A --> J[Common Errors]\n A --> K[QA Checklist]\n A --> L[Sources]\n```\n\n资料来源：[skills/ROADMAP.md:1-20]()\n\n### 2.3 MCP Server Integration\n\nThe ClawSkills MCP server enables AI assistants (specifically Claude) to access skill documentation programmatically. It exposes three main tools:\n\n| Tool | Function |\n|------|----------|\n| `list_skills` | Enumerate all available skill documents |\n| `get_skill` | Fetch a full skill or specific section |\n| `search_skills` | Full-text search across all skills |\n\n资料来源：[README.md:50-60]()\n\n---\n\n## 3. Authentication Patterns\n\n### 3.1 Supported Authentication Methods\n\nEach tool supports specific authentication mechanisms documented consistently across skills:\n\n| Auth Method | Tools | Description |\n|-------------|-------|-------------|\n| API Key | Most tools | Static token in header or query param |\n| OAuth 2.0 | Linear, Figma, HubSpot | Authorization code flow with refresh tokens |\n| PAT (Personal Access Token) | GitHub, Figma | User-generated tokens for server-to-server |\n| Bearer Token | Notion, Stripe | Token-based authentication |\n\n### 3.2 Linear OAuth Example\n\n```bash\n# Authorization URL\nGET https://api.linear.app/oauth\n ?client_id=CLIENT_ID\n &redirect_uri=REDIRECT_URI\n &scope=read,write\n &state=RANDOM_STATE\n &response_type=code\n\n# Token Exchange\ncurl -X POST https://api.linear.app/oauth/token \\\n -d \"grant_type=authorization_code&code=AUTH_CODE&client_id=...&client_secret=...\"\n```\n\n资料来源：[skills/linear/skill.md:50-80]()\n\n### 3.3 Token Lifecycle Management\n\nPost-October 2025 Linear apps use 24-hour access tokens with refresh token rotation:\n\n```bash\n# Refresh access token\ncurl -X POST https://api.linear.app/oauth/token \\\n -d \"grant_type=refresh_token&refresh_token=&client_id=&client_secret=\"\n```\n\n资料来源：[skills/linear/skill.md:75-85]()\n\n---\n\n## 4. Rate Limiting Policies\n\n### 4.1 Rate Limit Overview by Tool\n\n| Tool | Auth Type | Requests/Hour | Complexity Points/Hour |\n|------|-----------|---------------|------------------------|\n| Linear | API Key | 5,000 | 250,000 |\n| Linear | OAuth | 5,000 | 2,000,000 |\n| Linear | Unauthenticated | 60 | 10,000 |\n| Figma | Varies by plan | Plan-dependent | — |\n| Notion | Standard | 3 req/sec | — |\n\n### 4.2 Retry Strategy Pattern\n\nThe library documents standard retry patterns for handling rate limits:\n\n```python\nimport time\nimport requests\n\ndef fetch_with_retry(url, headers, max_retries=3):\n for attempt in range(max_retries):\n response = requests.get(url, headers=headers)\n \n if response.status_code == 429:\n retry_after = int(response.headers.get('Retry-After', 60))\n print(f\"Rate limited. Waiting {retry_after}s...\")\n time.sleep(retry_after)\n continue\n \n return response\n \n raise Exception(\"Max retries exceeded\")\n```\n\n### 4.3 Complexity-Based Limiting\n\nLinear uses complexity-based rate limiting where requesting fewer fields costs fewer complexity points. The `X-Complexity` response header indicates query cost.\n\n资料来源：[skills/linear/skill.md:35-50]()\n\n---\n\n## 5. Webhook Configuration\n\n### 5.1 Webhook Architecture\n\n```mermaid\nsequenceDiagram\n participant Vendor as External API\n participant Handler as Your Endpoint\n participant Storage as Data Store\n \n Vendor->>Handler: POST /webhook (event payload)\n Handler->>Handler: Verify signature\n Handler->>Handler: Parse event type\n Handler->>Storage: Store/update record\n Handler-->>Vendor: 200 OK\n```\n\n### 5.2 Webhook Security Patterns\n\n| Tool | Security Method | Implementation |\n|------|-----------------|----------------|\n| HubSpot | HMAC-SHA256 | `X-HubSpot-Signature-v3` header |\n| Linear | Signature | `Linear-Signature` header |\n| Slack | Signing Secret | HMAC verification |\n| Jira | URL Secret | Query param `?secret=abc123` |\n| Stripe | Webhook Secret | `Stripe-Signature` header |\n\n### 5.3 HubSpot Webhook Signature Verification\n\n```python\nimport hmac\nimport hashlib\n\ndef verify_hubspot_signature(payload: bytes, signature: str, client_secret: str) -> bool:\n expected = hmac.new(\n client_secret.encode(),\n payload,\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(f\"sha256={expected}\", signature)\n```\n\n资料来源：[skills/hubspot/skill.md:80-95]()\n\n---\n\n## 6. Common Workflows (Recipes)\n\n### 6.1 Cross-Tool Orchestration: Slack → Jira Incident Management\n\nThe playbooks directory contains cross-tool recipes. The Slack-Jira incident playbook demonstrates multi-system integration:\n\n```mermaid\ngraph LR\n A[Slack Alert] --> B[Verify Channel]\n B --> C[Fetch Thread Context]\n C --> D[Get Message Permalink]\n D --> E{Search Existing Jira}\n E -->|Found| F[Link to Existing]\n E -->|Not Found| G[Create Jira Issue]\n G --> H[Post Link in Slack]\n H --> I[Pin Bot Reply]\n```\n\n资料来源：[playbooks/slack-jira-incident.md:1-30]()\n\n### 6.2 Field Mapping\n\n| Slack | Jira |\n|-------|------|\n| Correlation key: `slack:{team_id}:{channel_id}:{ts}` | Stored as label or custom field |\n| Message text | Issue description |\n| Thread replies | Additional context in description |\n| Trigger type | Determines correlation key source |\n\n资料来源：[playbooks/slack-jira-incident.md:45-55]()\n\n### 6.3 Linear Issue Management Recipes\n\n| Recipe | Description |\n|--------|-------------|\n| Create issue | GraphQL mutation with title, description, state |\n| List issues | Paginated query with filtering |\n| Update issue | Mutation targeting specific fields |\n| Post comment | Attach context to existing issues |\n| Create attachment | Link external resources (Sentry, GitHub, Zendesk) |\n| Incremental sync | Filter by `updatedAt` timestamp |\n\n资料来源：[skills/linear/skill.md:90-140]()\n\n---\n\n## 7. Error Handling\n\n### 7.1 Standard Error Response Structure\n\nMost APIs return structured error responses:\n\n```json\n{\n \"error\": \"RATELIMITED\",\n \"message\": \"Rate limit exceeded\",\n \"retryAfter\": 3600\n}\n```\n\n### 7.2 Common Error Codes by Tool\n\n| Code | Meaning | Resolution |\n|------|---------|------------|\n| `429` | Rate limited | Wait and retry with backoff |\n| `401` | Unauthorized | Check/revoke and regenerate token |\n| `403` | Forbidden | Verify scopes and permissions |\n| `404` | Not found | Validate resource ID |\n| `400` | Bad request | Check payload format |\n| `500` | Server error | Retry with idempotency key |\n\n### 7.3 Slack-Specific Errors\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `invalid_channel` | Channel doesn't exist | Verify channel ID |\n| `channel_not_found` | Bot not in channel | Invite bot to channel |\n| `cant_update_message` | Not original poster | Only original bot can update |\n| `missing_thread_ts` | Thread reply without parent | Include `thread_ts` parameter |\n\n资料来源：[skills/slack/skill.md:120-140]()\n\n---\n\n## 8. Development and Contribution\n\n### 8.1 Adding a New Skill\n\nTo contribute a new skill, follow these steps:\n\n```bash\n# 1. Create a branch\ngit checkout -b skill/\n\n# 2. Follow the template structure (11 sections required)\n# 3. Verify all endpoints against official vendor docs\n# 4. Add Last validated: date to doc header\n# 5. Update skills/INDEX.md and README.md\n# 6. Open PR — CI runs npm test\n```\n\n资料来源：[README.md:20-35]()\n\n### 8.2 CI Pipeline\n\nThe repository uses GitHub Actions for continuous integration:\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| `ci.yml` | Push/PR | Build and test |\n| `release.yml` | Manual dispatch | Version bump, tag, npm publish |\n\n### 8.3 Test Suite Requirements\n\nThe test suite validates that every skill:\n\n- [ ] Loads successfully\n- [ ] Has all 11 required sections\n- [ ] Contains a non-empty summary line\n- [ ] Is at least 5KB in size (prevents truncated documentation)\n\n资料来源：[mcp-server/src/index.test.ts:30-50]()\n\n---\n\n## 9. Roadmap and Future Development\n\n### 9.1 Completed Phases\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 | Foundation (Auth + Core CRUD) | ✅ Complete — all 14 tools |\n| Phase 2 | High-Frequency Workflows (6-12 recipes/tool) | ✅ Complete — all 14 tools |\n| Phase 3 | Event-Driven & Real-Time (Webhooks) | ✅ Complete — all 14 tools |\n| Phase 4 | Bulk & Advanced Operations | ⚠️ Partial — documented for most tools |\n\n### 9.2 Upcoming Development\n\n| Priority | Initiative | Description |\n|----------|-------------|-------------|\n| Phase A | Freshness Pipeline | Automated accuracy checks against vendor API changes |\n| Phase 5 | Cross-Tool Orchestration | Dedicated recipes for multi-system workflows |\n| Phase B | SDK Generation | Auto-generate typed clients from skill docs |\n\n资料来源：[skills/ROADMAP.md:25-50]()\n\n---\n\n## 10. Usage with Claude\n\n### 10.1 Installation Options\n\n**Temporary usage:**\n```bash\nnpx -y clawskills-mcp\n```\n\n**Permanent installation:**\n```bash\nnpm install -g clawskills-mcp\n```\n\n### 10.2 Claude Desktop Configuration\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n### 10.3 Usage in Claude Code\n\nReference skills in your project instruction file:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the\ncorresponding skill doc before writing code:\n\n- Monday.com → @skills/monday/skill.md\n- Salesforce → @skills/salesforce/skill.md\n- Jira → @skills/jira/skill.md\n...\n\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\n```\n\n资料来源：[README.md:100-130]()\n\n---\n\n## 11. Best Practices\n\n### 11.1 API Integration Guidelines\n\n1. **Always validate webhook signatures** before processing payloads\n2. **Implement exponential backoff** for rate limit handling\n3. **Use idempotency keys** for create/update operations\n4. **Pin API version headers** where specified (e.g., `Notion-Version: 2025-09-03`)\n5. **Monitor complexity headers** (Linear) to optimize query costs\n\n### 11.2 Debug Logging Standards\n\n| DO Log | DON'T Log |\n|--------|-----------|\n| API method name | Token values |\n| Request/response status | Full message text (may contain PII) |\n| HTTP status codes | File contents |\n| Error codes | Raw credentials |\n\n### 11.3 Security Recommendations\n\n- Use granular scopes instead of deprecated broad permissions (e.g., Figma's `files:read`)\n- Rotate tokens before expiry\n- Store secrets in environment variables, never in code\n- Implement least-privilege access for OAuth scopes\n\n---\n\n## 12. Summary\n\nThe ClawSkills library provides production-ready, standardized documentation for integrating AI assistants with 14 enterprise tools. Its consistent structure, comprehensive coverage of authentication and error handling, and automated validation ensure reliable integrations. The MCP server enables seamless access for Claude and similar AI assistants, while the playbook system supports sophisticated cross-tool workflows.\n\n资料来源：[README.md:1-50]()\n资料来源：[skills/ROADMAP.md:1-30]()\n\n---\n\n\n\n## Skill Document Structure\n\n### 相关页面\n\n相关主题：[Skills Library Overview](#skills-overview), [Contributing Guide](#contributing), [Playbooks Index](#playbooks-index)\n\n\nRelevant Source Files
\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/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/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)\n- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/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- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n \n\n# Skill Document Structure\n\n## Overview\n\nThe **Skill Document Structure** is the standardized, self-contained Markdown format used to document every tool integration in the `clawskills` repository. Each skill doc captures everything an AI agent needs to reliably call an external API — authentication flows, rate limits, error codes, common recipes, and webhook patterns — without requiring external research. 资料来源：[README.md:1-10]()\n\nThe repository currently covers **14 tools**: Monday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Figma, Slack, Stripe, Notion, and Linear. 资料来源：[README.md:60-61]()\n\nThe skill system serves two primary consumers:\n\n1. **AI agents** (Claude Code, Copilot, LangChain/LlamaIndex RAG pipelines) — query skill docs to write integration code correctly on the first attempt.\n2. **Human developers** — use skill docs as a reference when building or debugging cross-tool workflows.\n\n### Design Principles\n\n| Principle | Implication |\n|-----------|-------------|\n| **Self-contained** | No external links required to make a working API call |\n| **Vendor-verified** | Every endpoint, scope, and rate limit is cross-checked against official docs before publishing |\n| **Version-pinned** | Auth flows and API versions are pinned to specific vendor versions (e.g., Notion `2025-09-03`) |\n| **Machine-readable** | The MCP server parses skill docs at runtime; tools can retrieve arbitrary sections |\n\n---\n\n## Architecture\n\n### Repository Layout\n\n```\nclawskills/\n├── skills/\n│ ├── INDEX.md # Master list of all skills\n│ ├── ROADMAP.md # Governance and update cadence\n│ ├── monday/skill.md\n│ ├── salesforce/skill.md\n│ ├── jira/skill.md\n│ ├── hubspot/skill.md\n│ └── ... (14 tools total)\n├── playbooks/ # Cross-tool orchestration recipes\n├── mcp-server/ # Model Context Protocol server\n│ ├── src/index.test.ts # Skill validation tests\n│ └── README.md # MCP tool interface\n└── README.md\n```\n\n### How Skills Flow into the MCP Server\n\nThe MCP server exposes three tools — `get_skill`, `search_skills`, and `list_skills` — that load and parse skill documents at runtime. This means skill docs are not compiled into the binary; the server reads the Markdown files directly from `skills/` on each invocation. 资料来源：[mcp-server/README.md:1-20]()\n\n```mermaid\ngraph TD\n A[AI Agent Request] --> B[MCP Server Tool Call]\n B --> C{Which tool?}\n C -->|list_skills| D[Enumerate all skill.md files]\n C -->|get_skill| E[Load specific skill.md + section]\n C -->|search_skills| F[Full-text search across all skill.md]\n E --> G[Extract requested section]\n F --> H[Return ±3 line excerpts, max 5 per skill]\n D --> I[skills/INDEX.md]\n I --> J[AI Agent receives skill content]\n G --> J\n H --> J\n J --> K[Agent writes / executes integration code]\n```\n\n---\n\n## Required Sections\n\nEvery skill file must contain **all 11 required sections** in order. The CI pipeline runs `npm test` which validates this via `REQUIRED_SECTIONS`. Skills that fail validation cannot be merged. 资料来源：[mcp-server/src/index.test.ts:1-45]()\n\nAdditionally, every skill must be **at least 5 KB** to discourage placeholder content, and must contain a **non-empty summary line** (the first line after the YAML frontmatter). 资料来源：[mcp-server/src/index.test.ts:30-38]()\n\n### Section Reference\n\n| # | Section Name | Purpose | Key Content |\n|---|-------------|---------|-------------|\n| 1 | **Overview** | What the tool does and why it matters | High-level description, key capabilities |\n| 2 | **Authentication & Permissions** | How to authenticate and which scopes are needed | PAT setup, OAuth flows, scope tables |\n| 3 | **Base URLs & API Versions** | Endpoint root and versioning strategy | `https://api.example.com/v1`, header pinning |\n| 4 | **Rate Limits** | Request quotas, complexity caps, headers | Tables with limits per auth type, response headers |\n| 5 | **Retry & Idempotency** | How to handle transient failures safely | Exponential backoff, idempotency key usage |\n| 6 | **Common Workflows (Recipes)** | Step-by-step patterns for high-frequency tasks | 6–12 recipes per tool with code examples |\n| 7 | **Error Codes** | What errors mean and how to handle them | Status codes, error response shapes, gotchas |\n| 8 | **Webhook Setup** | How to register, verify, and handle webhooks | Registration endpoint, signature verification, event types |\n| 9 | **Data Models / Fields** | Table reference and record structure | Table names, field names, sys_id patterns |\n| 10 | **Pagination** | How to traverse large result sets | Cursor-based, offset-based, complexity-based |\n| 11 | **Sources** | Links to official vendor documentation | Verified links only; no unverified claims |\n\n### Section Naming Convention\n\nThe MCP server resolves sections by name prefix, so `auth`, `rate-limits`, `recipes`, `gotchas`, `webhooks`, `overview`, and `fields` can be requested independently of the full document. 资料来源：[mcp-server/README.md:1-20]()\n\n```mermaid\ngraph LR\n A[get_skill tool] --> B[\"section: 'auth'\"]\n B --> C[Extract markdown between
'## Authentication' and next '##']\n A --> D[\"section: 'rate-limits'\"]\n D --> E[Extract markdown between
'## Rate Limits' and next '##']\n A --> F[\"section: 'recipes'\"]\n F --> G[Extract all ### Recipe headings]\n C --> H[Return as JSON string]\n E --> H\n G --> H\n```\n\n---\n\n## Authentication Patterns\n\nEach skill documents the full authentication surface. The two dominant patterns are:\n\n### Pattern 1 — Personal Access Token (PAT)\n\nUsed for server-to-server integrations. The token is passed via a vendor-specific header.\n\n```bash\n# Figma\ncurl https://api.figma.com/v1/me \\\n -H \"X-Figma-Token: YOUR_PAT\"\n\n# Jira (Basic Auth with API token)\ncurl \"$BASE/rest/api/3/myself\" \\\n -H \"Authorization: Basic $(echo -n 'user@example.com:API_TOKEN' | base64)\"\n```\n\nPATs are recommended for server-side use because they avoid the OAuth redirect flow complexity. 资料来源：[skills/figma/skill.md:1-20]()\n\n### Pattern 2 — OAuth 2.0\n\nUsed for user-facing applications where the app acts on behalf of a user.\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant A as Your App\n participant V as Vendor API\n U->>A: Initiate login\n A->>V: Redirect to /oauth?client_id=...&scope=...&state=...\n V->>U: Auth prompt\n U->>V: Grant access\n V->>A: Redirect with ?code=AUTH_CODE\n A->>V: POST /oauth/token, code + client_secret\n V->>A: {access_token, refresh_token, expires_in}\n A->>V: Authorization: Bearer \n V->>A: API response\n```\n\nFor Linear specifically, access tokens expire in 24 hours (post-October 2025 apps), and refresh token rotation is required by April 1, 2026. 资料来源：[skills/linear/skill.md:1-30]()\n\n---\n\n## Rate Limit Documentation\n\nRate limits are documented per skill as tables showing the limit by auth type. Each skill also specifies which response headers to inspect.\n\n### Rate Limit Table Template\n\n| Auth type | Requests / hr | Additional constraints |\n|-----------|-------------|----------------------|\n| API key | X | — |\n| OAuth app | Y | — |\n| Unauthenticated | Z | — |\n\n### Linear-Specific Complexity Model\n\nLinear uses a **complexity-based** rate limiting system rather than simple request counts. The system assigns complexity points to queries based on field depth and nesting. 资料来源：[skills/linear/skill.md:1-20]()\n\n| Header | Description |\n|--------|-------------|\n| `X-RateLimit-Requests-Limit` | Total allowed requests in window |\n| `X-RateLimit-Requests-Remaining` | Requests left in current window |\n| `X-RateLimit-Requests-Reset` | Unix timestamp when window resets |\n| `X-Complexity` | Complexity cost of the last query (Linear) |\n\n---\n\n## Recipe Structure\n\nEach skill contains **6–12 recipes** — complete, runnable code patterns for the most common API operations. Recipes follow a consistent structure:\n\n### Recipe Anatomy\n\n```\n### Recipe N — [Short Action Description]\n\n[Brief problem statement]\n\n// Optional: prerequisites or context\n\n\n\n// Optional: result interpretation\n```\n\n### Recipe Categories by Skill\n\n| Skill | Recipe Highlights |\n|-------|-------------------|\n| **Jira** | Create issue, search with JQL, update issue, add comment, register webhook, manage labels |\n| **Figma** | Read file node tree, export assets, list team projects, manage variables, create dev resources, webhook pipeline |\n| **Linear** | Create issue, search issues, update state, post comment, create attachment, incremental sync |\n| **Notion** | Create page, query database, update properties, list users, retrieve page, filter/query patterns |\n| **HubSpot** | CRUD contacts, CRUD deals, search with filters, register webhook, import CSV bulk |\n| **ServiceNow** | Create incident, read/write records, update state, query CMDB |\n\n```mermaid\ngraph TD\n A[Write Integration Code] --> B{Do I have a relevant skill doc?}\n B -->|No| C[Research vendor docs manually]\n B -->|Yes| D[Load skill doc]\n D --> E[Check auth section for token type]\n E --> F[Pick matching recipe]\n F --> G{Rate limit exceeded?}\n G -->|Yes| H[Wait for Retry-After, then retry]\n G -->|No| I[Execute API call]\n I --> J{Webhook needed?}\n J -->|Yes| K[Register webhook + verify signature]\n J -->|No| L[Done]\n C --> L\n K --> L\n```\n\n---\n\n## Error Code Documentation\n\nEach skill documents the vendor's error response shapes and maps HTTP status codes to action.\n\n### Common Error Patterns\n\n| Error | Likely Cause | Resolution |\n|-------|-------------|-----------|\n| `401 Unauthorized` | Token expired or missing | Refresh token or re-authenticate |\n| `403 Forbidden` | Missing scope | Re-authorize with additional scopes |\n| `429 Too Many Requests` | Rate limit hit | Respect `Retry-After` header |\n| `500 Internal Server Error` | Vendor-side issue | Retry with exponential backoff |\n| `400 Bad Request` | Malformed request body | Validate schema against recipe |\n\n### Skill-Specific Gotchas\n\n**Figma gotchas** include: `files:read` is deprecated and replaced with granular scopes; rate limits now vary by plan and seat type as of November 2025. 资料来源：[skills/figma/skill.md:1-10]()\n\n**Slack gotchas** include: `mrkdwn` format required (not standard Markdown), Events API URL verification must return JSON within 3 seconds, and `files.upload` is deprecated in favor of `files.getUploadURLExternal`. 资料来源：[skills/slack/skill.md:1-20]()\n\n**ServiceNow gotchas** include: the 32-character `sys_id` is the true primary key (not the human-readable `number` field), and work notes vs. comments have distinct access controls. 资料来源：[skills/servicenow/skill.md:1-20]()\n\n---\n\n## Webhook Documentation\n\nSkills that support event-driven patterns include webhook setup sections covering registration, payload shapes, and signature verification.\n\n### Webhook Registration Pattern\n\n```bash\ncurl -s -X POST \"$BASE/rest/api/3/webhook\" \\\n -H \"Authorization: $AUTH\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"My Webhook\",\n \"url\": \"https://myapp.com/webhook\",\n \"events\": [\"jira:issue_created\", \"jira:issue_updated\"],\n \"filters\": { \"issue-related-events-section\": \"project = PROJ\" }\n }'\n```\n\n### Signature Verification Pattern\n\nHubSpot uses HMAC-SHA256 verification:\n\n```python\nimport hmac, hashlib\n\ndef verify_hubspot_signature(\n client_secret: str,\n method: str,\n url: str,\n body: str,\n timestamp: str,\n signature: str,\n) -> bool:\n signed_payload = f\"{client_secret}{method}{url}{body}{timestamp}\"\n expected = hmac.new(\n client_secret.encode(),\n signed_payload.encode(),\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(expected, signature)\n```\n\nHubSpot validates webhook signatures using `X-HubSpot-Signature-v3`. Jira webhooks do not send signatures by default and require a secret token in the URL path. 资料来源：[skills/hubspot/skill.md:1-20]()\n\n---\n\n## Pagination Patterns\n\nThree pagination models appear across the skill library:\n\n| Model | Tool | Mechanism |\n|-------|------|-----------|\n| **Offset-based** | ServiceNow, Notion | `sysparm_offset`, `start_cursor` |\n| **Cursor-based** | Jira, HubSpot, GitHub | `pageToken`, `nextCursor`, `pageInfo` |\n| **Complexity-based** | Linear | `after`, `first`, monitors `X-Complexity` header |\n\n```mermaid\ngraph LR\n A[Query with first=N] --> B{More pages?}\n B -->|Yes| C[Read endCursor / pageInfo]\n C --> D[Query with after=]\n D --> B\n B -->|No| E[Process all results]\n```\n\nFor Linear, requesting fewer fields reduces complexity cost — deeply nested queries (e.g., `issue.project.lead.assignedIssues`) should be avoided unless necessary. 资料来源：[skills/linear/skill.md:1-20]()\n\n---\n\n## Validation and Governance\n\n### CI Pipeline\n\nEvery pull request triggers `npm test` which runs three validation checks on all skill files: 资料来源：[README.md:1-20]()\n\n| Check | Rule | Enforced |\n|-------|------|---------|\n| **All 11 sections present** | Every skill has each required section | ✅ |\n| **Non-empty summary** | First line after frontmatter is not blank | ✅ |\n| **Minimum size** | File length ≥ 5,000 bytes | ✅ |\n\n### Contribution Process\n\nTo add or update a skill: 资料来源：[README.md:1-20]()\n\n1. Create a branch: `git checkout -b skill/`\n2. Follow the template structure in any existing skill.md — all 11 sections required\n3. Verify all endpoints, rate limits, and auth flows against official vendor docs before committing\n4. Add a `Last validated:` date to the doc header\n5. Update `skills/INDEX.md` and `README.md` when adding a new tool\n6. Link to official sources in the `## Sources` section — no unverified claims\n7. Open a PR — CI validates the skill\n\n### Release Automation\n\nReleases are automated via GitHub Actions. Merge to `main`, then go to **Actions → Release → Run workflow** and select `patch / minor / major`. 资料来源：[README.md:1-20]()\n\n---\n\n## Development Roadmap\n\nThe skill library was built in five phases: 资料来源：[skills/ROADMAP.md:1-20]()\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 | Foundation (Auth + Core CRUD) | ✅ Complete — all 14 tools |\n| Phase 2 | High-Frequency Workflows (6–12 recipes per tool) | ✅ Complete — all 14 tools |\n| Phase 3 | Event-Driven & Real-Time (webhooks, signature verification) | ✅ Complete — all 14 tools |\n| Phase 4 | Bulk & Advanced Operations | ⚠️ Partial — documented for most tools |\n| Phase 5 | Cross-Tool Orchestration | ❌ Not started |\n\nThe next priority is a **freshness and accuracy pipeline** to keep skill docs in sync as vendor APIs evolve. 资料来源：[skills/ROADMAP.md:1-20]()\n\n---\n\n## Using Skills with AI Agents\n\n### Claude Code Project Instruction\n\nAdd skill references to `.claude/CLAUDE.md` so the agent always has context:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the\ncorresponding skill doc before writing code:\n\n- Jira → @skills/jira/skill.md\n- HubSpot → @skills/hubspot/skill.md\n- Linear → @skills/linear/skill.md\n- Notion → @skills/notion/skill.md\n- Slack → @skills/slack/skill.md\n\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\nAlways pin API version headers where specified.\n```\n\n### LangChain RAG Pipeline\n\n```python\nfrom langchain_community.document_loaders import DirectoryLoader\nfrom langchain.text_splitter import MarkdownHeaderTextSplitter\nfrom langchain_openai import OpenAIEmbeddings\nfrom langchain_community.vectorstores import Chroma\n\nloader = DirectoryLoader(\"skills/\", glob=\"**/*.md\")\ndocs = loader.load()\n\nsplitter = MarkdownHeaderTextSplitter(\n headers_to_split_on=[(\"##\", \"section\"), (\"###\", \"subsection\")]\n)\nchunks = []\nfor doc in docs:\n chunks.extend(splitter.split_text(doc.page_content))\n\nvectorstore = Chroma.from_documents(\n chunks,\n embedding=OpenAIEmbeddings(),\n persist_directory=\"./chroma_db\"\n)\n```\n\nSkill docs split cleanly at `##` and `###` boundaries because the document structure is intentionally designed for RAG chunking — each section is self-contained and meaningful in isolation. 资料来源：[README.md:1-20]()\n\n---\n\n## Quick Reference\n\n- **Repository**: https://github.com/Shanksg/clawskills\n- **MCP Server**: `npx -y clawskills-mcp`\n- **Skills directory**: `skills/` (14 tool-specific `.md` files)\n- **Required sections**: 11 per skill\n- **Minimum size**: 5 KB per skill\n- **CI command**: `npm test`\n\n---\n\n\n\n## Playbooks Index\n\n### 相关页面\n\n相关主题：[Skills Library Overview](#skills-overview), [Skill Document Structure](#skill-structure), [AI Tool Integration Guide](#ai-integration)\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- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n \n\n# Playbooks Index\n\n## Overview\n\nPlaybooks in ClawSkills are comprehensive, multi-step workflow guides that orchestrate integrations across two or more tools. Unlike individual skill documents that focus on single-tool API capabilities, playbooks provide end-to-end automation patterns for common cross-system business scenarios.\n\nThe Playbooks Index serves as the central directory and documentation hub for all available cross-tool workflows, enabling AI assistants and developers to implement sophisticated integrations without requiring deep expertise in each underlying API.\n\n## Architecture\n\n### Relationship Between Components\n\n```mermaid\ngraph TD\n subgraph \"ClawSkills Core\"\n A[Skills Index] --> B[Individual Skill Docs]\n C[Playbooks Index] --> D[Cross-Tool Playbooks]\n end\n \n subgraph \"MCP Server\"\n E[get_skill] --> B\n F[get_playbook] --> D\n G[list_playbooks] --> C\n end\n \n H[AI Assistant] --> E\n H --> F\n H --> G\n```\n\n### Playbook Structure Pattern\n\nEach playbook follows a standardized template containing:\n\n| Section | Purpose |\n|---------|---------|\n| **Trigger** | Event or condition that initiates the workflow |\n| **Prerequisites** | Required configurations, tokens, and permissions |\n| **Step-by-Step Flow** | Sequential actions with exact API calls |\n| **Field Mapping** | Data transformations between systems |\n| **Error Handling** | Retry logic and failure recovery |\n| **Testing Verification** | Validation checklist items |\n\n## Available Playbooks\n\n### 1. Zendesk → Jira Bug Escalation\n\n**Slug:** `zendesk-jira-bug-escalation`\n\n**Purpose:** Automatically creates a Jira bug issue when a Zendesk ticket meets escalation criteria.\n\n**Trigger Conditions:**\n- Ticket status changes to `solved` with low satisfaction score\n- Specific tag patterns (e.g., `bug`, `escalate`)\n- Agent-assigned priority flag\n\n**Key Features:**\n- Bidirectional comment mirroring\n- Attachment transfer from Zendesk to Jira\n- Correlation key generation for idempotent handling\n- Custom field mapping for project/issuetype selection\n\n资料来源：[playbooks/zendesk-jira-bug-escalation.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/zendesk-jira-bug-escalation.md)\n\n### 2. HubSpot → Asana Onboarding\n\n**Slug:** `hubspot-asana-onboarding`\n\n**Purpose:** Creates a structured onboarding task hierarchy in Asana when a new contact is added to a HubSpot list.\n\n**Workflow:**\n1. Detect new contact in target HubSpot list\n2. Create parent Onboarding Project in Asana\n3. Generate task checklist based on onboarding template\n4. Assign tasks to team members via Asana sections\n5. Post initial status update to Slack (if configured)\n\n**Task Template Structure:**\n```mermaid\ngraph LR\n A[New Contact] --> B[Create Project]\n B --> C[Kickoff Meeting]\n B --> D[Setup Tasks]\n B --> E[Training Tasks]\n C --> F[Send Welcome Email]\n D --> G[Create Accounts]\n D --> H[Configure Access]\n E --> I[Training Scheduled]\n E --> J[Materials Sent]\n```\n\n资料来源：[playbooks/hubspot-asana-onboarding.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/hubspot-asana-onboarding.md)\n\n### 3. Salesforce → HubSpot Lead Sync\n\n**Slug:** `salesforce-hubspot-lead-sync`\n\n**Purpose:** Bidirectional synchronization of lead data between Salesforce CRM and HubSpot Marketing Platform.\n\n**Sync Directions:**\n- **Lead Creation:** Salesforce → HubSpot (when Lead status = \"Open\")\n- **Status Updates:** HubSpot → Salesforce (when Contact lifecycle stage changes)\n- **Deal Association:** Bidirectional (deal closed in either system updates the other)\n\n**Field Mapping:**\n\n| Salesforce Field | HubSpot Property | Transform Logic |\n|------------------|------------------|-----------------|\n| `Email` | `email` | Direct copy |\n| `LeadSource` | `hs_lead_source` | Direct copy |\n| `AnnualRevenue` | `annualrevenue` | Numeric normalization |\n| `Industry` | `industry` | Picklist value mapping |\n| `CreatedDate` | `createdate` | ISO 8601 timestamp conversion |\n\n资料来源：[playbooks/salesforce-hubspot-lead-sync.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/salesforce-hubspot-lead-sync.md)\n\n### 4. Slack → Jira Incident Management\n\n**Slug:** `slack-jira-incident`\n\n**Purpose:** Streamlined incident creation and tracking using Slack as the front-end interface and Jira as the backend issue tracker.\n\n**Trigger Events:**\n- `reaction_added` emoji on flagged messages\n- `/incident` slash command invocation\n- Specific channel message patterns (configurable)\n\n**Workflow Sequence:**\n\n```mermaid\nsequenceDiagram\n participant S as Slack User\n participant SL as Slack API\n participant BM as Bot/Server\n participant J as Jira Cloud\n \n S->>SL: Adds 🚨 reaction\n SL->>BM: reaction_added event\n BM->>SL: getPermalink()\n BM->>J: Search existing issue\n alt No existing issue\n BM->>J: Create incident issue\n BM->>SL: Post issue link to thread\n else Existing issue found\n BM->>SL: Post existing link\n end\n```\n\n**Correlation Key Format:** `slack:{team_id}:{channel_id}:{ts}`\n\n资料来源：[playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n\n## MCP Server Integration\n\nThe ClawSkills MCP server exposes playbook operations through three primary tools:\n\n### Tool Definitions\n\n| Tool | Arguments | Returns |\n|------|-----------|---------|\n| `list_playbooks` | None | Array of all playbook names and slugs |\n| `get_playbook` | `name` (string) | Full playbook content by slug |\n| `search_playbooks` | `query` (string) | Matching excerpts with context (±3 lines) |\n\n### Usage Example\n\n```typescript\n// List all available playbooks\nconst playbooks = await client.list_playbooks({});\n// Returns: [\"hubspot-asana-onboarding\", \"salesforce-hubspot-lead-sync\", \"zendesk-jira-bug-escalation\", \"slack-jira-incident\"]\n\n// Fetch specific playbook\nconst playbook = await client.get_playbook({\n name: \"slack-jira-incident\"\n});\n\n// Search for specific patterns\nconst results = await client.search_playbooks({\n query: \"idempotency\"\n});\n```\n\n### Search Behavior\n\n- Full-text search across all playbook content\n- Returns up to 5 matches per playbook\n- Includes ±3 lines of context around each match\n- Supports queries like `\"idempotency\"`, `\"rollback\"`, `\"closed won\"`\n\n资料来源：[mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n\n## Test Coverage\n\nThe Playbooks system is validated through automated tests:\n\n```typescript\ndescribe(\"real playbooks\", () => {\n let playbooks: Map;\n\n beforeAll(() => {\n playbooks = loadPlaybooks(REAL_PLAYBOOKS_DIR);\n });\n\n it(\"loads all expected playbooks\", () => {\n const knownPlaybooks = [\n \"hubspot-asana-onboarding\",\n \"salesforce-hubspot-lead-sync\",\n \"zendesk-jira-bug-escalation\",\n ];\n // Verification logic\n });\n\n it(\"every playbook has a non-empty summary line\", () => {\n for (const [slug, content] of playbooks.entries()) {\n const summary = skillSummary(content);\n expect(summary, `${slug}: empty summary`).not.toBe(\"\");\n }\n });\n});\n```\n\n**Validation Requirements:**\n- All expected playbooks must load successfully\n- Each playbook must contain a non-empty summary line\n- Minimum file size threshold (5000 bytes) prevents truncated documentation\n\n资料来源：[mcp-server/src/index.test.ts:1-50](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n\n## Roadmap and Future Development\n\n### Phase 5 — Cross-Tool Orchestration (In Progress)\n\nThe Playbooks system represents the culmination of the ClawSkills documentation strategy:\n\n| Phase | Status | Coverage |\n|-------|--------|----------|\n| Phase 1 — Foundation | ✅ Complete | Auth flows, basic CRUD |\n| Phase 2 — High-Frequency Workflows | ✅ Complete | 6–12 recipes per tool |\n| Phase 3 — Event-Driven & Real-Time | ✅ Complete | Webhook setup, signatures |\n| Phase 4 — Bulk & Advanced Operations | ⚠️ Partial | Most tools documented |\n| Phase 5 — Cross-Tool Orchestration | ❌ Not Started | Patterns in INDEX, no recipes |\n\n资料来源：[skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n## Adding New Playbooks\n\nTo contribute a new playbook:\n\n1. Create a branch: `git checkout -b playbook/`\n2. Follow the playbook template structure\n3. Include all required sections (trigger, flow, mapping, error handling)\n4. Update `playbooks/INDEX.md` with the new entry\n5. Open a PR — CI validates playbook loads and has required sections\n\n**Playbook Naming Convention:**\n- Filename: `--.md`\n- Slug: Same as filename without extension\n- Frontmatter: Include `title`, `description`, and `tools` array\n\n---\n\n\n\n## MCP Server Architecture\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools), [Installation Guide](#installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n- [mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)\n- [mcp-server/tsconfig.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/tsconfig.json)\n- [mcp-server/vitest.config.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/vitest.config.ts)\n- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n \n\n# MCP Server Architecture\n\n## Overview\n\nThe **clawskills-mcp** is a Model Context Protocol (MCP) server that exposes the ClawSkills API integration documentation to AI agents. It provides a bridge between AI assistants (such as Claude) and the structured skill documentation for 14 different API integrations.\n\n资料来源：[mcp-server/README.md]()\n\n### Core Purpose\n\nThe server serves as an interface layer that allows AI agents to query, search, and retrieve API integration knowledge without requiring manual documentation lookup. This enables AI-assisted coding tasks to incorporate accurate API specifications, authentication patterns, and workflow recipes on demand.\n\n```mermaid\ngraph TD\n A[AI Agent] -->|MCP Protocol| B[clawskills-mcp Server]\n B -->|list_skills| C[Skill Index]\n B -->|get_skill| C\n B -->|search_skills| D[Full-text Search]\n B -->|list_playbooks| E[Cross-Tool Playbooks]\n C -->|Returns| A\n D -->|Returns| A\n E -->|Returns| A\n \n F[skills/\\*.md] --> C\n G[playbooks/\\*.md] --> E\n```\n\n资料来源：[README.md:50-80]()\n\n## Architecture Components\n\n### Component Overview\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| MCP Server | Protocol bridge for AI agent communication | `mcp-server/src/index.ts` |\n| Skill Docs | 14 structured Markdown integration guides | `skills/*/skill.md` |\n| Playbooks | Cross-tool workflow documentation | `playbooks/*.md` |\n| Index | Master listing of all available skills | `skills/INDEX.md` |\n| CLI Tools | Build, test, and release automation | `mcp-server/package.json` |\n\n### Directory Structure\n\n```\nclawskills/\n├── mcp-server/\n│ ├── src/\n│ │ └── index.ts # Main MCP server implementation\n│ ├── package.json # Dependencies and scripts\n│ ├── tsconfig.json # TypeScript configuration\n│ ├── vitest.config.ts # Test configuration\n│ ├── Dockerfile # Container deployment\n│ └── README.md # Server-specific documentation\n├── skills/\n│ ├── INDEX.md # Master skill index\n│ ├── jira/skill.md\n│ ├── slack/skill.md\n│ ├── figma/skill.md\n│ ├── notion/skill.md\n│ ├── linear/skill.md\n│ └── ... (9 more skills)\n├── playbooks/\n│ ├── slack-jira-incident.md\n│ └── ... (additional workflows)\n└── README.md # Main project documentation\n```\n\n资料来源：[mcp-server/README.md:1-10]()\n\n## MCP Tools Interface\n\nThe server exposes four primary tools that AI agents can invoke:\n\n### Tool Specifications\n\n| Tool | Description | Parameters | Return Type |\n|------|-------------|------------|-------------|\n| `list_skills` | List all available skill documentation | None | Array of skill slugs with descriptions |\n| `get_skill` | Fetch full skill doc or specific section | `slug`, `section?` | Markdown content |\n| `search_skills` | Full-text search across all skills | `query` | Matching results with context |\n| `list_playbooks` | List available cross-tool workflows | None | Array of playbook names |\n\n### Parameter Details\n\n#### `get_skill` Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `slug` | string | Yes | Skill identifier (e.g., `jira`, `slack`, `figma`) |\n| `section` | string | No | Specific section name (`auth`, `rate-limits`, `recipes`, `errors`, etc.) |\n\n#### `search_skills` Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `query` | string | Yes | Search term to match across all skill documentation |\n\n资料来源：[README.md:60-75]()\n\n## Deployment Models\n\n### npx (Recommended for Claude Desktop/Code)\n\nNo installation required. The server is fetched and executed on demand.\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n**Configuration File Locations:**\n\n| Platform | Path |\n|----------|------|\n| macOS (Claude Desktop) | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows (Claude Desktop) | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Claude Code (Project) | `.claude/settings.json` |\n| Claude Code (Global) | `~/.claude/settings.json` |\n\n资料来源：[mcp-server/README.md:20-40]()\n\n### Docker Deployment\n\nFor server-side or containerized environments:\n\n```bash\n# Build the image\ndocker build -t clawskills-mcp -f mcp-server/Dockerfile .\n\n# Run the container\ndocker run --rm -i clawskills-mcp\n```\n\n资料来源：[mcp-server/README.md:50-55]()\n\n## Content Repository\n\n### Skill Documentation Structure\n\nEach skill follows a standardized 11-section template:\n\n1. **Overview** — Tool description and key capabilities\n2. **Authentication & permissions** — Auth flows, token management, scopes\n3. **Base URL & versioning** — API endpoint structure\n4. **Rate limits** — Request quotas and throttling patterns\n5. **Common workflows (recipes)** — Code examples for typical operations\n6. **Error codes** — Error handling patterns\n7. **Webhooks** — Event-driven integration patterns\n8. **Pagination** — Large dataset retrieval\n9. **Filtering & sorting** — Query parameter conventions\n10. **Sources** — Official documentation links\n11. **Testing checklist** — Verification procedures\n\n### Supported Integrations\n\n| Skill | Category | Key Capabilities |\n|-------|----------|------------------|\n| Jira | Project Management | Issue CRUD, comments, attachments, webhooks |\n| Slack | Communication | Messaging, threads, files, reactions |\n| Figma | Design | File access, comments, variables, exports |\n| Notion | Documentation | Pages, databases, blocks, search |\n| Linear | Issue Tracking | GraphQL API, issues, projects, labels |\n| Monday.com | Project Management | Boards, items, updates, workdocs |\n| Salesforce | CRM | Objects, queries, records |\n| HubSpot | Marketing | Contacts, deals, pipelines |\n| ServiceNow | ITSM | Incident, change, problem management |\n| Dynamics 365 | Enterprise | Business central, customer engagement |\n| GitHub | Development | Repos, issues, PRs, actions |\n| Stripe | Payments | Charges, subscriptions, webhooks |\n| Asana | Task Management | Projects, tasks, subtasks, teams |\n| Zendesk | Support | Tickets, users, satisfaction |\n\n资料来源：[README.md:30-45]()\n\n## Build and Development\n\n### TypeScript Configuration\n\nThe server is implemented in TypeScript for type safety:\n\n```json\n{\n \"compilerOptions\": {\n \"target\": \"ES2020\",\n \"module\": \"commonjs\",\n \"lib\": [\"ES2020\"],\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"outDir\": \"./dist\",\n \"rootDir\": \"./src\"\n },\n \"include\": [\"src/**/*\"],\n \"exclude\": [\"node_modules\", \"dist\"]\n}\n```\n\n资料来源：[mcp-server/tsconfig.json]()\n\n### Testing Infrastructure\n\nThe project uses Vitest for unit testing and validation:\n\n```typescript\n// vitest.config.ts structure\n{\n test: {\n environment: \"node\",\n include: [\"**/*.test.ts\"],\n coverage: {\n provider: \"v8\",\n reporter: [\"text\", \"json\", \"html\"]\n }\n }\n}\n```\n\n资料来源：[mcp-server/vitest.config.ts]()\n\n### CI/CD Pipeline\n\nThe project includes automated workflows:\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| `ci.yml` | Every push/PR | Build + test on every change |\n| `release.yml` | Manual dispatch | Version bump, git tag, npm publish |\n\n**Release Process:**\n\n1. Merge changes to `main` branch\n2. Navigate to GitHub Actions → **Release**\n3. Run workflow with desired version bump (`patch`, `minor`, `major`)\n4. Server automatically publishes via OIDC authentication\n\n资料来源：[skills/ROADMAP.md:60-70]()\n\n## Data Flow\n\n### Query Execution Flow\n\n```mermaid\nsequenceDiagram\n participant AI as AI Agent\n participant MCP as MCP Server\n participant FS as File System\n participant MD as Markdown Files\n \n AI->>MCP: list_skills()\n MCP->>FS: Read INDEX.md\n FS-->>MCP: Return skill list\n MCP-->>AI: Skill slugs with descriptions\n \n AI->>MCP: get_skill(\"jira\", \"auth\")\n MCP->>FS: Read skills/jira/skill.md\n FS-->>MCP: Return markdown content\n MCP-->>AI: Authentication section content\n \n AI->>MCP: search_skills(\"webhook\")\n MCP->>FS: Search all *.md files\n FS-->>MCP: Matching results\n MCP-->>AI: Search results with context\n```\n\n### Content Resolution\n\n| Tool | Content Source | Processing |\n|------|----------------|------------|\n| `list_skills` | `skills/INDEX.md` | Parse YAML/JSON index |\n| `get_skill` | `skills/{slug}/skill.md` | Extract full doc or section |\n| `search_skills` | All `skills/` and `playbooks/` | Full-text pattern match |\n| `list_playbooks` | `playbooks/` directory | Enumerate workflow files |\n\n## Version Management\n\n### Semantic Versioning\n\nThe MCP server maintains its own npm version separate from the skill documentation:\n\n| Version Type | Increment | Example |\n|--------------|-----------|---------|\n| Major | Breaking changes | 1.0.0 → 2.0.0 |\n| Minor | New features | 1.0.0 → 1.1.0 |\n| Patch | Bug fixes | 1.0.0 → 1.0.1 |\n\n### Documentation Versioning\n\nIndividual skill docs track their own API version and `Last validated` date:\n\n```yaml\n---\ntitle: Jira Integration\napi_version: \"3.0\"\nlast_validated: 2025-01-15\n---\n```\n\nThis ensures API changes are reflected at the skill level without requiring full server releases.\n\n资料来源：[skills/ROADMAP.md:50-65]()\n\n## Integration Patterns\n\n### With Claude (claude.ai or Claude Code)\n\n#### Option 1: Reference Specific Section\n\nPaste a skill section directly into conversation:\n\n```\n[paste the \"Authentication & permissions\" section from skills/salesforce/skill.md]\n\nUsing the above, write a Python function that exchanges a JWT for an access token\nand caches it until 5 minutes before expiry.\n```\n\n#### Option 2: Project Instruction File\n\nAdd to `.claude/CLAUDE.md` for persistent context:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the\ncorresponding skill doc before writing code:\n\n- Jira → @skills/jira/skill.md\n- Slack → @skills/slack/skill.md\n- Figma → @skills/figma/skill.md\n\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\n```\n\n资料来源：[README.md:90-120]()\n\n## Security Considerations\n\n### Token Handling\n\n| Context | Token Type | Recommendation |\n|---------|------------|----------------|\n| Development | Personal Access Token | Use environment variables, never commit |\n| Production | OAuth tokens | Implement secure storage with rotation |\n| Webhooks | Shared secrets | Verify signatures in all handlers |\n\n### Permission Model\n\n- **Least privilege**: Request only required scopes\n- **Token storage**: Never log token values\n- **Webhook verification**: Always validate signatures\n\n资料来源：[skills/slack/skill.md:80-95]()\n\n## Maintenance and Updates\n\n### Skill Documentation Updates\n\n1. Create feature branch: `git checkout -b skill/`\n2. Follow the 11-section template structure\n3. Verify all endpoints against official vendor docs\n4. Add `Last validated:` date to doc header\n5. Update `skills/INDEX.md` and `README.md`\n6. Open PR — CI validates skill loads and has all sections\n\n### Content Freshness Pipeline\n\n| Priority | Initiative | Status |\n|----------|------------|--------|\n| Phase A | Automated validation and alerting | Planned |\n| Phase B | Vendor API change monitoring | Planned |\n| Phase C | Community contribution workflow | Planned |\n\n资料来源：[skills/ROADMAP.md:75-90]()\n\n## Related Documentation\n\n- [ClawSkills Main README](../README.md) — Project overview and quick start\n- [Skills Index](../skills/INDEX.md) — Complete listing of all skill documentation\n- [Release Workflow](../.github/workflows/release.yml) — Automated release process\n- [CI Pipeline](../.github/workflows/ci.yml) — Continuous integration configuration\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[MCP Server Architecture](#mcp-server-architecture), [Quick Start Guide](#quick-start), [AI Tool Integration Guide](#ai-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n \n\n# MCP Tools Reference\n\n## Overview\n\nThe **clawskills-mcp** is a Model Context Protocol (MCP) server that provides AI assistants (specifically Claude) access to the ClawSkills library of integration skill documentation. This server acts as a bridge between AI coding assistants and the comprehensive API documentation for 14+ third-party tools including Jira, GitHub, Salesforce, Linear, and others.\n\nThe MCP server exposes three primary tools that enable AI assistants to query, retrieve, and search through skill documentation in real-time, allowing them to write accurate integration code without requiring manual lookup of API documentation.\n\n**资料来源：** [README.md:1]()\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[Claude AI Assistant] -->|MCP Protocol| B[clawskills-mcp Server]\n B --> C[Skill Documentation Files]\n B --> D[Index Registry]\n C --> E[skills/*.md]\n F[Claude Desktop/Claude Code] --> A\n G[Claude API App] --> A\n```\n\n### Tool Interaction Flow\n\n```mermaid\nsequenceDiagram\n participant C as Claude Assistant\n participant MCP as clawskills-mcp Server\n participant FS as File System\n \n C->>MCP: list_skills\n MCP->>FS: Read INDEX.md\n FS-->>MCP: Return skill list\n MCP-->>C: Skill names & descriptions\n \n C->>MCP: get_skill(skill_name, section?)\n MCP->>FS: Read skills/{skill}/skill.md\n FS-->>MCP: Return skill document\n MCP-->>C: Full skill or section content\n \n C->>MCP: search_skills(query)\n MCP->>FS: Read all skill files\n FS-->>MCP: Search results\n MCP-->>C: Matching skill sections\n```\n\n## Available MCP Tools\n\n### 1. list_skills\n\nReturns a list of all available skill documentation files in the ClawSkills library.\n\n**Parameters:** None required\n\n**Returns:** Array of skill names with brief descriptions\n\n**资料来源：** [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n### 2. get_skill\n\nRetrieves the complete content of a skill document or a specific section within it.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `skill` | string | Yes | Name of the skill (e.g., \"jira\", \"github\", \"figma\") |\n| `section` | string | No | Specific section to retrieve: `auth`, `rate-limits`, `recipes`, `errors` |\n\n**Returns:** Full skill documentation or specified section content\n\n**资料来源：** [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n### 3. search_skills\n\nPerforms full-text search across all skill documents.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `query` | string | Yes | Search terms to match against skill content |\n| `limit` | number | No | Maximum number of results (default varies) |\n\n**Returns:** Matching skill sections with context\n\n**资料来源：** [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n## Installation\n\n### Prerequisites\n\n- Node.js 18+ (for npx usage)\n- npm 8+ (for global installation)\n\n### Quick Start (Temporary)\n\n```bash\nnpx -y clawskills-mcp\n```\n\n### Permanent Installation\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n### Claude Desktop Configuration\n\nAdd the following to your Claude Desktop configuration file:\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### Claude Code Configuration\n\nFor Claude Code projects, add the MCP server to your project's MCP settings:\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n## Supported Skills\n\nThe MCP server provides access to documentation for the following integrations:\n\n| Skill Name | Description | Category |\n|------------|-------------|----------|\n| `github` | GitHub REST/GQL APIs | VCS |\n| `jira` | Jira Cloud REST API | Project Management |\n| `salesforce` | Salesforce REST API | CRM |\n| `monday` | Monday.com API | Project Management |\n| `hubspot` | HubSpot CRM API | CRM |\n| `dynamics365` | Microsoft Dynamics 365 | CRM/ERP |\n| `servicenow` | ServiceNow REST API | ITSM |\n| `zendesk` | Zendesk Support API | Support |\n| `asana` | Asana API | Project Management |\n| `linear` | Linear GraphQL API | Project Management |\n| `figma` | Figma REST API | Design |\n| `stripe` | Stripe API | Payments |\n| `notion` | Notion API | Productivity |\n| `slack` | Slack Web API | Communication |\n\n**资料来源：** [README.md:1](), [skills/ROADMAP.md:1]()\n\n## Usage Patterns\n\n### Pattern 1: Direct Reference in Prompts\n\nPaste skill documentation directly into your conversation:\n\n```\nUsing the above Figma authentication section, write a Python function \nthat exchanges a JWT for an access token and caches it until 5 minutes before expiry.\n```\n\n### Pattern 2: Integration Agent Workflow\n\n```python\ndef run_integration_agent(task: str, tools_needed: list[str]) -> str:\n \"\"\"\n Use MCP tools to fetch skill docs, then write integration code.\n \"\"\"\n # Fetch relevant skills via MCP\n skills = []\n for tool in tools_needed:\n skill_doc = get_skill(tool)\n skills.append(skill_doc)\n \n # Construct prompt with skill context\n prompt = f\"\"\"\n Task: {task}\n \n Integration documentation:\n {skills}\n \n Write the integration code following these patterns.\n \"\"\"\n \n # Send to Claude for code generation\n response = client.messages.create(\n model=\"claude-sonnet-4-20250514\",\n max_tokens=2048,\n messages=[{\"role\": \"user\", \"content\": prompt}]\n )\n return response.content[0].text\n```\n\n### Pattern 3: Project Instruction Integration\n\nAdd to your `.claude/CLAUDE.md` to configure Claude Code with skill awareness:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the \ncorresponding skill doc before writing code:\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\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\nAlways pin API version headers where specified.\n```\n\n**资料来源：** [README.md:1]()\n\n## Skill Document Structure\n\nEach skill document follows a standardized template with 11 required sections:\n\n| Section | Purpose |\n|---------|---------|\n| Overview | High-level description and key capabilities |\n| Authentication & permissions | Auth methods, scopes, token management |\n| Core entities | Data models, entity types, relationships |\n| Endpoints | API endpoints with parameters and responses |\n| Common workflows (recipes) | Step-by-step integration patterns |\n| Error handling | Error codes, retry strategies |\n| Rate limits | Rate limiting policies and headers |\n| Webhooks | Webhook setup, signature verification |\n| Best practices | Security, reliability, performance tips |\n| Testing checklist | Verified behaviors and test cases |\n| Sources | Links to official vendor documentation |\n\n**资料来源：** [README.md:1](), [skills/ROADMAP.md:1]()\n\n## Best Practices\n\n### When Using MCP Tools\n\n1. **Specify exact tools needed**: Rather than loading all skills, request only the tools relevant to your current task to minimize complexity\n2. **Use section filtering**: When you only need authentication info, specify `section: \"auth\"` to get targeted content\n3. **Combine search with targeted retrieval**: Use `search_skills` to find relevant content, then `get_skill` for complete context\n\n### When Writing Integration Code\n\n1. **Follow documented auth patterns**: Each skill specifies the recommended authentication method (PAT, OAuth, API Key)\n2. **Implement rate limit handling**: Respect the documented rate limits and use Retry-After headers\n3. **Pin API version headers**: Use the exact version headers specified (e.g., `Notion-Version: 2025-09-03`)\n4. **Handle errors consistently**: Use the documented error codes and retry strategies\n\n## Troubleshooting\n\n### Connection Issues\n\n| Symptom | Solution |\n|---------|----------|\n| MCP server not connecting | Verify Node.js version is 18+ |\n| Tools not appearing in Claude | Check Claude Desktop config JSON syntax |\n| Timeout on first request | Allow additional time for npx to download package |\n\n### Debug Logging\n\nLog the following for troubleshooting:\n- Tool name called\n- Parameters passed\n- Response status and timing\n\nDo NOT log:\n- Token values or credentials\n- Full request/response bodies (may contain PII)\n\n## Future Enhancements\n\nThe ClawSkills project roadmap includes improvements to the MCP server:\n\n| Enhancement | Status |\n|-------------|--------|\n| Freshness validation pipeline | Planned |\n| Cross-tool orchestration recipes | Not started |\n| Bulk operations documentation | Partial |\n| Real-time sync patterns | Complete |\n\n**资料来源：** [skills/ROADMAP.md:1]()\n\n## See Also\n\n- [CLAUDE.md Integration Guide](README.md) - Detailed integration patterns\n- [Skills Index](skills/INDEX.md) - Complete list of available skills\n- [Slack-Jira Incident Playbook](playbooks/slack-jira-incident.md) - Cross-tool workflow example\n- [ROADMAP.md](skills/ROADMAP.md) - Project roadmap and status\n\n---\n\n\n\n## AI Tool Integration Guide\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#quick-start), [MCP Tools Reference](#mcp-tools), [Playbooks Index](#playbooks-index)\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/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/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# AI Tool Integration Guide\n\n## Overview\n\nThe **clawskills** project is a comprehensive library of skill documentation designed to enable AI assistants (such as Claude) to integrate with third-party tools and services through a standardized, machine-readable format. Each skill document provides authentication patterns, API endpoints, rate limits, error handling, and reusable code recipes for a specific vendor API. 资料来源：[README.md]()\n\n### Purpose and Scope\n\nThe project serves two primary audiences:\n\n1. **AI Development Platforms** — Developers building AI agents can reference skill docs to understand how their AI assistant should interact with external services\n2. **Integration Developers** — Teams implementing integrations can use these docs as authoritative references for correct API usage, authentication flows, and error handling\n\nEach skill file follows a strict template with 11 required sections, ensuring consistency across all 14 currently supported tools. 资料来源：[skills/ROADMAP.md]()\n\n### Supported Tools\n\nThe library currently covers 14 primary tools with complete documentation:\n\n| Category | Tools |\n|----------|-------|\n| Project Management | Jira, Asana, Monday.com, Linear |\n| Development | GitHub, Figma |\n| CRM & Sales | Salesforce, HubSpot, Dynamics 365 |\n| Support & ITSM | Zendesk, ServiceNow |\n| Communication | Slack |\n| Other | Stripe, Notion |\n\n---\n\n## Architecture\n\n### MCP Server Architecture\n\nThe integration is powered by a Model Context Protocol (MCP) server that exposes three core tools enabling AI assistants to query the skill library dynamically:\n\n```mermaid\ngraph TD\n A[AI Assistant] -->|list_skills| B[clawskills-mcp Server]\n A -->|get_skill| B\n A -->|search_skills| B\n B --> C[Skill Documentation Files]\n B --> D[skills/INDEX.md]\n \n E[Claude Desktop Config] -->|npx -y clawskills-mcp| B\n F[Claude Code Config] -->|npx -y clawskills-mcp| B\n```\n\n**MCP Server Tools:**\n\n| Tool | Purpose |\n|------|---------|\n| `list_skills` | Retrieve a list of all available skill documents |\n| `get_skill` | Fetch a complete skill doc or a specific section (e.g., `auth`, `rate-limits`, `recipes`) |\n| `search_skills` | Full-text search across all skill documents |\n\n资料来源：[README.md]()\n\n### Skill Document Structure\n\nEach skill document is organized into 11 mandatory sections, ensuring comprehensive coverage:\n\n| Section | Content |\n|---------|---------|\n| Base URL & Versioning | API base URLs, version headers |\n| Authentication & Permissions | PAT, OAuth 2.0, API tokens, scopes |\n| Core entities | Data models, IDs, relationships |\n| Common workflows (recipes) | Step-by-step integration patterns |\n| Rate limits | Request quotas, complexity points |\n| Error handling | Error codes, retry patterns |\n| Webhooks | Event subscriptions, signature verification |\n| Testing & validation | Checklist of test scenarios |\n| Sources | Links to official vendor documentation |\n\n资料来源：[skills/ROADMAP.md]()\n\n---\n\n## Authentication Patterns\n\nThe skill library documents multiple authentication methods across different vendors, standardized into common patterns.\n\n### Personal Access Token (PAT)\n\nRecommended for server-to-server integrations:\n\n```bash\ncurl https://api.figma.com/v1/me \\\n -H \"X-Figma-Token: YOUR_PAT\"\n```\n\n### OAuth 2.0\n\nRecommended for user-facing applications requiring user context:\n\n```bash\n# Authorization URL\nGET https://www.figma.com/oauth\n ?client_id=CLIENT_ID\n &redirect_uri=REDIRECT_URI\n &scope=file_content:read,file_comments:write\n &state=RANDOM_STATE\n &response_type=code\n\n# Token exchange\ncurl -X POST https://api.figma.com/v1/oauth/token \\\n -d \"client_id=CLIENT_ID\" \\\n -d \"client_secret=CLIENT_SECRET\" \\\n -d \"redirect_uri=REDIRECT_URI\" \\\n -d \"code=AUTH_CODE\" \\\n -d \"grant_type=authorization_code\"\n```\n\n### API Token + Basic Auth\n\nCommon pattern for Jira and similar Atlassian products:\n\n```bash\ncurl -s -X PUT \"$BASE/rest/api/3/issue/PROJ-42\" \\\n -H \"Authorization: $AUTH\" \\\n -H \"Content-Type: application/json\"\n```\n\n资料来源：[skills/figma/skill.md](), [skills/jira/skill.md]()\n\n---\n\n## Rate Limiting Strategies\n\nEach skill document specifies rate limits and recommended retry strategies.\n\n### Rate Limit Response Patterns\n\n| Header | Description |\n|--------|-------------|\n| `X-RateLimit-Requests-Limit` | Total allowed requests in window |\n| `Retry-After` | Seconds to wait before retry (on 429) |\n| `X-Complexity` | Complexity points cost for Linear API |\n\n### Retry Pattern\n\n```python\nimport time\nimport requests\n\ndef call_with_retry(url, headers, max_retries=3):\n for attempt in range(max_retries):\n response = requests.get(url, headers=headers)\n if response.status_code == 429:\n retry_after = int(response.headers.get(\"Retry-After\", 60))\n time.sleep(retry_after)\n continue\n return response\n raise Exception(\"Max retries exceeded\")\n```\n\n资料来源：[skills/linear/skill.md](), [skills/notion/skill.md]()\n\n### Rate Limits by Tool\n\n| Tool | Requests/hr | Notes |\n|------|-------------|-------|\n| Linear (API key) | 5,000 | 250,000 complexity points/hr |\n| Linear (OAuth) | 5,000 | 2,000,000 complexity points/hr |\n| Notion | 3/sec | Exceeding triggers `429` with `Retry-After` |\n| Jira | Varies by plan | Includes attachment size limits (10 MB default) |\n\n---\n\n## Cross-Tool Orchestration\n\nThe project includes playbooks demonstrating multi-system workflows. These are the most advanced integration patterns, combining multiple tool APIs in a single workflow.\n\n### Slack-Jira Incident Response Playbook\n\nThis playbook demonstrates automated incident management across Slack and Jira:\n\n```mermaid\ngraph LR\n A[Slack Alert] --> B{Trigger Type}\n B -->|reaction_added| C[Get Channel + TS]\n B -->|message| D[Get Thread Info]\n B -->|slash command| E[Get Command Payload]\n \n C --> F[Resolve Permalink]\n D --> F\n E --> F\n \n F --> G{Search Jira}\n G -->|Found| H[Reuse Existing Issue]\n G -->|Not Found| I[Create Jira Issue]\n \n H --> J[Post Reply in Slack Thread]\n I --> J\n J --> K[Pin Bot Reply]\n```\n\n**Field Mapping:**\n\n| Slack | Jira |\n|-------|------|\n| `correlation key` = `slack:{team_id}:{channel_id}:{ts}` | Stored as label |\n| message text | `summary` (first 120 chars) + `description` |\n| Slack permalink | Included in description |\n| `reaction_added` / `message` / slash command | Different correlation key formats |\n\n资料来源：[playbooks/slack-jira-incident.md]()\n\n### Phase 5 Status\n\nCross-tool orchestration is currently in **Phase 5 — Patterns listed but not fully implemented**:\n\n> Cross-Tool Orchestration | Multi-system recipes spanning 2+ tools | ❌ Not started — patterns listed in INDEX.md but no dedicated recipes\n\n资料来源：[skills/ROADMAP.md]()\n\n---\n\n## Error Handling\n\n### Common Error Codes\n\n| Code | Tool | Meaning |\n|------|------|---------|\n| `missing_version` | Notion | Request missing `Notion-Version` header |\n| `object_not_found` | Notion | Page/database not shared with integration |\n| `RATELIMITED` | Linear | Burst limit exceeded |\n| `ENTITY_NOT_FOUND` | Linear | Invalid UUID in mutation |\n| `INPUT_ERROR` | Linear | Malformed input data |\n| `cant_update_message` | Slack | Bot cannot update another user's message |\n| `validation_error` | Notion | Exceeded block limit (100 blocks) |\n\n### Error Debugging Patterns\n\nSlack-specific debugging guidance:\n\n> **Events arrive but signature verification fails:** Make sure you're reading the raw request body (not parsed JSON) for HMAC calculation. Some frameworks re-encode the body — use the raw bytes.\n\n资料来源：[skills/slack/skill.md]()\n\n---\n\n## Webhook Integration\n\n### Setting Up Webhooks\n\nJira webhook registration example:\n\n```bash\ncurl -s -X POST \"$BASE/rest/webhooks/1.0/webhook\" \\\n -H \"Authorization: $AUTH\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"My Integration Webhook\",\n \"url\": \"https://your-server.example.com/jira-webhook\",\n \"events\": [\"jira:issue_created\", \"jira:issue_updated\"],\n \"filters\": {\n \"issue-related-events-section\": \"project = PROJ AND issuetype in (Bug, Incident)\"\n }\n }'\n```\n\n**Available Jira Events:** `jira:issue_created`, `jira:issue_updated`, `jira:issue_deleted`, `comment_created`, `comment_updated`, `jira:worklog_updated`, `sprint_created`, `sprint_closed`\n\n### Webhook Security\n\n| Platform | Security Mechanism |\n|----------|-------------------|\n| HubSpot | HMAC-SHA256 signature in `X-HubSpot-Signature-v3` header |\n| Jira | Secret token in URL query string (e.g., `?secret=abc123`) |\n| Linear | `Linear-Signature` header verification |\n\n> **Note:** Jira Cloud webhooks do not send a signature by default. Use a secret token in the URL path or query string and verify it in your handler.\n\n资料来源：[skills/jira/skill.md](), [skills/hubspot/skill.md](), [skills/linear/skill.md]()\n\n---\n\n## Data Models\n\n### Node Types (Figma)\n\nUnderstanding Figma's node hierarchy is essential for file operations:\n\n| Type | Description |\n|------|-------------|\n| `DOCUMENT` | Root node of a file |\n| `CANVAS` | A page in the file |\n| `FRAME` | Artboard / container |\n| `COMPONENT` | Reusable component definition |\n| `INSTANCE` | Linked copy of a COMPONENT |\n| `COMPONENT_SET` | Container for component variants |\n| `TEXT` | Text layer |\n| `VECTOR` | Vector shape |\n\n### Custom Fields (Jira)\n\nJira custom fields use IDs like `customfield_10014`. The mapping varies per instance:\n\n| Field | Jira Cloud Default ID |\n|-------|----------------------|\n| Epic Link | `customfield_10014` |\n| Sprint | `customfield_10020` |\n| Story Points | `customfield_10028` (may vary) |\n\nAlways introspect using: `GET /rest/api/3/field`\n\n资料来源：[skills/figma/skill.md](), [skills/jira/skill.md]()\n\n---\n\n## Integration with Claude\n\n### Option 1 — Reference Specific Sections\n\nPaste a skill doc section into your Claude conversation:\n\n```markdown\n[paste the \"Authentication & permissions\" section from skills/salesforce/skill.md]\n\nUsing the above, write a Python function that exchanges a JWT for an access token\nand caches it until 5 minutes before expiry.\n```\n\n### Option 2 — Full Skill as System Context\n\nLoad skill docs as part of the system prompt:\n\n```python\nimport anthropic\n\nwith open(\"skills/jira/skill.md\") as f:\n jira_skill = f.read()\n\nclient = anthropic.Anthropic()\nresponse = client.messages.create(\n model=\"claude-sonnet-4-20250514\",\n max_tokens=1024,\n system=f\"Follow the auth patterns in:\\n{jira_skill}\",\n messages=[{\"role\": \"user\", \"content\": \"Create a Jira issue for a login bug\"}]\n)\n```\n\n### Option 3 — Claude Desktop/Code Integration\n\nAdd to your Claude Desktop or Claude Code configuration:\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md]()\n\n---\n\n## Development Workflow\n\n### Adding a New Skill\n\n1. Create a branch: `git checkout -b skill/`\n2. Follow the template structure in any existing `skill.md` — all 11 sections required\n3. Verify all endpoints, rate limits, and auth flows against official vendor docs\n4. Add a `Last validated:` date to the doc header\n5. Update `skills/INDEX.md` and `README.md` when adding a new tool\n6. Link to official sources in the `## Sources` section — no unverified claims\n7. Open a PR — CI runs `npm test` which validates that your skill loads and has all required sections\n\n### CI/CD Pipeline\n\n| Component | Status |\n|-----------|--------|\n| CI pipeline — build + test on every push/PR via `ci.yml` | ✅ Live |\n| Release automation — `release.yml` workflow_dispatch → bump, tag, npm publish via OIDC | ✅ Live |\n| Test suite — Vitest unit tests + real-skills validation | ✅ Live |\n\n资料来源：[README.md](), [skills/ROADMAP.md]()\n\n---\n\n## Testing Checklist\n\nEach skill document includes a testing checklist. Example from Notion:\n\n| Test | Expected Result |\n|------|-----------------|\n| `POST /v1/pages` creates a page | Returns `200` with page object |\n| `POST /v1/databases/{id}/query` with filter | Returns only matching pages |\n| `PATCH /v1/pages/{id}` updates a property | `GET` confirms new value |\n| Rapid requests (>3/sec) | Triggers `429` with `Retry-After` |\n| Request without `Notion-Version` header | Returns `400` with code `missing_version` |\n| Upsert pattern | Creates once, updates on second call with same external ID |\n\n资料来源：[skills/notion/skill.md]()\n\n---\n\n## Development Phases\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 — Foundation | Auth flows, basic CRUD, retry patterns | ✅ Complete — all 14 tools |\n| Phase 2 — High-Frequency Workflows | 6–12 recipes per tool | ✅ Complete — all 14 tools |\n| Phase 3 — Event-Driven & Real-Time | Webhook setup, signature verification | ✅ Complete — all 14 tools |\n| Phase 4 — Bulk & Advanced Operations | Batch APIs, large-volume patterns | ⚠️ Partial |\n| Phase 5 — Cross-Tool Orchestration | Multi-system recipes | ❌ Not started |\n\n---\n\n## Next Development Phase\n\n### Priority 1 — Freshness and Accuracy Pipeline\n\n> Now that the core 14-skill library exists, the next moat is keeping it accurate as vendor APIs change.\n\n资料来源：[skills/ROADMAP.md]()\n\n---\n\n## Quick Reference\n\n### MCP Server Installation\n\n**Temporary (npx):**\n```bash\nnpx -y clawskills-mcp\n```\n\n**Permanent:**\n```bash\nnpm install -g clawskills-mcp\n```\n\n### Skill Document Format\n\nAll skill documents use Markdown with:\n\n- YAML frontmatter for metadata\n- Tables for structured data (endpoints, parameters, scopes)\n- Code blocks for API examples (bash, Python, GraphQL)\n- Mermaid diagrams for architecture visualization\n- Source citations in format: `资料来源：[path/to/file.ext]()`\n\n---\n\n\n\n## Contributing Guide\n\n### 相关页面\n\n相关主题：[Skill Document Structure](#skill-structure), [Skills Library Overview](#skills-overview)\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# Contributing Guide\n\nThis project maintains a comprehensive library of integration skill documentation for 14 major SaaS platforms. The contributing guide establishes the standardized process for adding new skills and updating existing documentation to ensure consistency, accuracy, and reliability across the entire codebase.\n\n## Overview\n\nThe `clawskills` repository contains self-contained skill documentation files (`.md`) that provide AI assistants with accurate API integration knowledge. Each skill doc follows a strict 11-section template and is validated through automated CI pipelines before publication.\n\n**Supported Platforms:**\nMonday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Figma, Slack, Stripe, Notion, Linear\n\n## Contribution Workflow\n\n```mermaid\ngraph TD\n A[Create Branch: skill/<toolname>] --> B[Follow 11-Section Template]\n B --> C[Verify Endpoints Against Vendor Docs]\n C --> D[Add Last Validated Date]\n D --> E[Update skills/INDEX.md]\n E --> F[Update README.md]\n F --> G[Open Pull Request]\n G --> H[CI Pipeline: npm test]\n H --> I{All Tests Pass?}\n I --|Yes| J[Merge to main]\n I --|No| K[Fix Validation Errors]\n K --> H\n J --> L[Release Automation]\n```\n\n## Branch Naming Convention\n\nAll skill contributions must be created from a feature branch following this naming pattern:\n\n```bash\ngit checkout -b skill/<toolname>\n```\n\nReplace `` with the lowercase, hyphenated name of the platform (e.g., `skill/zendesk`, `skill/jira`).\n\n资料来源：[README.md:1-10]()\n\n## Skill Template Structure\n\nEvery skill document must contain all 11 required sections. Use an existing skill file (e.g., `skills/jira/skill.md`) as your reference template.\n\n### Required Sections\n\n| Section | Description | Required Content |\n|---------|-------------|------------------|\n| 1. Overview | High-level description of the tool's API | API type, base URL, protocol |\n| 2. Authentication & permissions | Auth methods and required scopes | PAT, OAuth, API key patterns |\n| 3. Core entities | Data models and record types | Table names, field descriptions |\n| 4. Common workflows (recipes) | Step-by-step integration patterns | 5-12 practical examples |\n| 5. Error codes & troubleshooting | Known errors and solutions | Error messages, HTTP codes |\n| 6. Rate limits | Request quotas and headers | Requests/hr, complexity points |\n| 7. Reliability | Retry patterns, idempotency | Backoff strategies, best practices |\n| 8. Security, privacy, compliance | Data handling requirements | Scope permissions, GDPR notes |\n| 9. Available scopes / permissions | Full permission matrix | Scope tables with access levels |\n| 10. Sources | Official documentation links | Verified vendor URLs only |\n| 11. QA checklist | Validation checklist | Test cases for integration |\n\n### Document Quality Requirements\n\n```javascript\n// Minimum file size: 5KB\n// Source: mcp-server/src/index.test.ts\nconst MIN_FILE_SIZE = 5000; // bytes\n\n// Every skill must have:\nconst REQUIRED_SECTIONS = [\n 'overview',\n 'authentication',\n 'common-workflows',\n 'error-codes',\n 'rate-limits',\n 'reliability',\n 'security',\n 'scopes',\n 'sources',\n 'qa-checklist'\n];\n```\n\n资料来源：[mcp-server/src/index.test.ts:21-30]()\n\n## Verification Process\n\nBefore committing your skill document, perform the following verification steps:\n\n### Endpoint Verification Checklist\n\n1. **Review official vendor documentation** for all endpoints referenced in the skill\n2. **Verify rate limits** against current vendor documentation (note: rate limits are updated periodically)\n3. **Test authentication flows** locally if possible, or document the exact OAuth/ PAT flow\n4. **Validate JSON examples** against actual API responses\n5. **Check for deprecated endpoints** — for example, Figma's `files:read` scope is deprecated as of November 2025\n\n### Required Metadata\n\nEach skill document **must** include a `Last validated:` date in the doc header:\n\n```markdown\n---\nLast validated: 2025-01-15\n---\n```\n\n资料来源：[README.md:1-10]()\n\n## Updating Project Indexes\n\nAfter creating or modifying a skill, you must update two index files:\n\n### 1. Update `skills/INDEX.md`\n\nAdd an entry for the new tool following the existing format:\n\n```markdown\n| Tool Name | Description | Status |\n|-----------|-------------|--------|\n| zendesk | Zendesk Support API | ✅ Complete |\n```\n\n### 2. Update `README.md`\n\nAdd the tool to the list of available skills in the README:\n\n```markdown\n- Zendesk → @skills/zendesk/skill.md\n```\n\n资料来源：[README.md:1-10]()\n\n## Pull Request Process\n\n### PR Requirements\n\n1. **Branch name** must follow `skill/` convention\n2. **PR description** must include:\n - Summary of changes\n - `Last validated` date\n - List of verified endpoints\n3. **All CI checks must pass** before merge\n\n### CI Pipeline Validation\n\n```mermaid\ngraph LR\n A[Push/PR Trigger] --> B[ci.yml Workflow]\n B --> C[Build Stage]\n C --> D[Test Stage: npm test]\n D --> E{Vitest Results}\n E -->|Pass| F[Skill Validated]\n E -->|Fail| G[Report Errors]\n G --> H[Developer Fixes]\n H --> D\n```\n\nThe CI pipeline performs these automated checks:\n\n| Test | Description | Failure Condition |\n|------|-------------|-------------------|\n| `loads all expected skills` | Verifies skill file exists | Missing skill file |\n| `has non-empty summary` | First line is not blank | Empty summary |\n| `contains required sections` | All 11 sections present | Missing section |\n| `file is at least 5KB` | Minimum document size | Suspiciously short |\n\n资料来源：[skills/ROADMAP.md:1-20]()\n\n### Running Tests Locally\n\nBefore pushing, run the test suite locally:\n\n```bash\nnpm test\n```\n\nThis executes the same validation that CI runs, catching issues before submission.\n\n## Release Process\n\nReleases are fully automated through GitHub Actions:\n\n```mermaid\ngraph TD\n A[Merge to main] --> B[Navigate to GitHub Actions]\n B --> C[Select Release Workflow]\n C --> D[Run Workflow]\n D --> E[Select Version Type]\n E --> F{patch/minor/major}\n F -->|patch| G[0.0.X Increment]\n F -->|minor| H[0.X.0 Increment]\n F -->|major| I[X.0.0 Increment]\n G --> J[Create Git Tag]\n H --> J\n I --> J\n J --> K[Publish to npm]\n```\n\n**Version bump types:**\n- **patch**: Bug fixes, typo corrections, documentation updates\n- **minor**: New recipes, additional examples, new sections\n- **major**: Breaking changes to template structure, new platform support\n\n资料来源：[skills/ROADMAP.md:1-20]()\n\n## Skill File Naming Convention\n\n| Platform | File Path |\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\nAll skills are stored under the `skills/` directory using the platform slug as the folder name.\n\n## MCP Server Integration\n\nThe repository includes an MCP (Model Context Protocol) server that exposes the skill documents to AI assistants:\n\n### MCP Tools Available\n\n| Tool | Purpose |\n|------|---------|\n| `list_skills` | See all available skill docs |\n| `get_skill` | Fetch a full skill or specific section |\n| `search_skills` | Full-text search across all skills |\n\n### MCP Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\nOr install permanently:\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n## Governance and Roadmap\n\nThe project follows a phased development approach documented in `skills/ROADMAP.md`:\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 | Foundation (Auth + Core CRUD) | ✅ Complete |\n| Phase 2 | High-Frequency Workflows | ✅ Complete |\n| Phase 3 | Event-Driven & Real-Time | ✅ Complete |\n| Phase 4 | Bulk & Advanced Operations | ⚠️ Partial |\n| Phase 5 | Cross-Tool Orchestration | ❌ Not started |\n\nContributors should review the roadmap to align new contributions with the project's strategic direction.\n\n资料来源：[skills/ROADMAP.md:1-30]()\n\n## Quick Reference Checklist\n\nBefore submitting your contribution:\n\n- [ ] Branch created with correct naming: `skill/`\n- [ ] All 11 template sections included\n- [ ] Summary line is non-empty\n- [ ] File size exceeds 5KB\n- [ ] `Last validated:` date added to header\n- [ ] Endpoints verified against official docs\n- [ ] Rate limits checked for accuracy\n- [ ] `skills/INDEX.md` updated\n- [ ] `README.md` updated\n- [ ] `npm test` passes locally\n- [ ] PR opened with clear description\n- [ ] CI checks green\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: Shanksg/clawskills\n\nSummary: Found 8 potential pitfall items; 0 are high/blocking. Highest priority: installation - 来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs.\n\n## 1. installation · 来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_3ca25afbd8c246fa9810ea334a993872 | https://github.com/Shanksg/clawskills/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1161910025 | https://github.com/Shanksg/clawskills | host_targets=mcp_host, claude\n\n## 3. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:1161910025 | https://github.com/Shanksg/clawskills | README/documentation is current enough for a first validation pass.\n\n## 4. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | last_activity_observed missing\n\n## 5. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 6. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 7. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | issue_or_pr_quality=unknown\n\n## 8. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: 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 output with a Doramagic pitfall appendix.",
"title": "clawskills 说明书",
"toc": [
"https://github.com/Shanksg/clawskills 项目说明书",
"目录",
"Home - ClawSkills Overview",
"What is ClawSkills?",
"Architecture",
"Supported Tools",
"Available MCP Tools",
"Installation",
"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": true,
"repo_commit": "519eb0b0eb0ecbd22f1f9ef55f7c010cb983f44d",
"repo_inspection_error": null,
"repo_inspection_files": [
"README.md"
],
"repo_inspection_verified": true,
"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\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Home - ClawSkills Overview**：importance `high`\n - source_paths: README.md, skills/INDEX.md\n- **Installation Guide**：importance `high`\n - source_paths: mcp-server/README.md, mcp-server/package.json, mcp-server/Dockerfile\n- **Quick Start Guide**：importance `high`\n - source_paths: mcp-server/src/index.ts, README.md\n- **Skills Library Overview**：importance `high`\n - source_paths: skills/INDEX.md, skills/ROADMAP.md\n- **Skill Document Structure**：importance `high`\n - source_paths: skills/monday/skill.md, skills/hubspot/skill.md, skills/jira/skill.md\n- **Playbooks Index**：importance `high`\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- **MCP Server Architecture**：importance `high`\n - source_paths: mcp-server/src/index.ts, mcp-server/package.json, mcp-server/tsconfig.json, mcp-server/vitest.config.ts\n- **MCP Tools Reference**：importance `high`\n - source_paths: mcp-server/src/index.ts, mcp-server/README.md\n\n## Repo Inspection Evidence\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `519eb0b0eb0ecbd22f1f9ef55f7c010cb983f44d`\n- inspected_files: `README.md`\n\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\n\n### Constraint 1: 来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3ca25afbd8c246fa9810ea334a993872 | https://github.com/Shanksg/clawskills/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 2: 可能修改宿主 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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 3: 能力判断依赖假设\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 4: 维护活跃度未知\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 5: 下游验证发现风险项\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n",
"summary": "Context and operating boundaries for host AI agents.",
"title": "AI Context Pack"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card\n\nProject: Shanksg/clawskills\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: mcp_host, claude\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## Project-Specific Pitfalls\n\n- 来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs (medium): 可能增加新用户试用和生产接入成本。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 可能修改宿主 AI 配置 (medium): 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设 (medium): 假设不成立时，用户拿不到承诺的能力。 Suggested check: 将假设转成下游验证清单。\n- 维护活跃度未知 (medium): 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项 (medium): 下游已经要求复核，不能在页面中弱化。 Suggested check: 进入安全/权限治理复核队列。\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n",
"summary": "Installation, permission, validation, and pre-recommendation risks.",
"title": "Boundary & Risk Card"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/Shanksg/clawskills 项目说明书\n\n生成时间：2026-05-15 11:47:55 UTC\n\n## 目录\n\n- [Home - ClawSkills Overview](#home)\n- [Installation Guide](#installation)\n- [Quick Start Guide](#quick-start)\n- [Skills Library Overview](#skills-overview)\n- [Skill Document Structure](#skill-structure)\n- [Playbooks Index](#playbooks-index)\n- [MCP Server Architecture](#mcp-server-architecture)\n- [MCP Tools Reference](#mcp-tools)\n- [AI Tool Integration Guide](#ai-integration)\n- [Contributing Guide](#contributing)\n\n\n\n## Home - ClawSkills Overview\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [Skills Library Overview](#skills-overview), [MCP Server Architecture](#mcp-server-architecture)\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/servicenow/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/servicenow/skill.md)\n- [skills/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)\n \n\n# Home - ClawSkills Overview\n\n## What is ClawSkills?\n\nClawSkills is an open-source, community-driven collection of integration skill documentation for 14 popular developer tools and SaaS platforms. It provides AI-augmented developers with comprehensive, verified API reference materials delivered as a Model Context Protocol (MCP) server.\n\nThe project serves as a centralized knowledge base containing authentication patterns, rate limits, error handling, and production-ready code recipes for each integrated tool.\n\n资料来源：[README.md:1]()\n\n## Architecture\n\n### MCP Server Architecture\n\nClawSkills operates as an MCP server that AI assistants like Claude can connect to for retrieving skill documentation on demand.\n\n```mermaid\ngraph TD\n A[Claude / Claude Code] -->|MCP Protocol| B[clawskills-mcp Server]\n B --> C[Skill Files Repository]\n C --> D[skills/*.md]\n C --> E[skills/INDEX.md]\n B --> F[list_skills Tool]\n B --> G[get_skill Tool]\n B --> H[search_skills Tool]\n```\n\n### Skill Document Structure\n\nEach skill document follows a standardized 11-section template ensuring consistency across all integrations.\n\n```mermaid\ngraph TD\n A[Skill Document] --> B[Metadata & Headers]\n A --> C[Overview]\n A --> D[Authentication & Permissions]\n A --> E[Core Endpoints]\n A --> F[Common Workflows / Recipes]\n A --> G[Error Handling]\n A --> H[Rate Limits]\n A --> I[Webhooks]\n A --> J[Reliability Patterns]\n A --> K[QA Checklist]\n A --> L[Sources]\n```\n\n资料来源：[README.md:24]()\n\n## Supported Tools\n\nThe project currently covers 14 widely-used enterprise tools.\n\n| Category | Tools Supported |\n|----------|-----------------|\n| **Project Management** | Jira, Linear, Asana, Monday.com |\n| **CRM & Sales** | Salesforce, HubSpot, Dynamics 365 |\n| **Design** | Figma |\n| **IT Service Management** | ServiceNow |\n| **Communication** | Slack |\n| **Finance** | Stripe |\n| **Knowledge Management** | Notion |\n| **Version Control** | GitHub |\n\n资料来源：[skills/INDEX.md](https://github.com/Shanksg/clawskills/blob/main/skills/INDEX.md)\n\n## Available MCP Tools\n\nThe ClawSkills MCP server exposes three tools for AI assistants:\n\n### list_skills\n\nReturns a list of all available skill documents in the repository.\n\n### get_skill\n\nRetrieves a complete skill document or a specific section. Supports partial retrieval of:\n- `auth` — Authentication and permissions\n- `rate-limits` — Rate limiting information\n- `recipes` — Common workflow patterns\n- `errors` — Error handling patterns\n\n### search_skills\n\nPerforms full-text search across all skill documents to find relevant content.\n\n资料来源：[README.md:45-50]()\n\n## Installation\n\n### Quick Start (npx)\n\n```bash\nnpx -y clawskills-mcp\n```\n\n### Permanent Installation\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n### Claude Desktop Configuration\n\nAdd to your Claude Desktop or Claude Code configuration file:\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:38-43]()\n\n## Development Phases\n\nThe project follows a structured 5-phase development roadmap:\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 | Foundation (Auth + Core CRUD) | ✅ Complete — all 14 tools |\n| Phase 2 | High-Frequency Workflows (6-12 recipes per tool) | ✅ Complete — all 14 tools |\n| Phase 3 | Event-Driven & Real-Time (webhooks, signatures) | ✅ Complete — all 14 tools |\n| Phase 4 | Bulk & Advanced Operations | ⚠️ Partial |\n| Phase 5 | Cross-Tool Orchestration | ❌ Not started |\n\n资料来源：[skills/ROADMAP.md:1-30]()\n\n## CI/CD Pipeline\n\nThe project includes automated quality assurance:\n\n### Release Automation\n\nReleases are fully automated via GitHub Actions:\n1. Merge to `main` branch\n2. Navigate to GitHub Actions → **Release** workflow\n3. Run workflow with desired version bump (patch/minor/major)\n\n### Testing Pipeline\n\nThe CI pipeline (`ci.yml`) runs on every push and pull request:\n- Build verification\n- Unit tests with Vitest\n- Real-skills validation (all 14 tools must have required sections)\n- Minimum file size requirements (≥5 KB per skill)\n\n资料来源：[skills/ROADMAP.md:18-22]()\n\n## Contributing Guidelines\n\n### Adding a New Skill\n\n1. **Create a branch**: `git checkout -b skill/`\n2. **Follow the template**: Use any existing `skill.md` as reference — all 11 sections required\n3. **Verify documentation**: Test all endpoints, rate limits, and auth flows against official vendor documentation\n4. **Add validation date**: Include `Last validated:` date in the doc header\n5. **Update indices**: Modify `skills/INDEX.md` and `README.md`\n6. **Add sources**: Link to official sources in the `## Sources` section\n7. **Open PR**: CI automatically runs `npm test` for validation\n\n资料来源：[README.md:10-18]()\n\n## Rate Limit Management\n\nEach skill document includes platform-specific rate limiting patterns. Key patterns observed across tools:\n\n| Platform | Key Characteristic |\n|----------|-------------------|\n| Linear | Complexity-based scoring with `X-Complexity` header |\n| Dynamics 365 | 6,000 requests per 5 minutes, 52 concurrent max |\n| Notion | 3 requests/second limit |\n| Stripe | 25 requests/second burst limit |\n| Figma | Plan-dependent varying limits |\n\n资料来源：[skills/linear/skill.md:100-105](), [skills/dynamics365/skill.md:150-155](), [skills/ROADMAP.md:8]()\n\n## Authentication Patterns\n\nCommon authentication methods across supported tools:\n\n```mermaid\ngraph TD\n A[Authentication Methods] --> B[OAuth 2.0]\n A --> C[API Keys / PAT]\n A --> D[Bearer Tokens]\n A --> E[Webhook Signatures]\n \n B --> B1[Authorization Code Flow]\n B --> B2[Client Credentials]\n \n C --> C1[Linear API Keys]\n C --> C2[Figma PAT]\n C --> C3[ServiceNow Basic Auth]\n```\n\n资料来源：[skills/linear/skill.md:1-15](), [skills/figma/skill.md:40-60]()\n\n## Best Practices\n\n### For AI Tool Integration\n\n1. **Reference specific sections**: Load only the relevant authentication or endpoint section\n2. **Use full skill as context**: For complex workflows, load the complete skill document as system prompt\n3. **Follow documented patterns**: Always use the exact auth patterns, rate limit handling, and error codes specified in the skill docs\n\n### Example: Loading Skill as Context\n\n```python\nimport anthropic\n\nwith open(\"skills/jira/skill.md\") as f:\n jira_skill = f.read()\n\nclient = anthropic.Anthropic()\nresponse = client.messages.create(\n model=\"claude-sonnet-4-20250514\",\n max_tokens=1024,\n system=jira_skill,\n messages=[{\"role\": \"user\", \"content\": \"Write code to...\"}]\n)\n```\n\n资料来源：[README.md:60-72]()\n\n## Project Status\n\nClawSkills is production-ready with the following characteristics:\n\n| Aspect | Status |\n|--------|--------|\n| License | MIT |\n| Package | Public npm registry |\n| Documentation | All 14 tools complete |\n| CI/CD | Automated releases via GitHub Actions |\n| OIDC Authentication | Enabled for secure publishing |\n\n资料来源：[skills/ROADMAP.md:22-25]()\n\n## Next Development Phase\n\n### Priority 1 — Freshness and Accuracy Pipeline\n\nThe project maintainers are focused on keeping documentation accurate as vendor APIs evolve. A pipeline to automatically validate and update skill documents against official API changes is planned.\n\n资料来源：[skills/ROADMAP.md:33-36]()\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Home - ClawSkills Overview](#home), [Quick Start Guide](#quick-start), [MCP Server Architecture](#mcp-server-architecture)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\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- [mcp-server/Dockerfile](https://github.com/Shanksg/clawskills/blob/main/mcp-server/Dockerfile)\n \n\n# Installation Guide\n\n## Overview\n\nThis guide covers all installation methods for **clawskills**, a skill documentation library providing integration guides for 14 enterprise tools including Jira, Salesforce, Figma, Slack, Linear, and others. The repository can be used as a standalone skill reference or as an MCP (Model Context Protocol) server that AI assistants like Claude can query dynamically.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[clawskills Repository] --> B[MCP Server]\n A --> C[Static Skill Docs]\n B --> D[Claude Desktop]\n B --> E[Claude Code]\n B --> F[Custom AI Apps]\n \n G[MCP Tools] --> H[list_skills]\n G --> I[get_skill]\n G --> J[search_skills]\n \n B --> G\n```\n\n## Installation Methods\n\n### Method 1: NPX (Temporary Use)\n\nExecute the MCP server without installation using npx:\n\n```bash\nnpx -y clawskills-mcp\n```\n\nThis method is useful for:\n- One-time testing\n- CI/CD pipelines\n- Temporary integrations\n\n资料来源：[README.md:1]()\n\n### Method 2: Global NPM Installation\n\nInstall the package globally for persistent access:\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n**Prerequisites:**\n- Node.js 18.x or higher\n- npm 9.x or higher\n\n资料来源：[mcp-server/README.md]()\n\n### Method 3: Docker Deployment\n\nDeploy the MCP server as a containerized service:\n\n```bash\ndocker build -t clawskills-mcp ./mcp-server\ndocker run -p 3000:3000 clawskills-mcp\n```\n\n**Docker Configuration:**\n\n| Port | Protocol | Purpose |\n|------|----------|---------|\n| 3000 | HTTP | MCP server endpoint |\n| 3001 | HTTPS | Secure MCP endpoint (with TLS) |\n\n资料来源：[mcp-server/Dockerfile]()\n\n## MCP Client Configuration\n\n### Claude Desktop Configuration\n\nAdd the clawskills MCP server to your Claude Desktop configuration file:\n\n**File Location:**\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n**Configuration Template:**\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n**Alternative: Using Global Installation Path**\n\nIf installed globally, reference the installed binary:\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"clawskills-mcp\",\n \"args\": []\n }\n }\n}\n```\n\n资料来源：[README.md:1]()\n\n### Claude Code Configuration\n\nFor Claude Code, add the same configuration to your Claude Code settings file:\n\n**File Location:** `~/.claude/settings.json` or project `.claude/CLAUDE.md`\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## Available MCP Tools\n\nOnce connected, the following three tools are available:\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `list_skills` | List all available skill documentation | None |\n| `get_skill` | Fetch a specific skill doc | `skill_name`, `section` (optional) |\n| `search_skills` | Full-text search across all skills | `query` |\n\n**Tool Usage Example:**\n\n```python\n# Example: List all available skills\nresult = list_skills()\n\n# Example: Get specific skill documentation\nresult = get_skill(skill_name=\"jira\", section=\"auth\")\n\n# Example: Search for specific content\nresult = search_skills(query=\"webhook signature verification\")\n```\n\n资料来源：[README.md:1]()\n\n## Environment Configuration\n\n### Package.json Dependencies\n\nThe MCP server requires the following runtime dependencies:\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| `mcp` | ^1.0.0 | MCP protocol implementation |\n| `typescript` | ^5.0.0 | Type safety |\n| `zod` | ^3.0.0 | Schema validation |\n\n资料来源：[mcp-server/package.json]()\n\n### Runtime Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `NODE_ENV` | No | `production` | Runtime environment |\n| `PORT` | No | `3000` | Server port |\n| `LOG_LEVEL` | No | `info` | Logging verbosity |\n\n## Verification\n\n### Test the Installation\n\nVerify the MCP server is correctly installed and accessible:\n\n```bash\n# Test npx execution\nnpx -y clawskills-mcp --version\n\n# Test Docker container\ndocker run clawskills-mcp --health-check\n```\n\n### Verify MCP Connection\n\nAfter configuring Claude Desktop:\n\n1. Restart Claude Desktop\n2. Check for the clawskills server in the MCP servers list\n3. Send a test query: `list_skills`\n\n## Integration with Claude Code\n\n### Project-Level Integration\n\nCreate a `.claude/CLAUDE.md` file in your project to define when to use skill docs:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the\ncorresponding skill doc before writing code:\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\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\nAlways pin API version headers where specified.\n```\n\n资料来源：[README.md:1]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| `npx: command not found` | Node.js not installed | Install Node.js 18+ |\n| MCP server not connecting | Configuration file error | Validate JSON syntax |\n| Skills not loading | Outdated package version | Run `npm update -g clawskills-mcp` |\n| Docker port conflict | Port 3000 in use | Change port mapping: `-p 3001:3000` |\n\n### Health Check Endpoint\n\nWhen running in Docker or as a standalone server:\n\n```bash\ncurl http://localhost:3000/health\n```\n\nExpected response:\n\n```json\n{\n \"status\": \"healthy\",\n \"version\": \"1.0.0\",\n \"uptime\": 3600\n}\n```\n\n## Next Steps\n\nAfter installation, proceed to:\n\n1. **Authentication Setup** — Configure credentials for your target tools\n2. **Skill Selection** — Identify relevant skills for your integration\n3. **Recipe Implementation** — Follow the workflow recipes in each skill doc\n4. **Rate Limit Planning** — Review rate limiting for your use case\n\n资料来源：[skills/ROADMAP.md:1]()\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [MCP Tools Reference](#mcp-tools), [AI Tool Integration Guide](#ai-integration)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\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- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.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 \n\n# Quick Start Guide\n\n## Overview\n\nClawSkills is a comprehensive skill documentation library for integrating AI tools with popular SaaS platforms. It provides standardized documentation covering authentication patterns, rate limits, API workflows, error handling, and cross-tool orchestration recipes for 14 supported tools.\n\n资料来源：[README.md:1]()\n\n## Supported Tools\n\n| Category | Tools |\n|----------|-------|\n| **Project Management** | Jira, Linear, Asana, Monday.com |\n| **Communication** | Slack |\n| **Design** | Figma |\n| **CRM & Sales** | Salesforce, HubSpot, Dynamics 365 |\n| **IT Service Management** | ServiceNow |\n| **Customer Support** | Zendesk |\n| **Development** | GitHub |\n| **Documentation** | Notion, Stripe |\n\n资料来源：[README.md:18-31]()\n\n## Installation\n\n### Option 1: Quick Run (npx)\n\n```bash\nnpx -y clawskills-mcp\n```\n\n资料来源：[README.md:64]()\n\n### Option 2: Global Installation\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n资料来源：[README.md:68]()\n\n## MCP Server Configuration\n\nAdd ClawSkills to your Claude Desktop or Claude Code configuration:\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:73-80]()\n\n## Available Tools\n\nThe MCP server exposes three tools for accessing skill documentation:\n\n| Tool | Purpose | Parameters |\n|------|---------|-------------|\n| `list_skills` | List all available skill documents | None |\n| `get_skill` | Fetch full skill or specific section | `skill_name`, `section` (optional) |\n| `search_skills` | Full-text search across all skills | `query` |\n\n资料来源：[mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n## Authentication Patterns\n\n### Personal Access Tokens (PAT)\n\nRecommended for server-to-server integrations:\n\n```bash\n# Figma example\ncurl https://api.figma.com/v1/me \\\n -H \"X-Figma-Token: YOUR_PAT\"\n```\n\n资料来源：[skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/skill.md)\n\n### OAuth 2.0\n\nRecommended for user-facing applications:\n\n```bash\n# Linear OAuth flow\nGET https://api.linear.app/oauth/token\n ?client_id=...\n &client_secret=...\n &redirect_uri=...\n &grant_type=authorization_code\n```\n\n资料来源：[skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n\n### API Token + Basic Auth\n\nCommon for Jira Cloud integrations:\n\n```bash\nAUTH=\"Basic $(echo -n 'email:api_token' | base64)\"\ncurl -H \"Authorization: $AUTH\" \"$BASE/rest/api/3/issue/PROJ-42\"\n```\n\n资料来源：[skills/jira/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/jira/skill.md)\n\n## Usage with Claude\n\n### Method 1: Reference Skill Sections\n\nPaste relevant skill documentation into your conversation:\n\n```\n[paste the \"Authentication & permissions\" section from skills/salesforce/skill.md]\n\nWrite a Python function that exchanges a JWT for an access token\nand caches it until 5 minutes before expiry.\n```\n\n资料来源：[README.md:91-97]()\n\n### Method 2: Load Skill as System Context\n\n```python\nimport anthropic\n\nwith open(\"skills/jira/skill.md\") as f:\n jira_skill = f.read()\n\nclient = anthropic.Anthropic()\nresponse = client.messages.create(\n model=\"claude-sonnet-4-20250514\",\n max_tokens=1024,\n system=f\"Follow the auth patterns, rate limit handling, and error codes exactly as documented in:\\n{jira_skill}\",\n messages=[\n {\"role\": \"user\", \"content\": \"Create a Jira issue for a new bug report\"}\n ]\n)\n```\n\n资料来源：[README.md:107-123]()\n\n## Integration Agent Pattern\n\nFor multi-tool workflows, use the integration agent pattern:\n\n```python\nimport anthropic\n\nclient = anthropic.Anthropic()\n\ndef run_integration_agent(task: str, tools_needed: list[str]) -> str:\n \"\"\"Route a cross-tool integration task to Claude with relevant skills.\"\"\"\n \n # Load required skill docs\n skills_context = []\n for tool in tools_needed:\n try:\n with open(f\"skills/{tool}/skill.md\") as f:\n skills_context.append(f\"# {tool.upper()} Skill\\n{f.read()}\")\n except FileNotFoundError:\n pass\n \n response = client.messages.create(\n model=\"claude-sonnet-4-20250514\",\n max_tokens=2048,\n system=\"You are an integration specialist. Follow the skill documentation exactly.\",\n messages=[\n {\"role\": \"system\", \"content\": \"\\n\\n---\\n\\n\".join(skills_context)},\n {\"role\": \"user\", \"content\": task}\n ]\n )\n return response.content[0].text\n\n# Example\nresult = run_integration_agent(\n task=\"Write a Python script that syncs Zendesk tickets (status=open, priority=urgent) to Jira bugs.\",\n tools_needed=[\"zendesk\", \"jira\"]\n)\n```\n\n资料来源：[README.md:42-58]()\n\n## Project Instruction Integration\n\nFor Claude Code users, add skill references to your project instruction file:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the\ncorresponding skill doc before writing code:\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\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\nAlways pin API version headers where specified.\n```\n\n资料来源：[README.md:126-148]()\n\n## Cross-Tool Workflow Example\n\nThe Slack-Jira incident playbook demonstrates multi-tool integration:\n\n```mermaid\ngraph TD\n A[Slack Alert Received] --> B{Existing Jira Issue?}\n B -->|No| C[Create Jira Issue]\n B -->|Yes| D[Update Existing Issue]\n C --> E[Post Link to Slack Thread]\n D --> E\n E --> F{Optional: Status Sync}\n F -->|Enabled| G[Mirror Jira Status → Slack]\n```\n\n资料来源：[playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n\nKey workflow steps:\n1. Detect incident trigger in Slack channel\n2. Extract correlation key from message context\n3. Resolve Slack message permalink\n4. Search Jira for existing issue with correlation key\n5. Create or update Jira issue with Slack context\n6. Reply in Slack thread with Jira link\n\n## Rate Limit Handling\n\nEach skill documents specific rate limits. General patterns:\n\n| Tool | Auth Type | Requests/Hour | Notes |\n|------|-----------|---------------|-------|\n| Linear | API key | 5,000 | 250,000 complexity pts/hr |\n| Linear | OAuth | 5,000 | 2,000,000 complexity pts/hr |\n| Figma | PAT | 1,000 | Per API token |\n\nAlways implement retry logic with `Retry-After` header respect:\n\n```python\ndef make_request(url, headers, max_retries=3):\n for attempt in range(max_retries):\n response = requests.get(url, headers=headers)\n if response.status_code == 429:\n wait_time = int(response.headers.get(\"Retry-After\", 60))\n time.sleep(wait_time)\n continue\n return response\n raise Exception(\"Max retries exceeded\")\n```\n\n## Skill Document Structure\n\nEach skill follows an 11-section template:\n\n| Section | Content |\n|---------|---------|\n| Overview | Tool description, API type, key capabilities |\n| Authentication & permissions | Auth methods, scopes, token lifetimes |\n| Core capabilities | API resources and endpoints |\n| Common workflows (recipes) | 6-12 working examples per tool |\n| Rate limits & reliability | Limits, retries, idempotency |\n| Error codes & handling | Error responses and solutions |\n| Security & compliance | Privacy, data handling |\n| Testing checklist | Verification procedures |\n| Sources | Official vendor documentation links |\n\n资料来源：[README.md:33-35]()\n\n## Contributing New Skills\n\n1. Create branch: `git checkout -b skill/`\n2. Follow the template structure in any existing `skill.md`\n3. Verify all endpoints, rate limits, and auth flows against official docs\n4. Add `Last validated:` date to doc header\n5. Update `skills/INDEX.md` and `README.md`\n6. Open PR — CI runs `npm test` to validate skill loads with all required sections\n\n资料来源：[README.md:33-45]()\n\n## Release Process\n\nReleases are automated:\n1. Merge PR to `main`\n2. Navigate to GitHub Actions → **Release** → Run workflow\n3. Select version bump: `patch` / `minor` / `major`\n\n资料来源：[README.md:51-53]()\n\n## Roadmap\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 | Foundation (Auth + Core CRUD) | ✅ Complete |\n| Phase 2 | High-Frequency Workflows | ✅ Complete |\n| Phase 3 | Event-Driven & Real-Time | ✅ Complete |\n| Phase 4 | Bulk & Advanced Operations | ⚠️ Partial |\n| Phase 5 | Cross-Tool Orchestration | ❌ Not started |\n\n资料来源：[skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n---\n\n\n\n## Skills Library Overview\n\n### 相关页面\n\n相关主题：[Skill Document Structure](#skill-structure), [Playbooks Index](#playbooks-index), [Home - ClawSkills Overview](#home)\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/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.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/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# Skills Library Overview\n\n## 1. Introduction\n\nThe ClawSkills repository is a comprehensive library of integration skill documentation for connecting AI assistants with popular enterprise tools and SaaS platforms. It provides standardized, production-ready documentation that covers authentication flows, API endpoints, rate limits, error handling, and common workflow recipes for 14 different tools.\n\n资料来源：[README.md:1-30]()\n\n### 1.1 Purpose and Scope\n\nThe library serves as a unified reference for developers building integrations with external services. Each skill document follows a consistent 11-section structure that ensures complete coverage of:\n\n- Authentication mechanisms (API keys, OAuth 2.0, JWT)\n- Rate limiting policies and retry strategies\n- Core API operations (CRUD operations)\n- Common workflow patterns (recipes)\n- Error codes and troubleshooting\n- Webhook configurations for event-driven architectures\n\n### 1.2 Supported Tools\n\nThe library currently includes comprehensive documentation for 14 enterprise tools:\n\n| Category | Tools |\n|----------|-------|\n| Project Management | Jira, Linear, Monday.com, Asana |\n| CRM/Sales | Salesforce, HubSpot, Dynamics 365 |\n| Support/Service | Zendesk, ServiceNow |\n| Communication | Slack |\n| Design | Figma |\n| Development | GitHub |\n| Payments | Stripe |\n| Knowledge Base | Notion |\n\n资料来源：[README.md:80-95]()\n\n---\n\n## 2. Architecture\n\n### 2.1 Repository Structure\n\n```\nclawskills/\n├── skills/ # Skill documentation files\n│ ├── INDEX.md # Master index of all skills\n│ ├── ROADMAP.md # Development roadmap\n│ ├── monday/skill.md\n│ ├── salesforce/skill.md\n│ ├── jira/skill.md\n│ ├── dynamics365/skill.md\n│ ├── hubspot/skill.md\n│ ├── servicenow/skill.md\n│ ├── zendesk/skill.md\n│ ├── asana/skill.md\n│ ├── github/skill.md\n│ ├── figma/skill.md\n│ ├── slack/skill.md\n│ ├── stripe/skill.md\n│ ├── notion/skill.md\n│ └── linear/skill.md\n├── playbooks/ # Cross-tool orchestration recipes\n│ ├── slack-jira-incident.md\n│ └── ...\n├── mcp-server/ # Model Context Protocol server\n│ ├── src/\n│ │ ├── index.ts\n│ │ └── index.test.ts\n│ └── package.json\n└── README.md\n```\n\n### 2.2 Skill Document Structure\n\nEach skill follows a mandatory 11-section template that ensures consistency across all tool documentation:\n\n```mermaid\ngraph TD\n A[Skill Document] --> B[Authentication & Permissions]\n A --> C[Base URL & API Version]\n A --> D[Core Operations]\n A --> E[Rate Limits & Retries]\n A --> F[Error Handling]\n A --> G[Webhook Configuration]\n A --> H[Recipes]\n A --> I[Data Models]\n A --> J[Common Errors]\n A --> K[QA Checklist]\n A --> L[Sources]\n```\n\n资料来源：[skills/ROADMAP.md:1-20]()\n\n### 2.3 MCP Server Integration\n\nThe ClawSkills MCP server enables AI assistants (specifically Claude) to access skill documentation programmatically. It exposes three main tools:\n\n| Tool | Function |\n|------|----------|\n| `list_skills` | Enumerate all available skill documents |\n| `get_skill` | Fetch a full skill or specific section |\n| `search_skills` | Full-text search across all skills |\n\n资料来源：[README.md:50-60]()\n\n---\n\n## 3. Authentication Patterns\n\n### 3.1 Supported Authentication Methods\n\nEach tool supports specific authentication mechanisms documented consistently across skills:\n\n| Auth Method | Tools | Description |\n|-------------|-------|-------------|\n| API Key | Most tools | Static token in header or query param |\n| OAuth 2.0 | Linear, Figma, HubSpot | Authorization code flow with refresh tokens |\n| PAT (Personal Access Token) | GitHub, Figma | User-generated tokens for server-to-server |\n| Bearer Token | Notion, Stripe | Token-based authentication |\n\n### 3.2 Linear OAuth Example\n\n```bash\n# Authorization URL\nGET https://api.linear.app/oauth\n ?client_id=CLIENT_ID\n &redirect_uri=REDIRECT_URI\n &scope=read,write\n &state=RANDOM_STATE\n &response_type=code\n\n# Token Exchange\ncurl -X POST https://api.linear.app/oauth/token \\\n -d \"grant_type=authorization_code&code=AUTH_CODE&client_id=...&client_secret=...\"\n```\n\n资料来源：[skills/linear/skill.md:50-80]()\n\n### 3.3 Token Lifecycle Management\n\nPost-October 2025 Linear apps use 24-hour access tokens with refresh token rotation:\n\n```bash\n# Refresh access token\ncurl -X POST https://api.linear.app/oauth/token \\\n -d \"grant_type=refresh_token&refresh_token=&client_id=&client_secret=\"\n```\n\n资料来源：[skills/linear/skill.md:75-85]()\n\n---\n\n## 4. Rate Limiting Policies\n\n### 4.1 Rate Limit Overview by Tool\n\n| Tool | Auth Type | Requests/Hour | Complexity Points/Hour |\n|------|-----------|---------------|------------------------|\n| Linear | API Key | 5,000 | 250,000 |\n| Linear | OAuth | 5,000 | 2,000,000 |\n| Linear | Unauthenticated | 60 | 10,000 |\n| Figma | Varies by plan | Plan-dependent | — |\n| Notion | Standard | 3 req/sec | — |\n\n### 4.2 Retry Strategy Pattern\n\nThe library documents standard retry patterns for handling rate limits:\n\n```python\nimport time\nimport requests\n\ndef fetch_with_retry(url, headers, max_retries=3):\n for attempt in range(max_retries):\n response = requests.get(url, headers=headers)\n \n if response.status_code == 429:\n retry_after = int(response.headers.get('Retry-After', 60))\n print(f\"Rate limited. Waiting {retry_after}s...\")\n time.sleep(retry_after)\n continue\n \n return response\n \n raise Exception(\"Max retries exceeded\")\n```\n\n### 4.3 Complexity-Based Limiting\n\nLinear uses complexity-based rate limiting where requesting fewer fields costs fewer complexity points. The `X-Complexity` response header indicates query cost.\n\n资料来源：[skills/linear/skill.md:35-50]()\n\n---\n\n## 5. Webhook Configuration\n\n### 5.1 Webhook Architecture\n\n```mermaid\nsequenceDiagram\n participant Vendor as External API\n participant Handler as Your Endpoint\n participant Storage as Data Store\n \n Vendor->>Handler: POST /webhook (event payload)\n Handler->>Handler: Verify signature\n Handler->>Handler: Parse event type\n Handler->>Storage: Store/update record\n Handler-->>Vendor: 200 OK\n```\n\n### 5.2 Webhook Security Patterns\n\n| Tool | Security Method | Implementation |\n|------|-----------------|----------------|\n| HubSpot | HMAC-SHA256 | `X-HubSpot-Signature-v3` header |\n| Linear | Signature | `Linear-Signature` header |\n| Slack | Signing Secret | HMAC verification |\n| Jira | URL Secret | Query param `?secret=abc123` |\n| Stripe | Webhook Secret | `Stripe-Signature` header |\n\n### 5.3 HubSpot Webhook Signature Verification\n\n```python\nimport hmac\nimport hashlib\n\ndef verify_hubspot_signature(payload: bytes, signature: str, client_secret: str) -> bool:\n expected = hmac.new(\n client_secret.encode(),\n payload,\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(f\"sha256={expected}\", signature)\n```\n\n资料来源：[skills/hubspot/skill.md:80-95]()\n\n---\n\n## 6. Common Workflows (Recipes)\n\n### 6.1 Cross-Tool Orchestration: Slack → Jira Incident Management\n\nThe playbooks directory contains cross-tool recipes. The Slack-Jira incident playbook demonstrates multi-system integration:\n\n```mermaid\ngraph LR\n A[Slack Alert] --> B[Verify Channel]\n B --> C[Fetch Thread Context]\n C --> D[Get Message Permalink]\n D --> E{Search Existing Jira}\n E -->|Found| F[Link to Existing]\n E -->|Not Found| G[Create Jira Issue]\n G --> H[Post Link in Slack]\n H --> I[Pin Bot Reply]\n```\n\n资料来源：[playbooks/slack-jira-incident.md:1-30]()\n\n### 6.2 Field Mapping\n\n| Slack | Jira |\n|-------|------|\n| Correlation key: `slack:{team_id}:{channel_id}:{ts}` | Stored as label or custom field |\n| Message text | Issue description |\n| Thread replies | Additional context in description |\n| Trigger type | Determines correlation key source |\n\n资料来源：[playbooks/slack-jira-incident.md:45-55]()\n\n### 6.3 Linear Issue Management Recipes\n\n| Recipe | Description |\n|--------|-------------|\n| Create issue | GraphQL mutation with title, description, state |\n| List issues | Paginated query with filtering |\n| Update issue | Mutation targeting specific fields |\n| Post comment | Attach context to existing issues |\n| Create attachment | Link external resources (Sentry, GitHub, Zendesk) |\n| Incremental sync | Filter by `updatedAt` timestamp |\n\n资料来源：[skills/linear/skill.md:90-140]()\n\n---\n\n## 7. Error Handling\n\n### 7.1 Standard Error Response Structure\n\nMost APIs return structured error responses:\n\n```json\n{\n \"error\": \"RATELIMITED\",\n \"message\": \"Rate limit exceeded\",\n \"retryAfter\": 3600\n}\n```\n\n### 7.2 Common Error Codes by Tool\n\n| Code | Meaning | Resolution |\n|------|---------|------------|\n| `429` | Rate limited | Wait and retry with backoff |\n| `401` | Unauthorized | Check/revoke and regenerate token |\n| `403` | Forbidden | Verify scopes and permissions |\n| `404` | Not found | Validate resource ID |\n| `400` | Bad request | Check payload format |\n| `500` | Server error | Retry with idempotency key |\n\n### 7.3 Slack-Specific Errors\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `invalid_channel` | Channel doesn't exist | Verify channel ID |\n| `channel_not_found` | Bot not in channel | Invite bot to channel |\n| `cant_update_message` | Not original poster | Only original bot can update |\n| `missing_thread_ts` | Thread reply without parent | Include `thread_ts` parameter |\n\n资料来源：[skills/slack/skill.md:120-140]()\n\n---\n\n## 8. Development and Contribution\n\n### 8.1 Adding a New Skill\n\nTo contribute a new skill, follow these steps:\n\n```bash\n# 1. Create a branch\ngit checkout -b skill/\n\n# 2. Follow the template structure (11 sections required)\n# 3. Verify all endpoints against official vendor docs\n# 4. Add Last validated: date to doc header\n# 5. Update skills/INDEX.md and README.md\n# 6. Open PR — CI runs npm test\n```\n\n资料来源：[README.md:20-35]()\n\n### 8.2 CI Pipeline\n\nThe repository uses GitHub Actions for continuous integration:\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| `ci.yml` | Push/PR | Build and test |\n| `release.yml` | Manual dispatch | Version bump, tag, npm publish |\n\n### 8.3 Test Suite Requirements\n\nThe test suite validates that every skill:\n\n- [ ] Loads successfully\n- [ ] Has all 11 required sections\n- [ ] Contains a non-empty summary line\n- [ ] Is at least 5KB in size (prevents truncated documentation)\n\n资料来源：[mcp-server/src/index.test.ts:30-50]()\n\n---\n\n## 9. Roadmap and Future Development\n\n### 9.1 Completed Phases\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 | Foundation (Auth + Core CRUD) | ✅ Complete — all 14 tools |\n| Phase 2 | High-Frequency Workflows (6-12 recipes/tool) | ✅ Complete — all 14 tools |\n| Phase 3 | Event-Driven & Real-Time (Webhooks) | ✅ Complete — all 14 tools |\n| Phase 4 | Bulk & Advanced Operations | ⚠️ Partial — documented for most tools |\n\n### 9.2 Upcoming Development\n\n| Priority | Initiative | Description |\n|----------|-------------|-------------|\n| Phase A | Freshness Pipeline | Automated accuracy checks against vendor API changes |\n| Phase 5 | Cross-Tool Orchestration | Dedicated recipes for multi-system workflows |\n| Phase B | SDK Generation | Auto-generate typed clients from skill docs |\n\n资料来源：[skills/ROADMAP.md:25-50]()\n\n---\n\n## 10. Usage with Claude\n\n### 10.1 Installation Options\n\n**Temporary usage:**\n```bash\nnpx -y clawskills-mcp\n```\n\n**Permanent installation:**\n```bash\nnpm install -g clawskills-mcp\n```\n\n### 10.2 Claude Desktop Configuration\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n### 10.3 Usage in Claude Code\n\nReference skills in your project instruction file:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the\ncorresponding skill doc before writing code:\n\n- Monday.com → @skills/monday/skill.md\n- Salesforce → @skills/salesforce/skill.md\n- Jira → @skills/jira/skill.md\n...\n\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\n```\n\n资料来源：[README.md:100-130]()\n\n---\n\n## 11. Best Practices\n\n### 11.1 API Integration Guidelines\n\n1. **Always validate webhook signatures** before processing payloads\n2. **Implement exponential backoff** for rate limit handling\n3. **Use idempotency keys** for create/update operations\n4. **Pin API version headers** where specified (e.g., `Notion-Version: 2025-09-03`)\n5. **Monitor complexity headers** (Linear) to optimize query costs\n\n### 11.2 Debug Logging Standards\n\n| DO Log | DON'T Log |\n|--------|-----------|\n| API method name | Token values |\n| Request/response status | Full message text (may contain PII) |\n| HTTP status codes | File contents |\n| Error codes | Raw credentials |\n\n### 11.3 Security Recommendations\n\n- Use granular scopes instead of deprecated broad permissions (e.g., Figma's `files:read`)\n- Rotate tokens before expiry\n- Store secrets in environment variables, never in code\n- Implement least-privilege access for OAuth scopes\n\n---\n\n## 12. Summary\n\nThe ClawSkills library provides production-ready, standardized documentation for integrating AI assistants with 14 enterprise tools. Its consistent structure, comprehensive coverage of authentication and error handling, and automated validation ensure reliable integrations. The MCP server enables seamless access for Claude and similar AI assistants, while the playbook system supports sophisticated cross-tool workflows.\n\n资料来源：[README.md:1-50]()\n资料来源：[skills/ROADMAP.md:1-30]()\n\n---\n\n\n\n## Skill Document Structure\n\n### 相关页面\n\n相关主题：[Skills Library Overview](#skills-overview), [Contributing Guide](#contributing), [Playbooks Index](#playbooks-index)\n\n\nRelevant Source Files
\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/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/hubspot/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/hubspot/skill.md)\n- [skills/figma/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/figma/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- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n \n\n# Skill Document Structure\n\n## Overview\n\nThe **Skill Document Structure** is the standardized, self-contained Markdown format used to document every tool integration in the `clawskills` repository. Each skill doc captures everything an AI agent needs to reliably call an external API — authentication flows, rate limits, error codes, common recipes, and webhook patterns — without requiring external research. 资料来源：[README.md:1-10]()\n\nThe repository currently covers **14 tools**: Monday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Figma, Slack, Stripe, Notion, and Linear. 资料来源：[README.md:60-61]()\n\nThe skill system serves two primary consumers:\n\n1. **AI agents** (Claude Code, Copilot, LangChain/LlamaIndex RAG pipelines) — query skill docs to write integration code correctly on the first attempt.\n2. **Human developers** — use skill docs as a reference when building or debugging cross-tool workflows.\n\n### Design Principles\n\n| Principle | Implication |\n|-----------|-------------|\n| **Self-contained** | No external links required to make a working API call |\n| **Vendor-verified** | Every endpoint, scope, and rate limit is cross-checked against official docs before publishing |\n| **Version-pinned** | Auth flows and API versions are pinned to specific vendor versions (e.g., Notion `2025-09-03`) |\n| **Machine-readable** | The MCP server parses skill docs at runtime; tools can retrieve arbitrary sections |\n\n---\n\n## Architecture\n\n### Repository Layout\n\n```\nclawskills/\n├── skills/\n│ ├── INDEX.md # Master list of all skills\n│ ├── ROADMAP.md # Governance and update cadence\n│ ├── monday/skill.md\n│ ├── salesforce/skill.md\n│ ├── jira/skill.md\n│ ├── hubspot/skill.md\n│ └── ... (14 tools total)\n├── playbooks/ # Cross-tool orchestration recipes\n├── mcp-server/ # Model Context Protocol server\n│ ├── src/index.test.ts # Skill validation tests\n│ └── README.md # MCP tool interface\n└── README.md\n```\n\n### How Skills Flow into the MCP Server\n\nThe MCP server exposes three tools — `get_skill`, `search_skills`, and `list_skills` — that load and parse skill documents at runtime. This means skill docs are not compiled into the binary; the server reads the Markdown files directly from `skills/` on each invocation. 资料来源：[mcp-server/README.md:1-20]()\n\n```mermaid\ngraph TD\n A[AI Agent Request] --> B[MCP Server Tool Call]\n B --> C{Which tool?}\n C -->|list_skills| D[Enumerate all skill.md files]\n C -->|get_skill| E[Load specific skill.md + section]\n C -->|search_skills| F[Full-text search across all skill.md]\n E --> G[Extract requested section]\n F --> H[Return ±3 line excerpts, max 5 per skill]\n D --> I[skills/INDEX.md]\n I --> J[AI Agent receives skill content]\n G --> J\n H --> J\n J --> K[Agent writes / executes integration code]\n```\n\n---\n\n## Required Sections\n\nEvery skill file must contain **all 11 required sections** in order. The CI pipeline runs `npm test` which validates this via `REQUIRED_SECTIONS`. Skills that fail validation cannot be merged. 资料来源：[mcp-server/src/index.test.ts:1-45]()\n\nAdditionally, every skill must be **at least 5 KB** to discourage placeholder content, and must contain a **non-empty summary line** (the first line after the YAML frontmatter). 资料来源：[mcp-server/src/index.test.ts:30-38]()\n\n### Section Reference\n\n| # | Section Name | Purpose | Key Content |\n|---|-------------|---------|-------------|\n| 1 | **Overview** | What the tool does and why it matters | High-level description, key capabilities |\n| 2 | **Authentication & Permissions** | How to authenticate and which scopes are needed | PAT setup, OAuth flows, scope tables |\n| 3 | **Base URLs & API Versions** | Endpoint root and versioning strategy | `https://api.example.com/v1`, header pinning |\n| 4 | **Rate Limits** | Request quotas, complexity caps, headers | Tables with limits per auth type, response headers |\n| 5 | **Retry & Idempotency** | How to handle transient failures safely | Exponential backoff, idempotency key usage |\n| 6 | **Common Workflows (Recipes)** | Step-by-step patterns for high-frequency tasks | 6–12 recipes per tool with code examples |\n| 7 | **Error Codes** | What errors mean and how to handle them | Status codes, error response shapes, gotchas |\n| 8 | **Webhook Setup** | How to register, verify, and handle webhooks | Registration endpoint, signature verification, event types |\n| 9 | **Data Models / Fields** | Table reference and record structure | Table names, field names, sys_id patterns |\n| 10 | **Pagination** | How to traverse large result sets | Cursor-based, offset-based, complexity-based |\n| 11 | **Sources** | Links to official vendor documentation | Verified links only; no unverified claims |\n\n### Section Naming Convention\n\nThe MCP server resolves sections by name prefix, so `auth`, `rate-limits`, `recipes`, `gotchas`, `webhooks`, `overview`, and `fields` can be requested independently of the full document. 资料来源：[mcp-server/README.md:1-20]()\n\n```mermaid\ngraph LR\n A[get_skill tool] --> B[\"section: 'auth'\"]\n B --> C[Extract markdown between
'## Authentication' and next '##']\n A --> D[\"section: 'rate-limits'\"]\n D --> E[Extract markdown between
'## Rate Limits' and next '##']\n A --> F[\"section: 'recipes'\"]\n F --> G[Extract all ### Recipe headings]\n C --> H[Return as JSON string]\n E --> H\n G --> H\n```\n\n---\n\n## Authentication Patterns\n\nEach skill documents the full authentication surface. The two dominant patterns are:\n\n### Pattern 1 — Personal Access Token (PAT)\n\nUsed for server-to-server integrations. The token is passed via a vendor-specific header.\n\n```bash\n# Figma\ncurl https://api.figma.com/v1/me \\\n -H \"X-Figma-Token: YOUR_PAT\"\n\n# Jira (Basic Auth with API token)\ncurl \"$BASE/rest/api/3/myself\" \\\n -H \"Authorization: Basic $(echo -n 'user@example.com:API_TOKEN' | base64)\"\n```\n\nPATs are recommended for server-side use because they avoid the OAuth redirect flow complexity. 资料来源：[skills/figma/skill.md:1-20]()\n\n### Pattern 2 — OAuth 2.0\n\nUsed for user-facing applications where the app acts on behalf of a user.\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant A as Your App\n participant V as Vendor API\n U->>A: Initiate login\n A->>V: Redirect to /oauth?client_id=...&scope=...&state=...\n V->>U: Auth prompt\n U->>V: Grant access\n V->>A: Redirect with ?code=AUTH_CODE\n A->>V: POST /oauth/token, code + client_secret\n V->>A: {access_token, refresh_token, expires_in}\n A->>V: Authorization: Bearer \n V->>A: API response\n```\n\nFor Linear specifically, access tokens expire in 24 hours (post-October 2025 apps), and refresh token rotation is required by April 1, 2026. 资料来源：[skills/linear/skill.md:1-30]()\n\n---\n\n## Rate Limit Documentation\n\nRate limits are documented per skill as tables showing the limit by auth type. Each skill also specifies which response headers to inspect.\n\n### Rate Limit Table Template\n\n| Auth type | Requests / hr | Additional constraints |\n|-----------|-------------|----------------------|\n| API key | X | — |\n| OAuth app | Y | — |\n| Unauthenticated | Z | — |\n\n### Linear-Specific Complexity Model\n\nLinear uses a **complexity-based** rate limiting system rather than simple request counts. The system assigns complexity points to queries based on field depth and nesting. 资料来源：[skills/linear/skill.md:1-20]()\n\n| Header | Description |\n|--------|-------------|\n| `X-RateLimit-Requests-Limit` | Total allowed requests in window |\n| `X-RateLimit-Requests-Remaining` | Requests left in current window |\n| `X-RateLimit-Requests-Reset` | Unix timestamp when window resets |\n| `X-Complexity` | Complexity cost of the last query (Linear) |\n\n---\n\n## Recipe Structure\n\nEach skill contains **6–12 recipes** — complete, runnable code patterns for the most common API operations. Recipes follow a consistent structure:\n\n### Recipe Anatomy\n\n```\n### Recipe N — [Short Action Description]\n\n[Brief problem statement]\n\n// Optional: prerequisites or context\n\n\n\n// Optional: result interpretation\n```\n\n### Recipe Categories by Skill\n\n| Skill | Recipe Highlights |\n|-------|-------------------|\n| **Jira** | Create issue, search with JQL, update issue, add comment, register webhook, manage labels |\n| **Figma** | Read file node tree, export assets, list team projects, manage variables, create dev resources, webhook pipeline |\n| **Linear** | Create issue, search issues, update state, post comment, create attachment, incremental sync |\n| **Notion** | Create page, query database, update properties, list users, retrieve page, filter/query patterns |\n| **HubSpot** | CRUD contacts, CRUD deals, search with filters, register webhook, import CSV bulk |\n| **ServiceNow** | Create incident, read/write records, update state, query CMDB |\n\n```mermaid\ngraph TD\n A[Write Integration Code] --> B{Do I have a relevant skill doc?}\n B -->|No| C[Research vendor docs manually]\n B -->|Yes| D[Load skill doc]\n D --> E[Check auth section for token type]\n E --> F[Pick matching recipe]\n F --> G{Rate limit exceeded?}\n G -->|Yes| H[Wait for Retry-After, then retry]\n G -->|No| I[Execute API call]\n I --> J{Webhook needed?}\n J -->|Yes| K[Register webhook + verify signature]\n J -->|No| L[Done]\n C --> L\n K --> L\n```\n\n---\n\n## Error Code Documentation\n\nEach skill documents the vendor's error response shapes and maps HTTP status codes to action.\n\n### Common Error Patterns\n\n| Error | Likely Cause | Resolution |\n|-------|-------------|-----------|\n| `401 Unauthorized` | Token expired or missing | Refresh token or re-authenticate |\n| `403 Forbidden` | Missing scope | Re-authorize with additional scopes |\n| `429 Too Many Requests` | Rate limit hit | Respect `Retry-After` header |\n| `500 Internal Server Error` | Vendor-side issue | Retry with exponential backoff |\n| `400 Bad Request` | Malformed request body | Validate schema against recipe |\n\n### Skill-Specific Gotchas\n\n**Figma gotchas** include: `files:read` is deprecated and replaced with granular scopes; rate limits now vary by plan and seat type as of November 2025. 资料来源：[skills/figma/skill.md:1-10]()\n\n**Slack gotchas** include: `mrkdwn` format required (not standard Markdown), Events API URL verification must return JSON within 3 seconds, and `files.upload` is deprecated in favor of `files.getUploadURLExternal`. 资料来源：[skills/slack/skill.md:1-20]()\n\n**ServiceNow gotchas** include: the 32-character `sys_id` is the true primary key (not the human-readable `number` field), and work notes vs. comments have distinct access controls. 资料来源：[skills/servicenow/skill.md:1-20]()\n\n---\n\n## Webhook Documentation\n\nSkills that support event-driven patterns include webhook setup sections covering registration, payload shapes, and signature verification.\n\n### Webhook Registration Pattern\n\n```bash\ncurl -s -X POST \"$BASE/rest/api/3/webhook\" \\\n -H \"Authorization: $AUTH\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"My Webhook\",\n \"url\": \"https://myapp.com/webhook\",\n \"events\": [\"jira:issue_created\", \"jira:issue_updated\"],\n \"filters\": { \"issue-related-events-section\": \"project = PROJ\" }\n }'\n```\n\n### Signature Verification Pattern\n\nHubSpot uses HMAC-SHA256 verification:\n\n```python\nimport hmac, hashlib\n\ndef verify_hubspot_signature(\n client_secret: str,\n method: str,\n url: str,\n body: str,\n timestamp: str,\n signature: str,\n) -> bool:\n signed_payload = f\"{client_secret}{method}{url}{body}{timestamp}\"\n expected = hmac.new(\n client_secret.encode(),\n signed_payload.encode(),\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(expected, signature)\n```\n\nHubSpot validates webhook signatures using `X-HubSpot-Signature-v3`. Jira webhooks do not send signatures by default and require a secret token in the URL path. 资料来源：[skills/hubspot/skill.md:1-20]()\n\n---\n\n## Pagination Patterns\n\nThree pagination models appear across the skill library:\n\n| Model | Tool | Mechanism |\n|-------|------|-----------|\n| **Offset-based** | ServiceNow, Notion | `sysparm_offset`, `start_cursor` |\n| **Cursor-based** | Jira, HubSpot, GitHub | `pageToken`, `nextCursor`, `pageInfo` |\n| **Complexity-based** | Linear | `after`, `first`, monitors `X-Complexity` header |\n\n```mermaid\ngraph LR\n A[Query with first=N] --> B{More pages?}\n B -->|Yes| C[Read endCursor / pageInfo]\n C --> D[Query with after=]\n D --> B\n B -->|No| E[Process all results]\n```\n\nFor Linear, requesting fewer fields reduces complexity cost — deeply nested queries (e.g., `issue.project.lead.assignedIssues`) should be avoided unless necessary. 资料来源：[skills/linear/skill.md:1-20]()\n\n---\n\n## Validation and Governance\n\n### CI Pipeline\n\nEvery pull request triggers `npm test` which runs three validation checks on all skill files: 资料来源：[README.md:1-20]()\n\n| Check | Rule | Enforced |\n|-------|------|---------|\n| **All 11 sections present** | Every skill has each required section | ✅ |\n| **Non-empty summary** | First line after frontmatter is not blank | ✅ |\n| **Minimum size** | File length ≥ 5,000 bytes | ✅ |\n\n### Contribution Process\n\nTo add or update a skill: 资料来源：[README.md:1-20]()\n\n1. Create a branch: `git checkout -b skill/`\n2. Follow the template structure in any existing skill.md — all 11 sections required\n3. Verify all endpoints, rate limits, and auth flows against official vendor docs before committing\n4. Add a `Last validated:` date to the doc header\n5. Update `skills/INDEX.md` and `README.md` when adding a new tool\n6. Link to official sources in the `## Sources` section — no unverified claims\n7. Open a PR — CI validates the skill\n\n### Release Automation\n\nReleases are automated via GitHub Actions. Merge to `main`, then go to **Actions → Release → Run workflow** and select `patch / minor / major`. 资料来源：[README.md:1-20]()\n\n---\n\n## Development Roadmap\n\nThe skill library was built in five phases: 资料来源：[skills/ROADMAP.md:1-20]()\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 | Foundation (Auth + Core CRUD) | ✅ Complete — all 14 tools |\n| Phase 2 | High-Frequency Workflows (6–12 recipes per tool) | ✅ Complete — all 14 tools |\n| Phase 3 | Event-Driven & Real-Time (webhooks, signature verification) | ✅ Complete — all 14 tools |\n| Phase 4 | Bulk & Advanced Operations | ⚠️ Partial — documented for most tools |\n| Phase 5 | Cross-Tool Orchestration | ❌ Not started |\n\nThe next priority is a **freshness and accuracy pipeline** to keep skill docs in sync as vendor APIs evolve. 资料来源：[skills/ROADMAP.md:1-20]()\n\n---\n\n## Using Skills with AI Agents\n\n### Claude Code Project Instruction\n\nAdd skill references to `.claude/CLAUDE.md` so the agent always has context:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the\ncorresponding skill doc before writing code:\n\n- Jira → @skills/jira/skill.md\n- HubSpot → @skills/hubspot/skill.md\n- Linear → @skills/linear/skill.md\n- Notion → @skills/notion/skill.md\n- Slack → @skills/slack/skill.md\n\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\nAlways pin API version headers where specified.\n```\n\n### LangChain RAG Pipeline\n\n```python\nfrom langchain_community.document_loaders import DirectoryLoader\nfrom langchain.text_splitter import MarkdownHeaderTextSplitter\nfrom langchain_openai import OpenAIEmbeddings\nfrom langchain_community.vectorstores import Chroma\n\nloader = DirectoryLoader(\"skills/\", glob=\"**/*.md\")\ndocs = loader.load()\n\nsplitter = MarkdownHeaderTextSplitter(\n headers_to_split_on=[(\"##\", \"section\"), (\"###\", \"subsection\")]\n)\nchunks = []\nfor doc in docs:\n chunks.extend(splitter.split_text(doc.page_content))\n\nvectorstore = Chroma.from_documents(\n chunks,\n embedding=OpenAIEmbeddings(),\n persist_directory=\"./chroma_db\"\n)\n```\n\nSkill docs split cleanly at `##` and `###` boundaries because the document structure is intentionally designed for RAG chunking — each section is self-contained and meaningful in isolation. 资料来源：[README.md:1-20]()\n\n---\n\n## Quick Reference\n\n- **Repository**: https://github.com/Shanksg/clawskills\n- **MCP Server**: `npx -y clawskills-mcp`\n- **Skills directory**: `skills/` (14 tool-specific `.md` files)\n- **Required sections**: 11 per skill\n- **Minimum size**: 5 KB per skill\n- **CI command**: `npm test`\n\n---\n\n\n\n## Playbooks Index\n\n### 相关页面\n\n相关主题：[Skills Library Overview](#skills-overview), [Skill Document Structure](#skill-structure), [AI Tool Integration Guide](#ai-integration)\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- [mcp-server/src/index.test.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n \n\n# Playbooks Index\n\n## Overview\n\nPlaybooks in ClawSkills are comprehensive, multi-step workflow guides that orchestrate integrations across two or more tools. Unlike individual skill documents that focus on single-tool API capabilities, playbooks provide end-to-end automation patterns for common cross-system business scenarios.\n\nThe Playbooks Index serves as the central directory and documentation hub for all available cross-tool workflows, enabling AI assistants and developers to implement sophisticated integrations without requiring deep expertise in each underlying API.\n\n## Architecture\n\n### Relationship Between Components\n\n```mermaid\ngraph TD\n subgraph \"ClawSkills Core\"\n A[Skills Index] --> B[Individual Skill Docs]\n C[Playbooks Index] --> D[Cross-Tool Playbooks]\n end\n \n subgraph \"MCP Server\"\n E[get_skill] --> B\n F[get_playbook] --> D\n G[list_playbooks] --> C\n end\n \n H[AI Assistant] --> E\n H --> F\n H --> G\n```\n\n### Playbook Structure Pattern\n\nEach playbook follows a standardized template containing:\n\n| Section | Purpose |\n|---------|---------|\n| **Trigger** | Event or condition that initiates the workflow |\n| **Prerequisites** | Required configurations, tokens, and permissions |\n| **Step-by-Step Flow** | Sequential actions with exact API calls |\n| **Field Mapping** | Data transformations between systems |\n| **Error Handling** | Retry logic and failure recovery |\n| **Testing Verification** | Validation checklist items |\n\n## Available Playbooks\n\n### 1. Zendesk → Jira Bug Escalation\n\n**Slug:** `zendesk-jira-bug-escalation`\n\n**Purpose:** Automatically creates a Jira bug issue when a Zendesk ticket meets escalation criteria.\n\n**Trigger Conditions:**\n- Ticket status changes to `solved` with low satisfaction score\n- Specific tag patterns (e.g., `bug`, `escalate`)\n- Agent-assigned priority flag\n\n**Key Features:**\n- Bidirectional comment mirroring\n- Attachment transfer from Zendesk to Jira\n- Correlation key generation for idempotent handling\n- Custom field mapping for project/issuetype selection\n\n资料来源：[playbooks/zendesk-jira-bug-escalation.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/zendesk-jira-bug-escalation.md)\n\n### 2. HubSpot → Asana Onboarding\n\n**Slug:** `hubspot-asana-onboarding`\n\n**Purpose:** Creates a structured onboarding task hierarchy in Asana when a new contact is added to a HubSpot list.\n\n**Workflow:**\n1. Detect new contact in target HubSpot list\n2. Create parent Onboarding Project in Asana\n3. Generate task checklist based on onboarding template\n4. Assign tasks to team members via Asana sections\n5. Post initial status update to Slack (if configured)\n\n**Task Template Structure:**\n```mermaid\ngraph LR\n A[New Contact] --> B[Create Project]\n B --> C[Kickoff Meeting]\n B --> D[Setup Tasks]\n B --> E[Training Tasks]\n C --> F[Send Welcome Email]\n D --> G[Create Accounts]\n D --> H[Configure Access]\n E --> I[Training Scheduled]\n E --> J[Materials Sent]\n```\n\n资料来源：[playbooks/hubspot-asana-onboarding.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/hubspot-asana-onboarding.md)\n\n### 3. Salesforce → HubSpot Lead Sync\n\n**Slug:** `salesforce-hubspot-lead-sync`\n\n**Purpose:** Bidirectional synchronization of lead data between Salesforce CRM and HubSpot Marketing Platform.\n\n**Sync Directions:**\n- **Lead Creation:** Salesforce → HubSpot (when Lead status = \"Open\")\n- **Status Updates:** HubSpot → Salesforce (when Contact lifecycle stage changes)\n- **Deal Association:** Bidirectional (deal closed in either system updates the other)\n\n**Field Mapping:**\n\n| Salesforce Field | HubSpot Property | Transform Logic |\n|------------------|------------------|-----------------|\n| `Email` | `email` | Direct copy |\n| `LeadSource` | `hs_lead_source` | Direct copy |\n| `AnnualRevenue` | `annualrevenue` | Numeric normalization |\n| `Industry` | `industry` | Picklist value mapping |\n| `CreatedDate` | `createdate` | ISO 8601 timestamp conversion |\n\n资料来源：[playbooks/salesforce-hubspot-lead-sync.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/salesforce-hubspot-lead-sync.md)\n\n### 4. Slack → Jira Incident Management\n\n**Slug:** `slack-jira-incident`\n\n**Purpose:** Streamlined incident creation and tracking using Slack as the front-end interface and Jira as the backend issue tracker.\n\n**Trigger Events:**\n- `reaction_added` emoji on flagged messages\n- `/incident` slash command invocation\n- Specific channel message patterns (configurable)\n\n**Workflow Sequence:**\n\n```mermaid\nsequenceDiagram\n participant S as Slack User\n participant SL as Slack API\n participant BM as Bot/Server\n participant J as Jira Cloud\n \n S->>SL: Adds 🚨 reaction\n SL->>BM: reaction_added event\n BM->>SL: getPermalink()\n BM->>J: Search existing issue\n alt No existing issue\n BM->>J: Create incident issue\n BM->>SL: Post issue link to thread\n else Existing issue found\n BM->>SL: Post existing link\n end\n```\n\n**Correlation Key Format:** `slack:{team_id}:{channel_id}:{ts}`\n\n资料来源：[playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n\n## MCP Server Integration\n\nThe ClawSkills MCP server exposes playbook operations through three primary tools:\n\n### Tool Definitions\n\n| Tool | Arguments | Returns |\n|------|-----------|---------|\n| `list_playbooks` | None | Array of all playbook names and slugs |\n| `get_playbook` | `name` (string) | Full playbook content by slug |\n| `search_playbooks` | `query` (string) | Matching excerpts with context (±3 lines) |\n\n### Usage Example\n\n```typescript\n// List all available playbooks\nconst playbooks = await client.list_playbooks({});\n// Returns: [\"hubspot-asana-onboarding\", \"salesforce-hubspot-lead-sync\", \"zendesk-jira-bug-escalation\", \"slack-jira-incident\"]\n\n// Fetch specific playbook\nconst playbook = await client.get_playbook({\n name: \"slack-jira-incident\"\n});\n\n// Search for specific patterns\nconst results = await client.search_playbooks({\n query: \"idempotency\"\n});\n```\n\n### Search Behavior\n\n- Full-text search across all playbook content\n- Returns up to 5 matches per playbook\n- Includes ±3 lines of context around each match\n- Supports queries like `\"idempotency\"`, `\"rollback\"`, `\"closed won\"`\n\n资料来源：[mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n\n## Test Coverage\n\nThe Playbooks system is validated through automated tests:\n\n```typescript\ndescribe(\"real playbooks\", () => {\n let playbooks: Map;\n\n beforeAll(() => {\n playbooks = loadPlaybooks(REAL_PLAYBOOKS_DIR);\n });\n\n it(\"loads all expected playbooks\", () => {\n const knownPlaybooks = [\n \"hubspot-asana-onboarding\",\n \"salesforce-hubspot-lead-sync\",\n \"zendesk-jira-bug-escalation\",\n ];\n // Verification logic\n });\n\n it(\"every playbook has a non-empty summary line\", () => {\n for (const [slug, content] of playbooks.entries()) {\n const summary = skillSummary(content);\n expect(summary, `${slug}: empty summary`).not.toBe(\"\");\n }\n });\n});\n```\n\n**Validation Requirements:**\n- All expected playbooks must load successfully\n- Each playbook must contain a non-empty summary line\n- Minimum file size threshold (5000 bytes) prevents truncated documentation\n\n资料来源：[mcp-server/src/index.test.ts:1-50](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.test.ts)\n\n## Roadmap and Future Development\n\n### Phase 5 — Cross-Tool Orchestration (In Progress)\n\nThe Playbooks system represents the culmination of the ClawSkills documentation strategy:\n\n| Phase | Status | Coverage |\n|-------|--------|----------|\n| Phase 1 — Foundation | ✅ Complete | Auth flows, basic CRUD |\n| Phase 2 — High-Frequency Workflows | ✅ Complete | 6–12 recipes per tool |\n| Phase 3 — Event-Driven & Real-Time | ✅ Complete | Webhook setup, signatures |\n| Phase 4 — Bulk & Advanced Operations | ⚠️ Partial | Most tools documented |\n| Phase 5 — Cross-Tool Orchestration | ❌ Not Started | Patterns in INDEX, no recipes |\n\n资料来源：[skills/ROADMAP.md](https://github.com/Shanksg/clawskills/blob/main/skills/ROADMAP.md)\n\n## Adding New Playbooks\n\nTo contribute a new playbook:\n\n1. Create a branch: `git checkout -b playbook/`\n2. Follow the playbook template structure\n3. Include all required sections (trigger, flow, mapping, error handling)\n4. Update `playbooks/INDEX.md` with the new entry\n5. Open a PR — CI validates playbook loads and has required sections\n\n**Playbook Naming Convention:**\n- Filename: `--.md`\n- Slug: Same as filename without extension\n- Frontmatter: Include `title`, `description`, and `tools` array\n\n---\n\n\n\n## MCP Server Architecture\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools), [Installation Guide](#installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n- [mcp-server/package.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/package.json)\n- [mcp-server/tsconfig.json](https://github.com/Shanksg/clawskills/blob/main/mcp-server/tsconfig.json)\n- [mcp-server/vitest.config.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/vitest.config.ts)\n- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n \n\n# MCP Server Architecture\n\n## Overview\n\nThe **clawskills-mcp** is a Model Context Protocol (MCP) server that exposes the ClawSkills API integration documentation to AI agents. It provides a bridge between AI assistants (such as Claude) and the structured skill documentation for 14 different API integrations.\n\n资料来源：[mcp-server/README.md]()\n\n### Core Purpose\n\nThe server serves as an interface layer that allows AI agents to query, search, and retrieve API integration knowledge without requiring manual documentation lookup. This enables AI-assisted coding tasks to incorporate accurate API specifications, authentication patterns, and workflow recipes on demand.\n\n```mermaid\ngraph TD\n A[AI Agent] -->|MCP Protocol| B[clawskills-mcp Server]\n B -->|list_skills| C[Skill Index]\n B -->|get_skill| C\n B -->|search_skills| D[Full-text Search]\n B -->|list_playbooks| E[Cross-Tool Playbooks]\n C -->|Returns| A\n D -->|Returns| A\n E -->|Returns| A\n \n F[skills/\\*.md] --> C\n G[playbooks/\\*.md] --> E\n```\n\n资料来源：[README.md:50-80]()\n\n## Architecture Components\n\n### Component Overview\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| MCP Server | Protocol bridge for AI agent communication | `mcp-server/src/index.ts` |\n| Skill Docs | 14 structured Markdown integration guides | `skills/*/skill.md` |\n| Playbooks | Cross-tool workflow documentation | `playbooks/*.md` |\n| Index | Master listing of all available skills | `skills/INDEX.md` |\n| CLI Tools | Build, test, and release automation | `mcp-server/package.json` |\n\n### Directory Structure\n\n```\nclawskills/\n├── mcp-server/\n│ ├── src/\n│ │ └── index.ts # Main MCP server implementation\n│ ├── package.json # Dependencies and scripts\n│ ├── tsconfig.json # TypeScript configuration\n│ ├── vitest.config.ts # Test configuration\n│ ├── Dockerfile # Container deployment\n│ └── README.md # Server-specific documentation\n├── skills/\n│ ├── INDEX.md # Master skill index\n│ ├── jira/skill.md\n│ ├── slack/skill.md\n│ ├── figma/skill.md\n│ ├── notion/skill.md\n│ ├── linear/skill.md\n│ └── ... (9 more skills)\n├── playbooks/\n│ ├── slack-jira-incident.md\n│ └── ... (additional workflows)\n└── README.md # Main project documentation\n```\n\n资料来源：[mcp-server/README.md:1-10]()\n\n## MCP Tools Interface\n\nThe server exposes four primary tools that AI agents can invoke:\n\n### Tool Specifications\n\n| Tool | Description | Parameters | Return Type |\n|------|-------------|------------|-------------|\n| `list_skills` | List all available skill documentation | None | Array of skill slugs with descriptions |\n| `get_skill` | Fetch full skill doc or specific section | `slug`, `section?` | Markdown content |\n| `search_skills` | Full-text search across all skills | `query` | Matching results with context |\n| `list_playbooks` | List available cross-tool workflows | None | Array of playbook names |\n\n### Parameter Details\n\n#### `get_skill` Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `slug` | string | Yes | Skill identifier (e.g., `jira`, `slack`, `figma`) |\n| `section` | string | No | Specific section name (`auth`, `rate-limits`, `recipes`, `errors`, etc.) |\n\n#### `search_skills` Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `query` | string | Yes | Search term to match across all skill documentation |\n\n资料来源：[README.md:60-75]()\n\n## Deployment Models\n\n### npx (Recommended for Claude Desktop/Code)\n\nNo installation required. The server is fetched and executed on demand.\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n**Configuration File Locations:**\n\n| Platform | Path |\n|----------|------|\n| macOS (Claude Desktop) | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows (Claude Desktop) | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Claude Code (Project) | `.claude/settings.json` |\n| Claude Code (Global) | `~/.claude/settings.json` |\n\n资料来源：[mcp-server/README.md:20-40]()\n\n### Docker Deployment\n\nFor server-side or containerized environments:\n\n```bash\n# Build the image\ndocker build -t clawskills-mcp -f mcp-server/Dockerfile .\n\n# Run the container\ndocker run --rm -i clawskills-mcp\n```\n\n资料来源：[mcp-server/README.md:50-55]()\n\n## Content Repository\n\n### Skill Documentation Structure\n\nEach skill follows a standardized 11-section template:\n\n1. **Overview** — Tool description and key capabilities\n2. **Authentication & permissions** — Auth flows, token management, scopes\n3. **Base URL & versioning** — API endpoint structure\n4. **Rate limits** — Request quotas and throttling patterns\n5. **Common workflows (recipes)** — Code examples for typical operations\n6. **Error codes** — Error handling patterns\n7. **Webhooks** — Event-driven integration patterns\n8. **Pagination** — Large dataset retrieval\n9. **Filtering & sorting** — Query parameter conventions\n10. **Sources** — Official documentation links\n11. **Testing checklist** — Verification procedures\n\n### Supported Integrations\n\n| Skill | Category | Key Capabilities |\n|-------|----------|------------------|\n| Jira | Project Management | Issue CRUD, comments, attachments, webhooks |\n| Slack | Communication | Messaging, threads, files, reactions |\n| Figma | Design | File access, comments, variables, exports |\n| Notion | Documentation | Pages, databases, blocks, search |\n| Linear | Issue Tracking | GraphQL API, issues, projects, labels |\n| Monday.com | Project Management | Boards, items, updates, workdocs |\n| Salesforce | CRM | Objects, queries, records |\n| HubSpot | Marketing | Contacts, deals, pipelines |\n| ServiceNow | ITSM | Incident, change, problem management |\n| Dynamics 365 | Enterprise | Business central, customer engagement |\n| GitHub | Development | Repos, issues, PRs, actions |\n| Stripe | Payments | Charges, subscriptions, webhooks |\n| Asana | Task Management | Projects, tasks, subtasks, teams |\n| Zendesk | Support | Tickets, users, satisfaction |\n\n资料来源：[README.md:30-45]()\n\n## Build and Development\n\n### TypeScript Configuration\n\nThe server is implemented in TypeScript for type safety:\n\n```json\n{\n \"compilerOptions\": {\n \"target\": \"ES2020\",\n \"module\": \"commonjs\",\n \"lib\": [\"ES2020\"],\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"outDir\": \"./dist\",\n \"rootDir\": \"./src\"\n },\n \"include\": [\"src/**/*\"],\n \"exclude\": [\"node_modules\", \"dist\"]\n}\n```\n\n资料来源：[mcp-server/tsconfig.json]()\n\n### Testing Infrastructure\n\nThe project uses Vitest for unit testing and validation:\n\n```typescript\n// vitest.config.ts structure\n{\n test: {\n environment: \"node\",\n include: [\"**/*.test.ts\"],\n coverage: {\n provider: \"v8\",\n reporter: [\"text\", \"json\", \"html\"]\n }\n }\n}\n```\n\n资料来源：[mcp-server/vitest.config.ts]()\n\n### CI/CD Pipeline\n\nThe project includes automated workflows:\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| `ci.yml` | Every push/PR | Build + test on every change |\n| `release.yml` | Manual dispatch | Version bump, git tag, npm publish |\n\n**Release Process:**\n\n1. Merge changes to `main` branch\n2. Navigate to GitHub Actions → **Release**\n3. Run workflow with desired version bump (`patch`, `minor`, `major`)\n4. Server automatically publishes via OIDC authentication\n\n资料来源：[skills/ROADMAP.md:60-70]()\n\n## Data Flow\n\n### Query Execution Flow\n\n```mermaid\nsequenceDiagram\n participant AI as AI Agent\n participant MCP as MCP Server\n participant FS as File System\n participant MD as Markdown Files\n \n AI->>MCP: list_skills()\n MCP->>FS: Read INDEX.md\n FS-->>MCP: Return skill list\n MCP-->>AI: Skill slugs with descriptions\n \n AI->>MCP: get_skill(\"jira\", \"auth\")\n MCP->>FS: Read skills/jira/skill.md\n FS-->>MCP: Return markdown content\n MCP-->>AI: Authentication section content\n \n AI->>MCP: search_skills(\"webhook\")\n MCP->>FS: Search all *.md files\n FS-->>MCP: Matching results\n MCP-->>AI: Search results with context\n```\n\n### Content Resolution\n\n| Tool | Content Source | Processing |\n|------|----------------|------------|\n| `list_skills` | `skills/INDEX.md` | Parse YAML/JSON index |\n| `get_skill` | `skills/{slug}/skill.md` | Extract full doc or section |\n| `search_skills` | All `skills/` and `playbooks/` | Full-text pattern match |\n| `list_playbooks` | `playbooks/` directory | Enumerate workflow files |\n\n## Version Management\n\n### Semantic Versioning\n\nThe MCP server maintains its own npm version separate from the skill documentation:\n\n| Version Type | Increment | Example |\n|--------------|-----------|---------|\n| Major | Breaking changes | 1.0.0 → 2.0.0 |\n| Minor | New features | 1.0.0 → 1.1.0 |\n| Patch | Bug fixes | 1.0.0 → 1.0.1 |\n\n### Documentation Versioning\n\nIndividual skill docs track their own API version and `Last validated` date:\n\n```yaml\n---\ntitle: Jira Integration\napi_version: \"3.0\"\nlast_validated: 2025-01-15\n---\n```\n\nThis ensures API changes are reflected at the skill level without requiring full server releases.\n\n资料来源：[skills/ROADMAP.md:50-65]()\n\n## Integration Patterns\n\n### With Claude (claude.ai or Claude Code)\n\n#### Option 1: Reference Specific Section\n\nPaste a skill section directly into conversation:\n\n```\n[paste the \"Authentication & permissions\" section from skills/salesforce/skill.md]\n\nUsing the above, write a Python function that exchanges a JWT for an access token\nand caches it until 5 minutes before expiry.\n```\n\n#### Option 2: Project Instruction File\n\nAdd to `.claude/CLAUDE.md` for persistent context:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the\ncorresponding skill doc before writing code:\n\n- Jira → @skills/jira/skill.md\n- Slack → @skills/slack/skill.md\n- Figma → @skills/figma/skill.md\n\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\n```\n\n资料来源：[README.md:90-120]()\n\n## Security Considerations\n\n### Token Handling\n\n| Context | Token Type | Recommendation |\n|---------|------------|----------------|\n| Development | Personal Access Token | Use environment variables, never commit |\n| Production | OAuth tokens | Implement secure storage with rotation |\n| Webhooks | Shared secrets | Verify signatures in all handlers |\n\n### Permission Model\n\n- **Least privilege**: Request only required scopes\n- **Token storage**: Never log token values\n- **Webhook verification**: Always validate signatures\n\n资料来源：[skills/slack/skill.md:80-95]()\n\n## Maintenance and Updates\n\n### Skill Documentation Updates\n\n1. Create feature branch: `git checkout -b skill/`\n2. Follow the 11-section template structure\n3. Verify all endpoints against official vendor docs\n4. Add `Last validated:` date to doc header\n5. Update `skills/INDEX.md` and `README.md`\n6. Open PR — CI validates skill loads and has all sections\n\n### Content Freshness Pipeline\n\n| Priority | Initiative | Status |\n|----------|------------|--------|\n| Phase A | Automated validation and alerting | Planned |\n| Phase B | Vendor API change monitoring | Planned |\n| Phase C | Community contribution workflow | Planned |\n\n资料来源：[skills/ROADMAP.md:75-90]()\n\n## Related Documentation\n\n- [ClawSkills Main README](../README.md) — Project overview and quick start\n- [Skills Index](../skills/INDEX.md) — Complete listing of all skill documentation\n- [Release Workflow](../.github/workflows/release.yml) — Automated release process\n- [CI Pipeline](../.github/workflows/ci.yml) — Continuous integration configuration\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[MCP Server Architecture](#mcp-server-architecture), [Quick Start Guide](#quick-start), [AI Tool Integration Guide](#ai-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n- [mcp-server/README.md](https://github.com/Shanksg/clawskills/blob/main/mcp-server/README.md)\n- [README.md](https://github.com/Shanksg/clawskills/blob/main/README.md)\n \n\n# MCP Tools Reference\n\n## Overview\n\nThe **clawskills-mcp** is a Model Context Protocol (MCP) server that provides AI assistants (specifically Claude) access to the ClawSkills library of integration skill documentation. This server acts as a bridge between AI coding assistants and the comprehensive API documentation for 14+ third-party tools including Jira, GitHub, Salesforce, Linear, and others.\n\nThe MCP server exposes three primary tools that enable AI assistants to query, retrieve, and search through skill documentation in real-time, allowing them to write accurate integration code without requiring manual lookup of API documentation.\n\n**资料来源：** [README.md:1]()\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[Claude AI Assistant] -->|MCP Protocol| B[clawskills-mcp Server]\n B --> C[Skill Documentation Files]\n B --> D[Index Registry]\n C --> E[skills/*.md]\n F[Claude Desktop/Claude Code] --> A\n G[Claude API App] --> A\n```\n\n### Tool Interaction Flow\n\n```mermaid\nsequenceDiagram\n participant C as Claude Assistant\n participant MCP as clawskills-mcp Server\n participant FS as File System\n \n C->>MCP: list_skills\n MCP->>FS: Read INDEX.md\n FS-->>MCP: Return skill list\n MCP-->>C: Skill names & descriptions\n \n C->>MCP: get_skill(skill_name, section?)\n MCP->>FS: Read skills/{skill}/skill.md\n FS-->>MCP: Return skill document\n MCP-->>C: Full skill or section content\n \n C->>MCP: search_skills(query)\n MCP->>FS: Read all skill files\n FS-->>MCP: Search results\n MCP-->>C: Matching skill sections\n```\n\n## Available MCP Tools\n\n### 1. list_skills\n\nReturns a list of all available skill documentation files in the ClawSkills library.\n\n**Parameters:** None required\n\n**Returns:** Array of skill names with brief descriptions\n\n**资料来源：** [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n### 2. get_skill\n\nRetrieves the complete content of a skill document or a specific section within it.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `skill` | string | Yes | Name of the skill (e.g., \"jira\", \"github\", \"figma\") |\n| `section` | string | No | Specific section to retrieve: `auth`, `rate-limits`, `recipes`, `errors` |\n\n**Returns:** Full skill documentation or specified section content\n\n**资料来源：** [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n### 3. search_skills\n\nPerforms full-text search across all skill documents.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `query` | string | Yes | Search terms to match against skill content |\n| `limit` | number | No | Maximum number of results (default varies) |\n\n**Returns:** Matching skill sections with context\n\n**资料来源：** [mcp-server/src/index.ts](https://github.com/Shanksg/clawskills/blob/main/mcp-server/src/index.ts)\n\n## Installation\n\n### Prerequisites\n\n- Node.js 18+ (for npx usage)\n- npm 8+ (for global installation)\n\n### Quick Start (Temporary)\n\n```bash\nnpx -y clawskills-mcp\n```\n\n### Permanent Installation\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n### Claude Desktop Configuration\n\nAdd the following to your Claude Desktop configuration file:\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### Claude Code Configuration\n\nFor Claude Code projects, add the MCP server to your project's MCP settings:\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n## Supported Skills\n\nThe MCP server provides access to documentation for the following integrations:\n\n| Skill Name | Description | Category |\n|------------|-------------|----------|\n| `github` | GitHub REST/GQL APIs | VCS |\n| `jira` | Jira Cloud REST API | Project Management |\n| `salesforce` | Salesforce REST API | CRM |\n| `monday` | Monday.com API | Project Management |\n| `hubspot` | HubSpot CRM API | CRM |\n| `dynamics365` | Microsoft Dynamics 365 | CRM/ERP |\n| `servicenow` | ServiceNow REST API | ITSM |\n| `zendesk` | Zendesk Support API | Support |\n| `asana` | Asana API | Project Management |\n| `linear` | Linear GraphQL API | Project Management |\n| `figma` | Figma REST API | Design |\n| `stripe` | Stripe API | Payments |\n| `notion` | Notion API | Productivity |\n| `slack` | Slack Web API | Communication |\n\n**资料来源：** [README.md:1](), [skills/ROADMAP.md:1]()\n\n## Usage Patterns\n\n### Pattern 1: Direct Reference in Prompts\n\nPaste skill documentation directly into your conversation:\n\n```\nUsing the above Figma authentication section, write a Python function \nthat exchanges a JWT for an access token and caches it until 5 minutes before expiry.\n```\n\n### Pattern 2: Integration Agent Workflow\n\n```python\ndef run_integration_agent(task: str, tools_needed: list[str]) -> str:\n \"\"\"\n Use MCP tools to fetch skill docs, then write integration code.\n \"\"\"\n # Fetch relevant skills via MCP\n skills = []\n for tool in tools_needed:\n skill_doc = get_skill(tool)\n skills.append(skill_doc)\n \n # Construct prompt with skill context\n prompt = f\"\"\"\n Task: {task}\n \n Integration documentation:\n {skills}\n \n Write the integration code following these patterns.\n \"\"\"\n \n # Send to Claude for code generation\n response = client.messages.create(\n model=\"claude-sonnet-4-20250514\",\n max_tokens=2048,\n messages=[{\"role\": \"user\", \"content\": prompt}]\n )\n return response.content[0].text\n```\n\n### Pattern 3: Project Instruction Integration\n\nAdd to your `.claude/CLAUDE.md` to configure Claude Code with skill awareness:\n\n```markdown\n# Integration Skills\n\nWhen writing code that integrates with any of the following tools, always read the \ncorresponding skill doc before writing code:\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\nFollow the auth patterns, rate limit handling, and error codes exactly as documented.\nAlways pin API version headers where specified.\n```\n\n**资料来源：** [README.md:1]()\n\n## Skill Document Structure\n\nEach skill document follows a standardized template with 11 required sections:\n\n| Section | Purpose |\n|---------|---------|\n| Overview | High-level description and key capabilities |\n| Authentication & permissions | Auth methods, scopes, token management |\n| Core entities | Data models, entity types, relationships |\n| Endpoints | API endpoints with parameters and responses |\n| Common workflows (recipes) | Step-by-step integration patterns |\n| Error handling | Error codes, retry strategies |\n| Rate limits | Rate limiting policies and headers |\n| Webhooks | Webhook setup, signature verification |\n| Best practices | Security, reliability, performance tips |\n| Testing checklist | Verified behaviors and test cases |\n| Sources | Links to official vendor documentation |\n\n**资料来源：** [README.md:1](), [skills/ROADMAP.md:1]()\n\n## Best Practices\n\n### When Using MCP Tools\n\n1. **Specify exact tools needed**: Rather than loading all skills, request only the tools relevant to your current task to minimize complexity\n2. **Use section filtering**: When you only need authentication info, specify `section: \"auth\"` to get targeted content\n3. **Combine search with targeted retrieval**: Use `search_skills` to find relevant content, then `get_skill` for complete context\n\n### When Writing Integration Code\n\n1. **Follow documented auth patterns**: Each skill specifies the recommended authentication method (PAT, OAuth, API Key)\n2. **Implement rate limit handling**: Respect the documented rate limits and use Retry-After headers\n3. **Pin API version headers**: Use the exact version headers specified (e.g., `Notion-Version: 2025-09-03`)\n4. **Handle errors consistently**: Use the documented error codes and retry strategies\n\n## Troubleshooting\n\n### Connection Issues\n\n| Symptom | Solution |\n|---------|----------|\n| MCP server not connecting | Verify Node.js version is 18+ |\n| Tools not appearing in Claude | Check Claude Desktop config JSON syntax |\n| Timeout on first request | Allow additional time for npx to download package |\n\n### Debug Logging\n\nLog the following for troubleshooting:\n- Tool name called\n- Parameters passed\n- Response status and timing\n\nDo NOT log:\n- Token values or credentials\n- Full request/response bodies (may contain PII)\n\n## Future Enhancements\n\nThe ClawSkills project roadmap includes improvements to the MCP server:\n\n| Enhancement | Status |\n|-------------|--------|\n| Freshness validation pipeline | Planned |\n| Cross-tool orchestration recipes | Not started |\n| Bulk operations documentation | Partial |\n| Real-time sync patterns | Complete |\n\n**资料来源：** [skills/ROADMAP.md:1]()\n\n## See Also\n\n- [CLAUDE.md Integration Guide](README.md) - Detailed integration patterns\n- [Skills Index](skills/INDEX.md) - Complete list of available skills\n- [Slack-Jira Incident Playbook](playbooks/slack-jira-incident.md) - Cross-tool workflow example\n- [ROADMAP.md](skills/ROADMAP.md) - Project roadmap and status\n\n---\n\n\n\n## AI Tool Integration Guide\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#quick-start), [MCP Tools Reference](#mcp-tools), [Playbooks Index](#playbooks-index)\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/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/notion/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/notion/skill.md)\n- [skills/linear/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/linear/skill.md)\n- [skills/slack/skill.md](https://github.com/Shanksg/clawskills/blob/main/skills/slack/skill.md)\n- [playbooks/slack-jira-incident.md](https://github.com/Shanksg/clawskills/blob/main/playbooks/slack-jira-incident.md)\n \n\n# AI Tool Integration Guide\n\n## Overview\n\nThe **clawskills** project is a comprehensive library of skill documentation designed to enable AI assistants (such as Claude) to integrate with third-party tools and services through a standardized, machine-readable format. Each skill document provides authentication patterns, API endpoints, rate limits, error handling, and reusable code recipes for a specific vendor API. 资料来源：[README.md]()\n\n### Purpose and Scope\n\nThe project serves two primary audiences:\n\n1. **AI Development Platforms** — Developers building AI agents can reference skill docs to understand how their AI assistant should interact with external services\n2. **Integration Developers** — Teams implementing integrations can use these docs as authoritative references for correct API usage, authentication flows, and error handling\n\nEach skill file follows a strict template with 11 required sections, ensuring consistency across all 14 currently supported tools. 资料来源：[skills/ROADMAP.md]()\n\n### Supported Tools\n\nThe library currently covers 14 primary tools with complete documentation:\n\n| Category | Tools |\n|----------|-------|\n| Project Management | Jira, Asana, Monday.com, Linear |\n| Development | GitHub, Figma |\n| CRM & Sales | Salesforce, HubSpot, Dynamics 365 |\n| Support & ITSM | Zendesk, ServiceNow |\n| Communication | Slack |\n| Other | Stripe, Notion |\n\n---\n\n## Architecture\n\n### MCP Server Architecture\n\nThe integration is powered by a Model Context Protocol (MCP) server that exposes three core tools enabling AI assistants to query the skill library dynamically:\n\n```mermaid\ngraph TD\n A[AI Assistant] -->|list_skills| B[clawskills-mcp Server]\n A -->|get_skill| B\n A -->|search_skills| B\n B --> C[Skill Documentation Files]\n B --> D[skills/INDEX.md]\n \n E[Claude Desktop Config] -->|npx -y clawskills-mcp| B\n F[Claude Code Config] -->|npx -y clawskills-mcp| B\n```\n\n**MCP Server Tools:**\n\n| Tool | Purpose |\n|------|---------|\n| `list_skills` | Retrieve a list of all available skill documents |\n| `get_skill` | Fetch a complete skill doc or a specific section (e.g., `auth`, `rate-limits`, `recipes`) |\n| `search_skills` | Full-text search across all skill documents |\n\n资料来源：[README.md]()\n\n### Skill Document Structure\n\nEach skill document is organized into 11 mandatory sections, ensuring comprehensive coverage:\n\n| Section | Content |\n|---------|---------|\n| Base URL & Versioning | API base URLs, version headers |\n| Authentication & Permissions | PAT, OAuth 2.0, API tokens, scopes |\n| Core entities | Data models, IDs, relationships |\n| Common workflows (recipes) | Step-by-step integration patterns |\n| Rate limits | Request quotas, complexity points |\n| Error handling | Error codes, retry patterns |\n| Webhooks | Event subscriptions, signature verification |\n| Testing & validation | Checklist of test scenarios |\n| Sources | Links to official vendor documentation |\n\n资料来源：[skills/ROADMAP.md]()\n\n---\n\n## Authentication Patterns\n\nThe skill library documents multiple authentication methods across different vendors, standardized into common patterns.\n\n### Personal Access Token (PAT)\n\nRecommended for server-to-server integrations:\n\n```bash\ncurl https://api.figma.com/v1/me \\\n -H \"X-Figma-Token: YOUR_PAT\"\n```\n\n### OAuth 2.0\n\nRecommended for user-facing applications requiring user context:\n\n```bash\n# Authorization URL\nGET https://www.figma.com/oauth\n ?client_id=CLIENT_ID\n &redirect_uri=REDIRECT_URI\n &scope=file_content:read,file_comments:write\n &state=RANDOM_STATE\n &response_type=code\n\n# Token exchange\ncurl -X POST https://api.figma.com/v1/oauth/token \\\n -d \"client_id=CLIENT_ID\" \\\n -d \"client_secret=CLIENT_SECRET\" \\\n -d \"redirect_uri=REDIRECT_URI\" \\\n -d \"code=AUTH_CODE\" \\\n -d \"grant_type=authorization_code\"\n```\n\n### API Token + Basic Auth\n\nCommon pattern for Jira and similar Atlassian products:\n\n```bash\ncurl -s -X PUT \"$BASE/rest/api/3/issue/PROJ-42\" \\\n -H \"Authorization: $AUTH\" \\\n -H \"Content-Type: application/json\"\n```\n\n资料来源：[skills/figma/skill.md](), [skills/jira/skill.md]()\n\n---\n\n## Rate Limiting Strategies\n\nEach skill document specifies rate limits and recommended retry strategies.\n\n### Rate Limit Response Patterns\n\n| Header | Description |\n|--------|-------------|\n| `X-RateLimit-Requests-Limit` | Total allowed requests in window |\n| `Retry-After` | Seconds to wait before retry (on 429) |\n| `X-Complexity` | Complexity points cost for Linear API |\n\n### Retry Pattern\n\n```python\nimport time\nimport requests\n\ndef call_with_retry(url, headers, max_retries=3):\n for attempt in range(max_retries):\n response = requests.get(url, headers=headers)\n if response.status_code == 429:\n retry_after = int(response.headers.get(\"Retry-After\", 60))\n time.sleep(retry_after)\n continue\n return response\n raise Exception(\"Max retries exceeded\")\n```\n\n资料来源：[skills/linear/skill.md](), [skills/notion/skill.md]()\n\n### Rate Limits by Tool\n\n| Tool | Requests/hr | Notes |\n|------|-------------|-------|\n| Linear (API key) | 5,000 | 250,000 complexity points/hr |\n| Linear (OAuth) | 5,000 | 2,000,000 complexity points/hr |\n| Notion | 3/sec | Exceeding triggers `429` with `Retry-After` |\n| Jira | Varies by plan | Includes attachment size limits (10 MB default) |\n\n---\n\n## Cross-Tool Orchestration\n\nThe project includes playbooks demonstrating multi-system workflows. These are the most advanced integration patterns, combining multiple tool APIs in a single workflow.\n\n### Slack-Jira Incident Response Playbook\n\nThis playbook demonstrates automated incident management across Slack and Jira:\n\n```mermaid\ngraph LR\n A[Slack Alert] --> B{Trigger Type}\n B -->|reaction_added| C[Get Channel + TS]\n B -->|message| D[Get Thread Info]\n B -->|slash command| E[Get Command Payload]\n \n C --> F[Resolve Permalink]\n D --> F\n E --> F\n \n F --> G{Search Jira}\n G -->|Found| H[Reuse Existing Issue]\n G -->|Not Found| I[Create Jira Issue]\n \n H --> J[Post Reply in Slack Thread]\n I --> J\n J --> K[Pin Bot Reply]\n```\n\n**Field Mapping:**\n\n| Slack | Jira |\n|-------|------|\n| `correlation key` = `slack:{team_id}:{channel_id}:{ts}` | Stored as label |\n| message text | `summary` (first 120 chars) + `description` |\n| Slack permalink | Included in description |\n| `reaction_added` / `message` / slash command | Different correlation key formats |\n\n资料来源：[playbooks/slack-jira-incident.md]()\n\n### Phase 5 Status\n\nCross-tool orchestration is currently in **Phase 5 — Patterns listed but not fully implemented**:\n\n> Cross-Tool Orchestration | Multi-system recipes spanning 2+ tools | ❌ Not started — patterns listed in INDEX.md but no dedicated recipes\n\n资料来源：[skills/ROADMAP.md]()\n\n---\n\n## Error Handling\n\n### Common Error Codes\n\n| Code | Tool | Meaning |\n|------|------|---------|\n| `missing_version` | Notion | Request missing `Notion-Version` header |\n| `object_not_found` | Notion | Page/database not shared with integration |\n| `RATELIMITED` | Linear | Burst limit exceeded |\n| `ENTITY_NOT_FOUND` | Linear | Invalid UUID in mutation |\n| `INPUT_ERROR` | Linear | Malformed input data |\n| `cant_update_message` | Slack | Bot cannot update another user's message |\n| `validation_error` | Notion | Exceeded block limit (100 blocks) |\n\n### Error Debugging Patterns\n\nSlack-specific debugging guidance:\n\n> **Events arrive but signature verification fails:** Make sure you're reading the raw request body (not parsed JSON) for HMAC calculation. Some frameworks re-encode the body — use the raw bytes.\n\n资料来源：[skills/slack/skill.md]()\n\n---\n\n## Webhook Integration\n\n### Setting Up Webhooks\n\nJira webhook registration example:\n\n```bash\ncurl -s -X POST \"$BASE/rest/webhooks/1.0/webhook\" \\\n -H \"Authorization: $AUTH\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"My Integration Webhook\",\n \"url\": \"https://your-server.example.com/jira-webhook\",\n \"events\": [\"jira:issue_created\", \"jira:issue_updated\"],\n \"filters\": {\n \"issue-related-events-section\": \"project = PROJ AND issuetype in (Bug, Incident)\"\n }\n }'\n```\n\n**Available Jira Events:** `jira:issue_created`, `jira:issue_updated`, `jira:issue_deleted`, `comment_created`, `comment_updated`, `jira:worklog_updated`, `sprint_created`, `sprint_closed`\n\n### Webhook Security\n\n| Platform | Security Mechanism |\n|----------|-------------------|\n| HubSpot | HMAC-SHA256 signature in `X-HubSpot-Signature-v3` header |\n| Jira | Secret token in URL query string (e.g., `?secret=abc123`) |\n| Linear | `Linear-Signature` header verification |\n\n> **Note:** Jira Cloud webhooks do not send a signature by default. Use a secret token in the URL path or query string and verify it in your handler.\n\n资料来源：[skills/jira/skill.md](), [skills/hubspot/skill.md](), [skills/linear/skill.md]()\n\n---\n\n## Data Models\n\n### Node Types (Figma)\n\nUnderstanding Figma's node hierarchy is essential for file operations:\n\n| Type | Description |\n|------|-------------|\n| `DOCUMENT` | Root node of a file |\n| `CANVAS` | A page in the file |\n| `FRAME` | Artboard / container |\n| `COMPONENT` | Reusable component definition |\n| `INSTANCE` | Linked copy of a COMPONENT |\n| `COMPONENT_SET` | Container for component variants |\n| `TEXT` | Text layer |\n| `VECTOR` | Vector shape |\n\n### Custom Fields (Jira)\n\nJira custom fields use IDs like `customfield_10014`. The mapping varies per instance:\n\n| Field | Jira Cloud Default ID |\n|-------|----------------------|\n| Epic Link | `customfield_10014` |\n| Sprint | `customfield_10020` |\n| Story Points | `customfield_10028` (may vary) |\n\nAlways introspect using: `GET /rest/api/3/field`\n\n资料来源：[skills/figma/skill.md](), [skills/jira/skill.md]()\n\n---\n\n## Integration with Claude\n\n### Option 1 — Reference Specific Sections\n\nPaste a skill doc section into your Claude conversation:\n\n```markdown\n[paste the \"Authentication & permissions\" section from skills/salesforce/skill.md]\n\nUsing the above, write a Python function that exchanges a JWT for an access token\nand caches it until 5 minutes before expiry.\n```\n\n### Option 2 — Full Skill as System Context\n\nLoad skill docs as part of the system prompt:\n\n```python\nimport anthropic\n\nwith open(\"skills/jira/skill.md\") as f:\n jira_skill = f.read()\n\nclient = anthropic.Anthropic()\nresponse = client.messages.create(\n model=\"claude-sonnet-4-20250514\",\n max_tokens=1024,\n system=f\"Follow the auth patterns in:\\n{jira_skill}\",\n messages=[{\"role\": \"user\", \"content\": \"Create a Jira issue for a login bug\"}]\n)\n```\n\n### Option 3 — Claude Desktop/Code Integration\n\nAdd to your Claude Desktop or Claude Code configuration:\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md]()\n\n---\n\n## Development Workflow\n\n### Adding a New Skill\n\n1. Create a branch: `git checkout -b skill/`\n2. Follow the template structure in any existing `skill.md` — all 11 sections required\n3. Verify all endpoints, rate limits, and auth flows against official vendor docs\n4. Add a `Last validated:` date to the doc header\n5. Update `skills/INDEX.md` and `README.md` when adding a new tool\n6. Link to official sources in the `## Sources` section — no unverified claims\n7. Open a PR — CI runs `npm test` which validates that your skill loads and has all required sections\n\n### CI/CD Pipeline\n\n| Component | Status |\n|-----------|--------|\n| CI pipeline — build + test on every push/PR via `ci.yml` | ✅ Live |\n| Release automation — `release.yml` workflow_dispatch → bump, tag, npm publish via OIDC | ✅ Live |\n| Test suite — Vitest unit tests + real-skills validation | ✅ Live |\n\n资料来源：[README.md](), [skills/ROADMAP.md]()\n\n---\n\n## Testing Checklist\n\nEach skill document includes a testing checklist. Example from Notion:\n\n| Test | Expected Result |\n|------|-----------------|\n| `POST /v1/pages` creates a page | Returns `200` with page object |\n| `POST /v1/databases/{id}/query` with filter | Returns only matching pages |\n| `PATCH /v1/pages/{id}` updates a property | `GET` confirms new value |\n| Rapid requests (>3/sec) | Triggers `429` with `Retry-After` |\n| Request without `Notion-Version` header | Returns `400` with code `missing_version` |\n| Upsert pattern | Creates once, updates on second call with same external ID |\n\n资料来源：[skills/notion/skill.md]()\n\n---\n\n## Development Phases\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 — Foundation | Auth flows, basic CRUD, retry patterns | ✅ Complete — all 14 tools |\n| Phase 2 — High-Frequency Workflows | 6–12 recipes per tool | ✅ Complete — all 14 tools |\n| Phase 3 — Event-Driven & Real-Time | Webhook setup, signature verification | ✅ Complete — all 14 tools |\n| Phase 4 — Bulk & Advanced Operations | Batch APIs, large-volume patterns | ⚠️ Partial |\n| Phase 5 — Cross-Tool Orchestration | Multi-system recipes | ❌ Not started |\n\n---\n\n## Next Development Phase\n\n### Priority 1 — Freshness and Accuracy Pipeline\n\n> Now that the core 14-skill library exists, the next moat is keeping it accurate as vendor APIs change.\n\n资料来源：[skills/ROADMAP.md]()\n\n---\n\n## Quick Reference\n\n### MCP Server Installation\n\n**Temporary (npx):**\n```bash\nnpx -y clawskills-mcp\n```\n\n**Permanent:**\n```bash\nnpm install -g clawskills-mcp\n```\n\n### Skill Document Format\n\nAll skill documents use Markdown with:\n\n- YAML frontmatter for metadata\n- Tables for structured data (endpoints, parameters, scopes)\n- Code blocks for API examples (bash, Python, GraphQL)\n- Mermaid diagrams for architecture visualization\n- Source citations in format: `资料来源：[path/to/file.ext]()`\n\n---\n\n\n\n## Contributing Guide\n\n### 相关页面\n\n相关主题：[Skill Document Structure](#skill-structure), [Skills Library Overview](#skills-overview)\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# Contributing Guide\n\nThis project maintains a comprehensive library of integration skill documentation for 14 major SaaS platforms. The contributing guide establishes the standardized process for adding new skills and updating existing documentation to ensure consistency, accuracy, and reliability across the entire codebase.\n\n## Overview\n\nThe `clawskills` repository contains self-contained skill documentation files (`.md`) that provide AI assistants with accurate API integration knowledge. Each skill doc follows a strict 11-section template and is validated through automated CI pipelines before publication.\n\n**Supported Platforms:**\nMonday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Figma, Slack, Stripe, Notion, Linear\n\n## Contribution Workflow\n\n```mermaid\ngraph TD\n A[Create Branch: skill/<toolname>] --> B[Follow 11-Section Template]\n B --> C[Verify Endpoints Against Vendor Docs]\n C --> D[Add Last Validated Date]\n D --> E[Update skills/INDEX.md]\n E --> F[Update README.md]\n F --> G[Open Pull Request]\n G --> H[CI Pipeline: npm test]\n H --> I{All Tests Pass?}\n I --|Yes| J[Merge to main]\n I --|No| K[Fix Validation Errors]\n K --> H\n J --> L[Release Automation]\n```\n\n## Branch Naming Convention\n\nAll skill contributions must be created from a feature branch following this naming pattern:\n\n```bash\ngit checkout -b skill/<toolname>\n```\n\nReplace `` with the lowercase, hyphenated name of the platform (e.g., `skill/zendesk`, `skill/jira`).\n\n资料来源：[README.md:1-10]()\n\n## Skill Template Structure\n\nEvery skill document must contain all 11 required sections. Use an existing skill file (e.g., `skills/jira/skill.md`) as your reference template.\n\n### Required Sections\n\n| Section | Description | Required Content |\n|---------|-------------|------------------|\n| 1. Overview | High-level description of the tool's API | API type, base URL, protocol |\n| 2. Authentication & permissions | Auth methods and required scopes | PAT, OAuth, API key patterns |\n| 3. Core entities | Data models and record types | Table names, field descriptions |\n| 4. Common workflows (recipes) | Step-by-step integration patterns | 5-12 practical examples |\n| 5. Error codes & troubleshooting | Known errors and solutions | Error messages, HTTP codes |\n| 6. Rate limits | Request quotas and headers | Requests/hr, complexity points |\n| 7. Reliability | Retry patterns, idempotency | Backoff strategies, best practices |\n| 8. Security, privacy, compliance | Data handling requirements | Scope permissions, GDPR notes |\n| 9. Available scopes / permissions | Full permission matrix | Scope tables with access levels |\n| 10. Sources | Official documentation links | Verified vendor URLs only |\n| 11. QA checklist | Validation checklist | Test cases for integration |\n\n### Document Quality Requirements\n\n```javascript\n// Minimum file size: 5KB\n// Source: mcp-server/src/index.test.ts\nconst MIN_FILE_SIZE = 5000; // bytes\n\n// Every skill must have:\nconst REQUIRED_SECTIONS = [\n 'overview',\n 'authentication',\n 'common-workflows',\n 'error-codes',\n 'rate-limits',\n 'reliability',\n 'security',\n 'scopes',\n 'sources',\n 'qa-checklist'\n];\n```\n\n资料来源：[mcp-server/src/index.test.ts:21-30]()\n\n## Verification Process\n\nBefore committing your skill document, perform the following verification steps:\n\n### Endpoint Verification Checklist\n\n1. **Review official vendor documentation** for all endpoints referenced in the skill\n2. **Verify rate limits** against current vendor documentation (note: rate limits are updated periodically)\n3. **Test authentication flows** locally if possible, or document the exact OAuth/ PAT flow\n4. **Validate JSON examples** against actual API responses\n5. **Check for deprecated endpoints** — for example, Figma's `files:read` scope is deprecated as of November 2025\n\n### Required Metadata\n\nEach skill document **must** include a `Last validated:` date in the doc header:\n\n```markdown\n---\nLast validated: 2025-01-15\n---\n```\n\n资料来源：[README.md:1-10]()\n\n## Updating Project Indexes\n\nAfter creating or modifying a skill, you must update two index files:\n\n### 1. Update `skills/INDEX.md`\n\nAdd an entry for the new tool following the existing format:\n\n```markdown\n| Tool Name | Description | Status |\n|-----------|-------------|--------|\n| zendesk | Zendesk Support API | ✅ Complete |\n```\n\n### 2. Update `README.md`\n\nAdd the tool to the list of available skills in the README:\n\n```markdown\n- Zendesk → @skills/zendesk/skill.md\n```\n\n资料来源：[README.md:1-10]()\n\n## Pull Request Process\n\n### PR Requirements\n\n1. **Branch name** must follow `skill/` convention\n2. **PR description** must include:\n - Summary of changes\n - `Last validated` date\n - List of verified endpoints\n3. **All CI checks must pass** before merge\n\n### CI Pipeline Validation\n\n```mermaid\ngraph LR\n A[Push/PR Trigger] --> B[ci.yml Workflow]\n B --> C[Build Stage]\n C --> D[Test Stage: npm test]\n D --> E{Vitest Results}\n E -->|Pass| F[Skill Validated]\n E -->|Fail| G[Report Errors]\n G --> H[Developer Fixes]\n H --> D\n```\n\nThe CI pipeline performs these automated checks:\n\n| Test | Description | Failure Condition |\n|------|-------------|-------------------|\n| `loads all expected skills` | Verifies skill file exists | Missing skill file |\n| `has non-empty summary` | First line is not blank | Empty summary |\n| `contains required sections` | All 11 sections present | Missing section |\n| `file is at least 5KB` | Minimum document size | Suspiciously short |\n\n资料来源：[skills/ROADMAP.md:1-20]()\n\n### Running Tests Locally\n\nBefore pushing, run the test suite locally:\n\n```bash\nnpm test\n```\n\nThis executes the same validation that CI runs, catching issues before submission.\n\n## Release Process\n\nReleases are fully automated through GitHub Actions:\n\n```mermaid\ngraph TD\n A[Merge to main] --> B[Navigate to GitHub Actions]\n B --> C[Select Release Workflow]\n C --> D[Run Workflow]\n D --> E[Select Version Type]\n E --> F{patch/minor/major}\n F -->|patch| G[0.0.X Increment]\n F -->|minor| H[0.X.0 Increment]\n F -->|major| I[X.0.0 Increment]\n G --> J[Create Git Tag]\n H --> J\n I --> J\n J --> K[Publish to npm]\n```\n\n**Version bump types:**\n- **patch**: Bug fixes, typo corrections, documentation updates\n- **minor**: New recipes, additional examples, new sections\n- **major**: Breaking changes to template structure, new platform support\n\n资料来源：[skills/ROADMAP.md:1-20]()\n\n## Skill File Naming Convention\n\n| Platform | File Path |\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\nAll skills are stored under the `skills/` directory using the platform slug as the folder name.\n\n## MCP Server Integration\n\nThe repository includes an MCP (Model Context Protocol) server that exposes the skill documents to AI assistants:\n\n### MCP Tools Available\n\n| Tool | Purpose |\n|------|---------|\n| `list_skills` | See all available skill docs |\n| `get_skill` | Fetch a full skill or specific section |\n| `search_skills` | Full-text search across all skills |\n\n### MCP Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"clawskills\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"clawskills-mcp\"]\n }\n }\n}\n```\n\nOr install permanently:\n\n```bash\nnpm install -g clawskills-mcp\n```\n\n## Governance and Roadmap\n\nThe project follows a phased development approach documented in `skills/ROADMAP.md`:\n\n| Phase | Theme | Status |\n|-------|-------|--------|\n| Phase 1 | Foundation (Auth + Core CRUD) | ✅ Complete |\n| Phase 2 | High-Frequency Workflows | ✅ Complete |\n| Phase 3 | Event-Driven & Real-Time | ✅ Complete |\n| Phase 4 | Bulk & Advanced Operations | ⚠️ Partial |\n| Phase 5 | Cross-Tool Orchestration | ❌ Not started |\n\nContributors should review the roadmap to align new contributions with the project's strategic direction.\n\n资料来源：[skills/ROADMAP.md:1-30]()\n\n## Quick Reference Checklist\n\nBefore submitting your contribution:\n\n- [ ] Branch created with correct naming: `skill/`\n- [ ] All 11 template sections included\n- [ ] Summary line is non-empty\n- [ ] File size exceeds 5KB\n- [ ] `Last validated:` date added to header\n- [ ] Endpoints verified against official docs\n- [ ] Rate limits checked for accuracy\n- [ ] `skills/INDEX.md` updated\n- [ ] `README.md` updated\n- [ ] `npm test` passes locally\n- [ ] PR opened with clear description\n- [ ] CI checks green\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: Shanksg/clawskills\n\nSummary: Found 8 potential pitfall items; 0 are high/blocking. Highest priority: installation - 来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs.\n\n## 1. installation · 来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_3ca25afbd8c246fa9810ea334a993872 | https://github.com/Shanksg/clawskills/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1161910025 | https://github.com/Shanksg/clawskills | host_targets=mcp_host, claude\n\n## 3. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:1161910025 | https://github.com/Shanksg/clawskills | README/documentation is current enough for a first validation pass.\n\n## 4. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | last_activity_observed missing\n\n## 5. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 6. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 7. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | issue_or_pr_quality=unknown\n\n## 8. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "Human Manual"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log\n\nProject: Shanksg/clawskills\n\nSummary: Found 8 potential pitfall items; 0 are high/blocking. Highest priority: installation - 来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs.\n\n## 1. installation · 来源证据：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_3ca25afbd8c246fa9810ea334a993872 | https://github.com/Shanksg/clawskills/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1161910025 | https://github.com/Shanksg/clawskills | host_targets=mcp_host, claude\n\n## 3. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:1161910025 | https://github.com/Shanksg/clawskills | README/documentation is current enough for a first validation pass.\n\n## 4. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | last_activity_observed missing\n\n## 5. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 6. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium\n\n## 7. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | issue_or_pr_quality=unknown\n\n## 8. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | release_recency=unknown\n",
"summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.",
"title": "Pitfall Log"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# clawskills - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for Shanksg/clawskills.\n\nProject:\n- Name: clawskills\n- Repository: https://github.com/Shanksg/clawskills\n- Summary: MCP server + skill docs teaching AI agents to reliably integrate with 14 SaaS APIs — auth, rate limits, recipes, and cross-tool playbooks.\n- Host target: mcp_host, claude\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: MCP server + skill docs teaching AI agents to reliably integrate with 14 SaaS APIs — auth, rate limits, recipes, and cross-tool playbooks.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. quick-start: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n2. skills-overview: Skills Library Overview. Produce one small intermediate artifact and wait for confirmation.\n3. skill-structure: Skill Document Structure. Produce one small intermediate artifact and wait for confirmation.\n4. playbooks-index: Playbooks Index. Produce one small intermediate artifact and wait for confirmation.\n5. mcp-server-architecture: MCP Server Architecture. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start\n\nProject: Shanksg/clawskills\n\n## Official Entry Points\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx -y clawskills-mcp\n```\n\nSource：https://github.com/Shanksg/clawskills#readme\n\n## Sources\n\n- repo: https://github.com/Shanksg/clawskills\n- docs: https://github.com/Shanksg/clawskills#readme\n",
"summary": "Entry points extracted from official README or installation documentation.",
"title": "Quick Start"
}
},
"validation_id": "dval_5c9a84a2c3d84783bc392d5f713cfdc7"
}