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

原创于 2025-12-20 17:09:35 发布 · 288 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能 #prompt #Skills #Agent #上下文工程

AI 专栏收录该内容

40 篇文章

订阅专栏

AgenticCoding·十二月创作之星挑战赛 10w+人浏览 430人参与

Cursor 中自动加载 Skill 的技术实现解析
落地方案：Cursor-Skills Github

Cursor Skills CLI

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

在这里插入图片描述

功能特性

双级 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>

 和  标记之间的内容由 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 确认