如何搭建 Cursor Skill 标准化目录结构与部署环境

Lifeline2026-06-192026-07-11

前言

上一讲我们系统吃透了Skill、Rule、Token三大核心基础概念，完成了零基础理论认知铺垫。从本篇开始，我们正式进入Skill实操落地阶段，从零搭建可直接使用的AI技能运行环境。

绝大多数新手遇到的Skill失效、无法触发、执行错乱等问题，90%都源于路径错误、目录不标准、命名不规范。AI编程助手的Skill是一套标准化结构化能力包，对存放路径、目录结构、文件格式有严格的官方约束，只要不满足规范，AI就无法扫描、识别和加载技能。

本篇将全程手把手实操教学，带你完整搭建Skill运行环境，深度拆解两种部署模式、官方标准目录结构、核心文件硬性规范，同时汇总新手高频踩坑点，夯实后续所有Skill创作、调试、落地的核心基础。

一、Skill 部署核心逻辑：生效范围决定部署方式

目前主流AI编程助手（Claude Code、CodeBuddy、Cursor）统一提供两套Skill部署方案，分为用户级（全局生效）和项目级（局部生效）。两种模式的核心差异集中在生效范围、存储路径、适用场景，大家可根据自身使用需求灵活选用。

核心**取舍口诀：**通用技能放全局，项目专属放本地。

1.1 用户级 Skill（全局生效）

用户级Skill绑定当前电脑系统用户，存放于系统用户根目录下，本机所有项目均可自动加载、全局生效，无需重复新建、配置技能。

适配场景：通用高频复用技能，例如代码格式化、单元测试自动生成、文本内容润色、项目临时日志清理等通用自动化操作。

三大主流工具官方全局路径（Windows/Mac/Linux全平台通用）：

CodeBuddy：~/.codebuddy/skills/
Claude Code：~/.claude/skills/
Cursor：~/.cursor/skills/ 或 ~/.agents/skills/

路径符号说明：统一路径标识 ~ 代表系统当前用户根目录，无需手动逐级查找文件夹，终端和AI工具可自动识别匹配路径。

1.2 项目级 Skill（局部生效）

项目级Skill存放于当前项目根目录，仅对当前项目生效，切换至其他项目后自动失效。核心优势是可跟随项目文件****托管至Git，支持团队同步、共享、统一使用。

适配场景：项目专属定制化技能，例如当前项目代码版本迁移、项目专属编码规范、定制化配置模板生成、项目专属脚本自动化等。

三大主流工具官方项目路径：

CodeBuddy：项目根目录 /.codebuddy/skills/
Claude Code：项目根目录 /.claude/skills/
Cursor：项目根目录 /.cursor/skills/ 或 /.agents/skills/

1.3 两种部署方式对比总结

部署类型	生效范围	适用场景	是否可团队共享	推荐新手使用
用户级（全局）	本机所有项目	通用高频技能、测试新Skill	否（仅本机生效）	✅ 优先推荐
项目级（局部）	仅当前项目	项目专属规范、定制化迁移脚本	✅ 可随Git同步团队	后期进阶使用

二、Skill 标准目录结构（官方规范）

Skill有一条强制官方规范：一个技能对应一个独立专属文件夹，严禁多个不同Skill共用同一个文件夹，避免AI加载错乱、规则冲突。官方提供两套标准目录结构，分别适配新手入门简单场景、企业级复杂商用场景。

2.1 最简结构（新手首选）

该结构为新手首选，适配单流程、轻量化、简单自动化技能，无需额外脚本、参考文档，仅依靠核心配置即可正常运行，覆盖90%的新手入门练习场景。

1 2	你的技能文件夹名/ └── SKILL.md # 唯一核心文件，必需文件

结构说明：技能所有执行规则、操作指令、案例示例、执行流程，全部统一编写在SKILL.md 中，结构轻量化、零冗余、易维护，完全适配新手练手、简单功能开发。

2.2 进阶复杂结构（企业级标准）

该结构为企业级商用标准，适配多步骤长流程、批量自动化、需要脚本辅助、依赖规范模板的复杂技能。所有子文件夹遵循**「按需创建、可选补充」**原则，无需强行搭建空目录。

你的技能文件夹名/
├── SKILL.md        # 核心指令文件（必需，唯一必填文件）
├── scripts/        # 可选：存放可执行脚本（sh/py/bat）
├── references/     # 可选：存放参考规范、文档、接口说明
└── assets/         # 可选：存放模板文件、静态配置、JSON模板