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