Cursor Skills CLI

用于管理 Cursor Skills 并同步到 AGENTS.md 的命令行工具。

目录

• 功能特性
• 安装
• 快速开始
• 使用方法
• Skills 目录结构
• SKILL.md 格式
• 生成的 AGENTS.md 结构
• 架构
• API 参考
• 贡献指南
• 许可证

功能特性

• 双级 Skills 管理 - 同时支持项目级和全局级 Skills
• 交互式选择 - 基于 TUI 的多选菜单，支持键盘导航
• AI 代理集成 - 内置 read 命令供 AI 代理调用
• 零依赖 - 纯 Node.js 实现，无任何外部依赖
• 智能同步 - 基于标记的增量更新，保护 AGENTS.md 中的其他内容

安装

环境要求

• Node.js >= 16.0.0

通过 npm 安装

npm install -g @localsummer/cursor-skills

通过 GitHub Packages 安装

npm install -g @localsummer/cursor-skills --registry=https://npm.pkg.github.com

本地开发

git clone https://github.com/localSummer/cursor-skills.git
cd cursor-skills
npm link

快速开始

# 1. 查看可用的 Skills
cursor-skills list

# 2. 选择并同步 Skills 到 AGENTS.md
cursor-skills sync

# 3. 读取特定 Skill 内容（供 AI 代理使用）
cursor-skills read <skill-name>

使用方法

列出可用 Skills

cursor-skills list
cursor-skills ls

扫描并显示以下目录中的所有可用 Skills：

• 项目级: .cursor/skills/
• 全局级: ~/.cursor/skills/

同步 Skills 到 AGENTS.md

cursor-skills sync

打开交互式多选菜单，选择 Skills 并同步到 AGENTS.md。

键盘操作:

| 按键 | 操作 | |------|------| | Up/k | 向上移动 | | Down/j | 向下移动 | | Space | 切换选中状态 | | Ctrl+A | 全选/取消全选 | | Enter | 确认 | | Ctrl+C | 取消 |

读取 Skill 内容

cursor-skills read <skill-name>

将 Skill 的完整内容输出到标准输出。专为 AI 代理集成设计。

输出格式:

# Skill: <name>

Base directory: /path/to/skill
Location: project|global

---

[SKILL.md 内容]

从 AGENTS.md 移除 Skill

cursor-skills remove <skill-name>
cursor-skills rm <skill-name>

从 AGENTS.md 文件中移除指定的 Skill。

帮助

cursor-skills help
cursor-skills help <command>
cursor-skills --help

Skills 目录结构

项目级 Skills

project-root/
└── .cursor/
    └── skills/
        └── skill-name/
            ├── SKILL.md        # 必需: Skill 定义文件
            ├── scripts/        # 可选: 可执行脚本
            ├── references/     # 可选: 参考文件
            └── assets/         # 可选: 资源文件

全局 Skills

~/.cursor/
└── skills/
    └── skill-name/
        └── SKILL.md

优先级规则

当项目级和全局级存在同名 Skill 时：

• 项目级优先
• 两者都会显示，并标注各自的来源位置

SKILL.md 格式

每个 Skill 必须包含一个带有 YAML 前置数据的 SKILL.md 文件：

---
name: my-skill
description: 简要描述这个 Skill 的功能
---

# Skill 文档

详细的文档和使用说明...

前置数据字段

| 字段 | 必需 | 说明 | |------|------|------| | name | 是 | Skill 的显示名称 | | description | 是 | 简要描述（显示在列表中） |

生成的 AGENTS.md 结构

sync 命令生成/更新的 AGENTS.md 结构如下：

<skills_system priority="1">

## Skills 位置

项目级: `.cursor/skills/`
全局级: `~/.cursor/skills/`

<!-- SKILLS_TABLE_START -->
<usage>
...使用说明...
</usage>
<available_skills>
<skill>
  <name>skill-name</name>
  <description>skill 描述</description>
  <location>project|global</location>
</skill>
</available_skills>
<!-- SKILLS_TABLE_END -->

</skills_system>

<!-- SKILLS_TABLE_START --> 和 <!-- SKILLS_TABLE_END --> 标记之间的内容由 CLI 管理。标记外的内容在更新时会被保留。

架构

cursor-skills/
├── index.mjs           # CLI 入口，命令路由
├── commands/           # 命令实现
│   ├── list.mjs       # 列出可用 Skills
│   ├── sync.mjs       # 交互式同步到 AGENTS.md
│   ├── read.mjs       # 读取 Skill 内容
│   ├── remove.mjs     # 从 AGENTS.md 移除 Skill
│   └── help.mjs       # 帮助信息
└── lib/                # 核心模块
    ├── skills.mjs     # Skills 扫描和解析
    ├── agents.mjs     # AGENTS.md 读写
    └── terminal.mjs   # 终端 UI 和样式

模块职责

| 模块 | 职责 | |------|------| | lib/skills.mjs | 扫描目录、解析前置数据、管理 Skill 元数据 | | lib/agents.mjs | 生成和更新 AGENTS.md 内容 | | lib/terminal.mjs | ANSI 颜色、交互式菜单、用户提示 |

错误处理

| 场景 | 处理方式 | |------|----------| | 目录不存在 | 返回空数组，继续执行 | | SKILL.md 不存在 | 跳过该目录，继续扫描 | | AGENTS.md 不存在 | 自动创建新文件 | | 用户中断 (Ctrl+C) | 优雅退出，不会损坏数据 |

API 参考

Skill 对象

{
  name: string,           // Skill 显示名称
  description: string,    // 简要描述
  location: 'global' | 'project',  // 来源位置
  path: string,           // Skill 目录路径
  skillFilePath: string   // SKILL.md 完整路径
}

核心函数

// lib/skills.mjs
getAllSkills(cwd)              // 获取所有可用 Skills
getSkillByName(name, cwd)      // 按名称查找 Skill
readSkillContent(skill)        // 读取 SKILL.md 内容
formatSkillOutput(skill, content)  // 格式化输出

// lib/agents.mjs
updateAgentsFile(skills, cwd)  // 更新 AGENTS.md
getExistingSkillNames(cwd)     // 获取已同步的 Skill 名称
removeSkillFromAgents(name, cwd)  // 从 AGENTS.md 移除

// lib/terminal.mjs
multiSelect({message, choices})  // 交互式多选
confirm(message)               // Y/N 确认

贡献指南

欢迎贡献代码、报告问题或提出功能建议。详细信息请参阅 CONTRIBUTING.md。

快速开始

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开 Pull Request

问题反馈

• 报告 Bug
• 功能建议

变更记录

查看 CHANGELOG.md 了解版本更新历史。

许可证

本项目采用 ISC 许可证。

作者

localSummer - GitHub

如果这个项目对你有帮助，欢迎给一个 Star!