agent-skills 在 Cursor 中的接入实战：skills 目录同步与 .mdc 项目规则配置

agent-skills 在 Cursor 中的接入实战skills 目录同步与 .mdc 项目规则配置【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills本文以 agent-skills 仓库的 docs/cursor-setup.md 为主体讲解如何将这套面向 AI 编码代理的工程工作流技能包接入 Cursor用.cursor/skills/承载完整技能工作流、用.cursor/rules/*.mdc承载简短策略并给出同步命令、规则文件格式、验证步骤与排错方法。读完后你能在任何仓库中独立完成一次可复现的 Cursor agent-skills 配置并理解技能路由背后的 frontmatter 契约。Cursor 当前的两级上下文模型rules 与 skillsCursor 将上下文约束拆成两层agent-skills 的接入方式就是围绕这两层展开的层级路径职责项目规则Project rules.cursor/rules/*.mdc始终生效或按文件范围生效的指令alwaysApply、globs项目技能Project skills.cursor/skills/skill-name/SKILL.mdAgent 自动发现的工作流当任务与技能description匹配时被读取用户规则User rulesCursor Settings → Rules账号级别的策略用户技能User skills可选~/.cursor/skills/在所有工作区全局可用的技能Rules 与 skills 的分工Rules—— 简短、稳定的策略例如“使用约定式提交”“为公开 Python API 添加类型注解”。原则是一个文件只写一个关注点避免粘贴大段指南。Skills—— 来自本仓库的分步流程test-driven-development、code-review-and-quality等。不要把整个SKILL.md正文复制进 rules那会让.cursor/skills/与规则文件重复维护同一份内容白白消耗上下文窗口。遗留方案对照新配置应避开遗留做法推荐替代根目录.cursorrules文件.cursor/rules/*.mdc把SKILL.md复制进.cursor/rules/放在.cursor/skills/name/SKILL.md“把 10 个技能都设为 always-on 规则”12 条精简的alwaysApply路由规则 按需加载的技能推荐的项目目录布局agent-skills 的 docs/cursor-setup.md 给出的目标结构如下agent-skills/可以是 git submodule 或 vendored clone仅作上游源your-project/ ├── .cursor/ │ ├── rules/ # 简短的 .mdc 策略你自己编写 │ │ └── agent-skills.mdc # 可选一条“使用项目技能”的路由指引 │ └── skills/ # Cursor Agent 实际加载的内容 │ ├── using-agent-skills/ │ ├── test-driven-development/ │ ├── code-review-and-quality/ │ └── … # 从 agent-skills 同步 你自己的技能 └── agent-skills/ # 可选git submodule 或 vendor clone └── skills/ # 仅作为上游源关键原则对 Agent 而言事实源source of truth是.cursor/skills/。仓库里的agent-skills/skills/或克隆的上游 addyosmani/agent-skills 仓库只是上游——必须把它同步进.cursor/skills/而不是只改上游就期望 Cursor 能看到。这与上游仓库的实际组织方式一致从 README.md 的项目结构看skills/下每个技能一个目录、目录内唯一必需文件是SKILL.md配套可选材料放在技能目录内的references/或附加 markdown 文件中例如 skills/constraint-driven-development/references/floor-guard.md、skills/idea-refine/frameworks.md这些都会随目录一起被rsync带进.cursor/skills/。安装把 skills 同步进.cursor/skills/从本地 agent-skills 克隆同步首次完整同步克隆位于项目根目录或其他位置均可mkdir -p .cursor/skills rsync -a /path/to/agent-skills/skills/ .cursor/skills/首次复制但不覆盖已有自定义技能保留你手写的同名技能rsync -a --ignore-existing /path/to/agent-skills/skills/ .cursor/skills/上游更新后重新同步rsync -a /path/to/agent-skills/skills/ .cursor/skills/SKILL.md 的 frontmatter 契约每个技能目录必须包含带 YAML frontmatter 的SKILL.md最少包含--- name: test-driven-development description: Drives development with tests. Use when implementing logic, fixing bugs, or changing behavior. ---Cursor 依据description及相关元数据判断何时应用某个技能。这条约束在上游的 docs/skill-anatomy.md 中有完整的格式规范结合源码可以确认几个影响 Cursor 实际行为的细节name必须是小写连字符命名且与目录名一致。以 skills/test-driven-development/SKILL.md 为例目录名、name字段、Cursor 技能列表里显示的名字三者完全对齐description上限 1024 字符写法是“第三人称说明技能做什么 一个或多个 Use when 触发条件”要同时讲清what和when不要在 description 里概括流程步骤。skill-anatomy 明确解释description 会被注入系统提示若其中包含过程摘要Agent 可能照着摘要执行而不再读取完整SKILL.md——这正是“路由靠 description、正文靠按需加载”这一 Cursor 模型得以成立的前提。最小项目规则.cursor/rules/agent-skills.mdc创建一个.cursor/rules/agent-skills.mdc作为技能的“路由入口”原文档给出的完整示例--- description: Use agent-skills workflows from .cursor/skills alwaysApply: true --- Before non-trivial technical work: 1. Route via .cursor/skills/using-agent-skills/SKILL.md. 2. Read and follow the matching skill under .cursor/skills/name/SKILL.md. 3. Open reference.md in that folder when the skill links to it. 4. Prefer project skills over guessing; user does not need to say read skill each time.仓库特定的规范代码风格、语言约定、技术栈应写成独立的.mdc文件每个文件聚焦一个主题。规则文件的标准格式--- description: Shown in Cursor rule UI alwaysApply: false globs: **/*.{ts,tsx} --- # Your rule content各 frontmatter 字段的用途字段用途alwaysApply: true本项目的所有对话都注入该规则globs上下文里出现匹配文件时注入alwaysApply: false且无 globsAgent 按需请求 / 在 Cursor UI 中手动启用的规则注意第 1 条路由规则指向的 skills/using-agent-skills/SKILL.md 是技能包中的“元技能”从源码看它内置了一棵完整的任务发现树Task arrives → 按开发阶段分支到interview-me/spec-driven-development/test-driven-development/code-review-and-quality等具体技能并定义了六条全局运行行为声明假设、主动管理困惑、必要时反驳、保持简洁、范围纪律、验证优先。这正是 Cursor 侧只放一条薄路由规则、把厚重流程留在技能正文里的设计意图。用户级技能可选把希望全局生效的技能复制或安装到~/.cursor/skills/下适合放与技术栈相关、但不属于 agent-skills 的通用指南例如某种语言的模式库。对于当前仓库的工作流.cursor/skills/中的项目级技能具有优先地位。验证接入是否生效Settings → Rules项目里的.mdc文件应出现在规则列表中Agent 对话来自.cursor/skills/的技能应出现在技能列表中取决于你的 Cursor 版本是否暴露该 UI行为验证执行一个能映射到某技能的任务例如“先写测试再加一个功能”且不点名任何文件——路由正常时Agent 应自行打开test-driven-development技能。Agent 使用技能的四步路由接入完成后Agent 侧的使用模型是Discover发现——using-agent-skills元技能把任务阶段映射到技能名Read读取—— 完整流程在.cursor/skills/name/SKILL.mdDeep dive深入—— 当技能声明指向支撑材料时读取该目录内的reference.md、references/*.md或关联清单。从源码结构看这类按需加载是普遍存在的skills/idea-refine/附带frameworks.md、examples.md、refinement-criteria.mdskills/constraint-driven-development/references/下挂有专题参考文件它们不会常驻上下文只在技能流程需要时才被读入Combine组合—— 例如一个 API 切片可以组合incremental-implementationapi-and-interface-design。如果 Agent 走偏显式短语仍然有效“follow TDD”、“use code-review-and-quality”。阶段 → 技能速查表你正在…对应技能澄清需求interview-me、idea-refine、spec-driven-development规划任务planning-and-task-breakdown实现代码incremental-implementation、frontend-ui-engineering、api-and-interface-design测试test-driven-development、browser-testing-with-devtools调试debugging-and-error-recovery评审code-review-and-quality、code-simplification安全 / 性能security-and-hardening、performance-optimizationGit / CI / 发布git-workflow-and-versioning、ci-cd-and-automation、shipping-and-launch完整的技能树以仓库内 skills/using-agent-skills/SKILL.md 为准其中还给出了一个完整特性的典型生命周期序列interview-me → idea-refine → spec-driven-development → planning-and-task-breakdown → … → code-review-and-quality → … → shipping-and-launch共 16 步并说明“并非每个任务都需要全部技能”。反模式不要做什么原文档列出的反模式与替代做法避免替代做法把所有技能粘贴进一条规则同步到.cursor/skills/维护两份互相漂移的副本从上游rsync把.cursor/skills/提交进版本库大量alwaysApply: true规则一条路由规则 按 glob 聚焦的规则只依赖.cursorrules迁移到.mdc skills期望agent-skills/agents/*.md被自动加载粘贴进对话或提炼成一条短规则上下文预算管理技巧always-on 规则保持最小只放路由 12 条不可妥协的硬约束长清单交给技能冗长的检查表和“借口反驳表”rationalization tables留在技能正文里靠 description 路由按需加载按需添加阶段性 globs 规则例如仅在涉及 Python 时**/*.py或组件目录**/components/**时生效验证步骤被跳过时用技能名在对话里提醒nudgeAgent 回到流程。agents/ 目录在 Cursor 中不会被自动加载agent-skills/agents/下是四个预配置的角色persona定义文件例如 agents/code-reviewer.mdSenior Staff Engineer 视角的五维评审框架、agents/security-auditor.md、agents/test-engineer.md、agents/web-performance-auditor.md。它们在 Cursor 中不会自动加载可选的处理方式有三种引用对应的等价技能如 code reviewer 对应code-review-and-quality把角色 markdown 一次性粘贴进对话用于单次专项评审从中提炼一个简短清单做成.mdc规则。从 agents/code-reviewer.md 的 frontmatter 可以看到这些角色文件同样遵循namedescription的格式正文包含完整的评审框架Correctness / Readability / Architecture / Security / Performance 五个维度因此“提炼短清单”或“粘贴全文进对话”两种方式都有现成素材可用。故障排查症状检查点技能从未被使用.cursor/skills/name/下是否有SKILL.mdfrontmatter 的description是否有效规则被忽略扩展名是否为.mdcalwaysApply/globs是否正确工作流过期重新从agent-skills/skills/执行rsync指令重复出现从规则中删掉技能正文内容只保留单一事实源选错了技能收窄自定义技能的description在对话中点名提醒其中“指令重复”一项呼应了 skill-anatomy 的原则description 只负责触发流程正文只应存在于技能目录内一份。新项目接入清单mkdir -p .cursor/skills并从agent-skills/skills/同步可选添加带路由指引的.cursor/rules/agent-skills.mdc把仓库特定规则写成独立的小.mdc文件将.cursor/skills/和.cursor/rules/提交进版本库团队共享同一套行为除非遗留工具强制要求跳过巨型.cursorrules文件延伸阅读docs/getting-started.md —— 与任意 Agent 的通用接入方式、最小三技能组合与生命周期加载顺序README.md —— 全部 25 个技能24 个生命周期技能 1 个元技能总览以及 Cursor 章节对本指南的引用docs/skill-anatomy.md ——SKILL.md的完整格式规范frontmatter 契约与标准章节docs/adoption-guide.md —— 绿地项目与既有代码库的两种落地路径【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考