Cursor创建Skill全指南：从零搭建高效开发工作流

1次阅读

共计 1930 个字符，预计需要花费 5 分钟才能阅读完成。

在 Cursor 中创建自定义 Skill 时，开发者常遇到以下问题：

环境配置复杂：需要手动安装 Python 依赖、配置 JSON-RPC 接口，新手容易遗漏关键步骤
调试周期长：缺乏本地测试工具，每次修改必须重启 Cursor 才能验证效果
性能瓶颈：Skill 冷启动速度慢，处理大文件时界面卡顿明显

Cursor Skill 采用 JSON-RPC over WebSocket 协议，工作流程如下：

Cursor 主进程启动 WebSocket 服务器（默认端口 8899）
Skill 连接服务后注册自身能力描述（capabilities.json）
通过 JSON-RPC 协议实现双向通信，典型消息结构：

{
  "jsonrpc": "2.0",
  "method": "formatDocument",
  "params": {"text": "const a=1"},
  "id": 1
}

以下实现支持自动格式化 JSON/XML 文件的 Skill，注意类型注解和异常处理：

import json
import xml.dom.minidom
from typing import Union
from jsonrpcserver import method, serve

@method
def format_document(text: str, lang: str) -> Union[str, None]:
    """
    :param text: 原始文本内容
    :param lang: 语言类型(json/xml)
    :return: 格式化后的文本或 None(失败时)
    """
    try:
        if lang == "json":
            parsed = json.loads(text)
            return json.dumps(parsed, indent=2)
        elif lang == "xml":
            return xml.dom.minidom.parseString(text).toprettyxml()
    except Exception as e:
        print(f"Format error: {str(e)}")
        return None

if __name__ == "__main__":
    serve(port=8899)

预加载机制 ：在 Cursor 启动时通过preload_skills 配置项提前加载常用 Skill
进程保持 ：使用keepalive 参数维持子进程（需在 skill.json 中配置）
懒加载依赖：将第三方库导入放在具体函数内部

处理大文件时建议采用生产者 - 消费者模式：

from queue import Queue
from threading import Thread

task_queue = Queue(maxsize=100)

def worker():
    while True:
        task = task_queue.get()
        format_document(*task)
        task_queue.task_done()

# 启动 4 个工作线程
for _ in range(4):
    Thread(target=worker, daemon=True).start()

# 提交任务示例
task_queue.put(("{\"a\":1}", "json"))

版本锁定 ：使用pip freeze > requirements.txt 生成精确依赖版本
虚拟环境：每个 Skill 创建独立的 venv 防止冲突
依赖检查 ：在skill.json 中声明所需 Python 版本

修改默认端口：在 config.json 中设置"rpc_port": 8900
使用唯一 Skill ID：如"id": "com.yourname.formatter"
关闭其他 Skill 调试实例

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Cursor    │───▶│ WebSocket   │───▶│   Skill     │
│  主进程     │◀───│  服务器     │◀───│  子进程     │
└─────────────┘    └─────────────┘    └─────────────┘
     ▲                    ▲                    ▲
     │                    │                    │
     ▼                    ▼                    ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  用户界面   │    │  JSON-RPC   │    │ 文件系统    │
│  (输入 / 输出)│    │  消息协议   │    │  操作       │
└─────────────┘    └─────────────┘    └─────────────┘

通过本文介绍的方法，我们实现了：