内容
# 技能文档库
用于市场推广和运营工作流中最常用SaaS平台的集成技能文档库。每个技能文档教导 **AI代理、自动化构建器或LLM** 如何可靠地使用平台的API，并提供工作代码示例、速率限制规则、错误处理手册和平台特定版本详细信息。
## 目录
```
playbooks/
├── INDEX.md ← 工作流级别的指南，涵盖多个工具
├── hubspot-asana-onboarding.md
├── salesforce-hubspot-lead-sync.md
├── slack-jira-incident.md
└── zendesk-jira-bug-escalation.md
skills/
├── INDEX.md ← 从这里开始：所有工具、主要工作流、快速参考表
├── ROADMAP.md ← 分阶段构建计划和治理模型
├── monday/skill.md ← Monday.com（GraphQL API v2026-01）
├── salesforce/skill.md ← Salesforce Sales Cloud（REST API v66.0）
├── jira/skill.md ← Jira Cloud（REST API v3）
├── dynamics365/skill.md ← Microsoft Dynamics 365（Dataverse Web API v9.2）
├── hubspot/skill.md ← HubSpot CRM（API v3，190 req/10s）
├── servicenow/skill.md ← ServiceNow（Yokohama release，Table API）
├── zendesk/skill.md ← Zendesk Support（API v2）
├── asana/skill.md ← Asana（REST API 1.0）
├── github/skill.md ← GitHub（REST API + GraphQL v4，2022-11-28）
├── figma/skill.md ← Figma（REST API v1，Webhooks V2）
├── slack/skill.md ← Slack（Web API，Block Kit，Events API）
├── stripe/skill.md ← Stripe（Payments API v2026-02-25，Billing，Connect）
├── notion/skill.md ← Notion（REST API v2025-09-03，Pages，Databases，Blocks）
└── linear/skill.md ← Linear（GraphQL API，Issues，Cycles，Webhooks）
```
每个 `skill.md` 都遵循相同的结构：
- **本技能实现的功能** — 面向结果的要点
- **最佳适用场景** — 8-15个真实工作流的表格，包含触发器和成功标准
- **关键概念和数据模型** — 对象、字段、关系、ID
- **身份验证和权限** — 带有工作 `curl` 示例的身份验证流程，最小权限范围
- **常见工作流（配方）** — 6-12个逐步配方，包含请求/响应示例
- **查询模式和筛选** — 分页、增量同步、去重
- **可靠性：速率限制、重试、幂等性** — 验证的限制、Python中的回退代码
- **错误处理和故障排除** — “如果看到X，则执行Y”的手册
- **安全性和合规性** — PII、审计跟踪、令牌指导
- **测试检查清单** — 可针对沙盒运行的QA检查清单
- **来源** — 官方文档链接
每个技能在其文档头部跟踪自己的平台版本和“上次验证”日期。MCP包有一个单独的npm版本，因为它对服务器/工具层进行版本控制，而不是底层SaaS API。
`playbooks/` 层捕获跨工具工作流的端到端：触发器、系统序列、字段映射、幂等性、故障策略和操作防护。
## 与MCP一起使用Claude（推荐）
ClawSkills作为MCP服务器提供，所有技能文档直接在Claude中作为工具暴露。
```bash
npx -y clawskills-mcp
```
或永久安装：
```bash
npm install -g clawskills-mcp
```
添加到您的Claude Desktop / Claude Code配置：
```json
{
"mcpServers": {
"clawskills": {
"command": "npx",
"args": ["-y", "clawskills-mcp"]
}
}
}
```
连接后，Claude可以调用三个工具：
- **`list_skills`** — 查看所有可用的技能文档
- **`get_skill`** — 获取完整的技能文档或特定部分（`auth`、`rate-limits`、`recipes`等）
- **`search_skills`** — 对所有技能进行全文搜索
## 如何将这些技能与AI工具一起使用
### 与Claude（claude.ai或Claude Code）一起使用
最直接的使用方法：将技能文档（或其某一部分）粘贴到对话中作为上下文，然后要求Claude编写集成代码、调试错误或计划工作流。
**选项1 — 参考特定部分**
```
[粘贴来自skills/salesforce/skill.md的“身份验证和权限”部分]
使用上述信息，编写一个Python函数，交换JWT以获取访问令牌，
并在到期前5分钟缓存它。
```
**选项2 — 使用完整技能作为系统上下文**
如果您正在使用Claude API，请将技能文档作为系统提示的一部分加载：
```python
import anthropic
with open("skills/jira/skill.md") as f:
jira_skill = f.read()
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=4096,
system=f"""您是一名集成工程师。请使用以下Jira技能文档作为参考，
用于所有API调用、身份验证模式和错误处理：
{jira_skill}
始终遵循技能文档中的速率限制和重试模式。",
messages=[{
"role": "user",
"content": "编写一个从PagerDuty警报有效负载创建Jira错误的函数。"
}]
)
```
**选项3 — Claude Code（此仓库）**
如果您已经在Claude Code中打开了此仓库，只需引用文件：
```
使用skills/hubspot/skill.md，编写一个Python脚本，
将新的Salesforce线索（在最近一小时内创建）同步到HubSpot联系人，
按电子邮件地址去重。
```
### 与ChatGPT / GPT-4一起使用
将技能文档作为文件附件或粘贴到ChatGPT界面中的上下文。
**在ChatGPT网页UI中：**
1. 打开一个新的对话。
2. 点击纸夹（附件）并上传相关的`skill.md`文件。
3. 提出问题 — ChatGPT将使用技能文档作为参考。
**通过OpenAI API：**
```python
from openai import OpenAI
with open("skills/zendesk/skill.md") as f:
zendesk_skill = f.read()
client = OpenAI()
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "system",
"content": f"你是一名集成工程师。请参考以下Zendesk技能文档，
用于所有API模式：\n\n{zendesk_skill}"
},
{
"role": "user",
"content": "编写一个Webhook处理程序，
从传入的JSON警报创建Zendesk票。"
}
]
)
```
### 与Cursor / GitHub Copilot（编辑器上下文）一起使用
这两个工具都拾取项目中的文件作为上下文。
**Cursor：**
- 通过`@file`提及将相关的`skill.md`添加到Cursor上下文中：
```
@skills/monday/skill.md 编写一个函数，
从具有以下字段的Webhook负载创建Monday.com项目：
name, status, due_date, assignee_email
```
- 或将`skills/`添加到Cursor规则（`.cursorrules`），
以便代理始终为集成相关任务提供上下文。
**GitHub Copilot聊天：**
```
#file:skills/servicenow/skill.md
编写一个Python函数，
从CloudWatch警报创建ServiceNow事件。
包括正确的错误处理和work_notes与comments的区别。
```
### 与LangChain / LlamaIndex（RAG管道）一起使用
将技能文档用作知识库，用于检索增强生成系统。每个技能文档都是自成体系的，作为RAG文档效果良好。
**LangChain示例：**
```python
from langchain_community.document_loaders import DirectoryLoader, TextLoader
from langchain.text_splitter import MarkdownHeaderTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma
from langchain.chains import RetrievalQA
from langchain_openai import ChatOpenAI
# 加载所有技能文档
loader = DirectoryLoader("skills/", glob="**/*.md", loader_cls=TextLoader)
docs = loader.load()
# 按Markdown标题分割以保持章节一致
splitter = MarkdownHeaderTextSplitter(
headers_to_split_on=[("##", "section"), ("###", "subsection")]
)
chunks = []
for doc in docs:
chunks.extend(splitter.split_text(doc.page_content))
# 索引到向量存储
vectorstore = Chroma.from_documents(
chunks,
embedding=OpenAIEmbeddings(),
persist_directory="./skills_index"
)
# 查询
qa = RetrievalQA.from_chain_type(
llm=ChatOpenAI(model="gpt-4o"),
retriever=vectorstore.as_retriever(search_kwargs={"k": 4})
)
answer = qa.invoke("HubSpot Pro的速率限制是多少？如何处理429？")
```
**LlamaIndex示例：**
```python
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex
documents = SimpleDirectoryReader("skills/", recursive=True).load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query(
"如何在一个操作中按电子邮件地址插入Salesforce联系人并记录一个Task？"
)
print(response)
```
### 将技能文档注入Claude API调用中
如果您正在使用Claude API构建自定义代理，可以根据代理即将调用的工具注入相关的技能文档：
```python
import anthropic
from pathlib import Path
SKILL_DIR = Path("skills")
def get_skill(tool_name: str) -> str:
"""为给定的工具slug加载技能文档."""
skill_path = SKILL_DIR / tool_name / "skill.md"
if skill_path.exists():
return skill_path.read_text()
return ""
def run_integration_agent(task: str, tools_needed: list[str]) -> str:
"""运行一个具有注入的技能文档的代理，用于它需要的工具."""
skill_context = "\n\n---\n\n".join(
f"# {tool.upper()} 技能参考\n{get_skill(tool)}"
for tool in tools_needed
if get_skill(tool)
)
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=8192,
system=f"""你是一名集成工程师，正在构建可靠的API集成。
使用以下技能参考，
用于所有API调用、身份验证流程、速率限制和错误处理。
不要偏离所描述的模式。
{skill_context}""",
messages=[{"role": "user", "content": task}]
)
return response.content[0].text
# 示例
result = run_integration_agent(
task="编写一个Python脚本，
将Zendesk票（status=open, priority=urgent）同步到Jira错误。",
tools_needed=["zendesk", "jira"]
)
```
### 在 `.claude/CLAUDE.md` 项目指令文件中
如果您经常在Claude Code中使用，可以告诉Claude始终使用这些文档：
```markdown
# 集成技能
编写与以下工具集成的代码时，
始终阅读相应的技能文档：
- Monday.com → @skills/monday/skill.md
- Salesforce → @skills/salesforce/skill.md
- Jira → @skills/jira/skill.md
- Dynamics 365 → @skills/dynamics365/skill.md
- HubSpot → @skills/hubspot/skill.md
- ServiceNow → @skills/servicenow/skill.md
- Zendesk → @skills/zendesk/skill.md
- Asana → @skills/asana/skill.md
- GitHub → @skills/github/skill.md
- Figma → @skills/figma/skill.md
- Slack → @skills/slack/skill.md
- Stripe → @skills/stripe/skill.md
- Notion → @skills/notion/skill.md
- Linear → @skills/linear/skill.md
在编写代码时，请严格遵循文档中描述的身份验证模式、速率限制处理和错误代码。
始终在指定位置固定API版本头。
```
## 使用技能文档的最佳实践
| 目标 | 在提示中包含的内容 |
|------|-------------------------------|
| 编写集成代码 | 完整的技能文档或“身份验证” + “配方”部分 |
| 调试错误 | “错误处理”部分 + 收到的确切错误消息 |
| 计划工作流 | “最佳适用场景”表格 + “关键概念”部分 |
| 审查现有代码 | 完整的技能文档（AI可以发现与记录的模式有偏差） |
| 处理速率限制 | 仅“可靠性”部分 — 它是自成体系的 |
| 设置Webhook | “常见工作流”中的Webhook配方 + “测试检查清单” |
**提示：**
- 在跨两个工具工作时（例如，Zendesk → Jira同步），
包括两个技能文档。
- 对于代码生成，始终提及目标语言 —
默认情况下，配方是`curl`/Python伪代码。
- 技能文档底部的“测试检查清单”部分
作为验证生成代码的提示很有用：
*"用技能文档中的测试检查清单检查此代码。"*
## 保持技能文档最新
技能文档针对实时API文档进行了验证。
每个文档的头部都有一个“上次验证”日期。
需要注意的关键事项：
- **Monday.com** — 每个季度发布新的API版本；始终固定`API-Version`头为`2026-01`（当前）或查看[developer.monday.com/api-reference/docs/api-versioning](https://developer.monday.com/api-reference/docs/api-versioning)
- **Salesforce** — 每个季节性发布一个新API版本（Spring/Summer/Winter）；目前为v66.0。检查您的组织中可用的版本列表。
- **Jira** — `GET /rest/api/3/search`已弃用；使用`POST /rest/api/3/search/jql`
- **HubSpot** — 基于日期的版本控制（`2025-09`样式）与v3一起推出；速率限制于2024年9月更新
- **ServiceNow** — 目前为Yokohama版本（2025年3月）；在实例升级时更新URL包名称
- **GitHub** — 始终固定`X-GitHub-Api-Version: 2022-11-28`；优先使用细粒度PAT而不是经典PAT；Actions中的`GITHUB_TOKEN`限制为每个仓库1,000 req/hr
- **Figma** — `files:read`范围已弃用；使用粒度范围（`file_content:read`、`file_comments:write`等）；速率限制于2025年11月更新，现在根据计划和席位类型而异
查看[ROADMAP.md](skills/ROADMAP.md)以获取完整的治理和更新流程。
## 贡献
添加或更新技能：
1. 创建一个分支：`git checkout -b skill/<toolname>`
2. 遵循任何现有`skill.md`的模板结构 — 所有11个部分都是必需的。
3. 在提交前，请针对官方供应商文档验证所有端点、速率限制和身份验证流程。
4. 在文档头部添加“上次验证”日期。
5. 更新`skills/INDEX.md`和`README.md`时添加新工具。
6. 在“## 来源”部分链接到官方来源 — 无未经验证的声明。
7. 打开一个PR — CI运行`npm test`，验证您的技能加载并具有所有必需部分。
**发布**是自动化的：合并到`main`，然后前往GitHub Actions → **发布** → 运行工作流 → 选择`patch / minor / major`。
