欢迎光临
我们一直在努力

从 Rules 到 Skills:用 Anthropic 开放标准重构你的 AI 编程工作流

从 Rules 到 Skills:用 Anthropic 开放标准重构你的 AI 编程工作流

基于 Java 后端 Skills 实战(REST API / Service / 异常处理 / 校验 / 日志 / MyBatis-Plus)

本文适合作为一篇 CSDN 博客发布,系统介绍 Skills 标准、工具链以及一个完整的 Java 后端 Skills 实战项目。

GitHub 项目地址:https://github.com/lambert0529/skills

说明:本文档基于 Anthropic Skills 开放标准编写,全面介绍 Skills 的概念、使用方法和最佳实践,并结合 Java 后端 Skills 进行实战演示。适用于所有支持该标准的 AI 编程助手(Cursor、Claude Code、Windsurf、Aider 等)。


📖 目录

  • Skill 是什么
  • Skill vs Rules vs BusAgent vs Commands vs MCP 对比
  • 各大编辑工具对 Skills 的支持和适配进度
  • Skills 使用技巧和细节
  • OpenSkills 使用细节
  • 本项目开发的 Skills

  • 1. Skill 是什么

    1.1 定义

    Skills(技能) 是由 Anthropic 提出的一个开放标准(Open Standard),用于增强 AI Agent 在特定任务上的能力。Skills 是一种可重用、结构化的知识包,封装了特定领域知识、工作流程、脚本和最佳实践,供 Agent 根据任务需要按需加载,而不是始终包含在上下文中。

    1.2 核心特性

    • 🌐 开放标准:由 Anthropic 定义,遵循统一的规范格式
    • 🔄 跨平台兼容:可在多个 AI 编程助手间共享(Cursor、Claude Code、Windsurf、Aider 等)
    • 📦 渐进式加载:采用"渐进式披露(Progressive Disclosure)"机制,节省上下文窗口
    • 🔧 可扩展:支持自定义命令、钩子脚本、领域知识等多种内容类型
    • 🎯 智能匹配:Agent 自动扫描技能描述,根据任务相关性匹配技能

    1.3 标准结构

    根据 Anthropic Skills 开放标准,每个 Skill 应该包含以下结构:

    skill-name/
    ├── SKILL.md # 必需:技能定义(YAML front matter + Markdown)
    ├── scripts/ # 可选:脚本文件(自动化任务逻辑)
    ├── assets/ # 可选:资源文件(用于输出的模板、图标、字体等)
    └── references/ # 可选:文档和参考资料(按需加载)

    1.4 SKILL.md 格式

    YAML Front Matter(必需):


    name: skillname # 必需:技能名称(kebab-case)
    description: 技能描述 # 必需:技能描述(用于 Agent 匹配任务,应包含具体使用场景)

    Markdown 内容:

    • 技能说明、使用方法、行为定义等
    • 应保持简洁(<500行,推荐<300行)
    • 详细内容放在 references/ 中

    1.5 渐进式披露原则

    Skills 使用三级加载系统来高效管理上下文:

  • Metadata(name + description) – 始终在上下文中(~100 词)
  • SKILL.md body – 当技能触发时加载(<5k 词,建议 <300 行)
  • Bundled resources – 按 Claude 需要时加载(无限制,因为脚本可以执行而不读入上下文窗口)
  • 关键原则:

    • 保持 SKILL.md 简洁,只包含核心流程和指导
    • 详细内容移到 references/ 文件
    • 使用链接引用详细内容,确保读者知道它们存在以及何时使用
    • 避免深层嵌套引用 – 保持 references 从 SKILL.md 一级深度

    2. Skill vs Rules vs BusAgent vs Commands vs MCP 对比

    2.1 概念对比表

    特性Skills(技能)Rules(规则)BusAgentCommands(命令)MCP(模型上下文协议)
    标准/协议 Anthropic Skills 开放标准 平台特定(如 Cursor Rules) 平台特定 平台特定(Slash Commands) Model Context Protocol 开放协议
    核心作用 教 Agent 如何做,提供知识、流程、判断、风格 对 Agent 输出/行为的静态约束或规范 业务代理,封装业务逻辑 简单的 prompt 模板,快速执行特定行为 给 Agent 能做什么动作,访问外部系统/数据/工具
    执行能力 本身不直接执行外部动作(除非 Skill 内含脚本并被执行) 没有执行外部工具能力,仅约束文本/输出内容 可执行业务逻辑和外部调用 无执行能力,仅提供 prompt 模板 本质是执行动作/调用外部逻辑
    文件结构 目录形式:SKILL.md + 脚本/模板/资源 .mdc 或 .md 文件 配置文件或代码 单个 Markdown 文件 JSON 配置
    加载方式 渐进式加载(按需,扫描名称和描述后决定) 静态加载(总是或按规则) 按需加载 手动显式调用(用户输入 /command) 按需调用外部服务
    上下文消耗 低(渐进式披露,仅在需要时载入) 中等(常驻文本,可能消耗较多 Token) 中等(按需加载) 低(仅在调用时加载) 工具描述占用部分,工具调用开销较大
    自动发现 ✅ 支持(Agent 扫描匹配) ✅ 支持(自动包含) ✅ 支持(按需匹配) ❌ 不支持(需显式调用) ✅ 支持(按需调用)
    使用场景 特定任务的专业能力、工作流程、领域知识 编码规范、团队标准、全局规则 业务场景封装、复杂业务流程 快速简短、频繁重用的命令 访问外部数据源、执行外部工具、查询数据库
    存放位置 .agent/skills/(通用)或 .claude/skills/ .cursor/rules/*.mdc 或 AGENTS.md 平台特定目录 .claude/commands/ 或 .cursor/commands/ .cursor/mcp.json 或 ~/.cursor/mcp.json
    文件格式 SKILL.md(YAML front matter + Markdown,标准格式) .mdc 或 .md(平台特定) 配置文件或代码 .md(简单 Markdown,无特殊格式要求) JSON 配置
    触发方式 Agent 扫描匹配或 /skill-name 命令 自动包含或按匹配规则 按业务场景匹配 用户显式输入 /command-name Agent 需要时调用
    可移植性 高(开放标准,跨平台兼容) 较有限(平台专有格式) 较有限(平台专有) 较有限(平台专有,但格式简单) 较好(协议标准,但不同 Agent 支持程度可能不同)
    创建难度 中等(需要 SKILL.md + 可选脚本/资源) 最基础(创建门槛低) 较高(需要业务逻辑设计) 低(只需一个 Markdown 文件) 较高(需搭建 server、定义 schema、权限、安全、认证等)
    安全性 如果 Skill 中含脚本,有代码执行权限,需要谨慎信任来源 相对安全(只包含文本规则,没有执行外部代码) 中等(可执行业务逻辑) 相对安全(仅文本 prompt,无脚本执行) 动作调用本身含有安全性风险,权限控制必需
    复杂度支持 高(支持多文件、脚本、复杂流程) 低(静态规则) 高(支持复杂业务逻辑) 低(简单 prompt 模板) 高(可连接复杂外部系统)

    2.2 详细对比

    Skills(技能)- Anthropic 开放标准

    定义:Skills 是由 Anthropic 定义的开放标准,用于封装复杂的能力包,包含 SKILL.md 文件以及可选的脚本、模板、参考资料等资源。

    优势:

    • ✅ 开放标准:遵循 Anthropic Skills 规范,跨平台兼容
    • ✅ 节省上下文:渐进式加载机制,只在需要时加载
    • ✅ 灵活性强:可以根据任务动态选择使用
    • ✅ 可复用:一次定义,可在多个项目、多个 Agent 平台间共享
    • ✅ 模块化:每个技能专注一个功能领域,职责清晰

    适用场景:

    • 代码审查、测试生成、文档生成等特定任务
    • 需要复杂工作流程的场景
    • 团队共享的专业知识和最佳实践
    • 跨项目、跨平台的知识复用
    Rules(规则)

    定义:Rules 是对 Agent 输出/行为的静态约束或规范,通常以 .mdc 或 .md 文件形式存在。

    优势:

    • ✅ 持续生效:始终包含在上下文中
    • ✅ 稳定性高:功能成熟,广泛使用
    • ✅ 自动应用:无需手动触发

    劣势:

    • ⚠️ 占用上下文:始终加载,可能占用较多 token
    • ⚠️ 不够灵活:所有对话都会包含,即使不相关

    适用场景:

    • 编码规范、命名约定
    • 项目结构说明
    • 团队工作流程
    • 需要持续指导的规则
    BusAgent(业务代理)

    定义:BusAgent 是平台特定的业务代理机制,用于封装业务逻辑和复杂业务流程。

    优势:

    • ✅ 业务逻辑封装:可以封装复杂的业务场景
    • ✅ 可执行:可以执行业务逻辑和外部调用

    劣势:

    • ⚠️ 平台特定:不同平台实现不同
    • ⚠️ 复杂度高:需要业务逻辑设计

    适用场景:

    • 复杂业务流程封装
    • 业务场景自动化
    • 平台特定的业务逻辑
    Commands(命令)- Slash Commands

    定义:Commands(也称为 Slash Commands)是简单的 prompt 模板,通常是一个 Markdown 文件,用于快速执行特定行为。

    优势:

    • ✅ 简单快速:只需一个 Markdown 文件,编辑方便
    • ✅ 可控性强:用户明确触发,行为可预测
    • ✅ 安全性好:内容简单,无复杂依赖,审查容易

    劣势:

    • ⚠️ 灵活性低:不支持复杂流程、多个文件、标准化资源
    • ⚠️ 自动化能力差:需要用户每次明确调用,不能基于上下文自动匹配

    适用场景:

    • 快速简短、频繁重用的命令
    • 简单的 prompt 模板,如 /review code、/optimize
    • 不需要复杂脚本或流程的行为
    MCP(Model Context Protocol)

    定义:MCP 是 Model Context Protocol 的缩写,是一个开放协议,用于连接外部系统、获取实时数据、执行外部工具。

    优势:

    • ✅ 连接外部系统:可以访问数据库、API、文件系统等
    • ✅ 实时数据:获取最新的外部数据
    • ✅ 工具集成:可以调用外部工具和脚本

    劣势:

    • ⚠️ 需要配置:需要设置 MCP 服务器
    • ⚠️ 依赖外部:需要外部系统可用
    • ⚠️ 性能考虑:网络调用可能较慢

    适用场景:

    • 访问数据库查询数据
    • 调用外部 API
    • 执行系统命令
    • 读取文件系统

    2.3 融合趋势

    重要更新:在 Claude Code 2.1.3+ 版本中,Anthropic 正在合并 Commands 和 Skills,将两者视为同一种能力单元,主要区别仅在"调用方式"(显式 vs 自动触发)。

    合并后的特点:

    • 无论是 .claude/commands/ 还是 .claude/skills/ 中的内容,从系统角度看都是 Skill
    • 可以通过 Settings 或 frontmatter 设定是否允许自动触发
    • 支持 user-invocable、disable-model-invocation 等设置

    建议:

    • 新项目建议直接使用 Skills 标准格式
    • 简单命令可以创建为 Skill,但设置 disable-model-invocation: true 仅允许手动调用
    • 复杂工作流使用完整的 Skills 结构,支持自动发现

    2.4 使用建议

    组合使用(最佳实践):

    • Rules:放置编码规范、架构约束等静态规则(平台特定)
    • Commands:放置简单、频繁重用的快捷命令(平台特定,或迁移到 Skills)
    • Skills:放置可执行的工作流、特定领域的动态知识(跨平台标准,推荐)
    • MCP:连接外部系统,获取实时数据(开放协议)
    • BusAgent:封装复杂业务逻辑(平台特定)

    最强组合:Skills + MCP + Rules 并用

    • Skills 提供何时做什么以及如何做的知识
    • MCP 提供能做什么动作的能力
    • Rules 提供必须遵循的约束和规范
    • Commands 提供快速执行的简单命令(可选,建议迁移到 Skills)
    • BusAgent 提供业务逻辑封装(平台特定)

    3. 各大编辑工具对 Skills 的支持和适配进度

    3.1 适配情况总览

    工具/平台支持状态支持类型使用方式限制与注意事项
    Claude Code ✅ 完全支持 原生支持 Anthropic Skills 标准 文件系统目录结构(.claude/skills/ 或 .agent/skills/) 自动触发机制依赖技能描述质量
    Claude.ai(Web) ✅ 完全支持 预构建 Skills + 自定义 Skills 设置中启用,上传 ZIP 或使用 Partner Skills 需开启 Code Execution 权限
    Claude API ✅ 完全支持 通过 API 管理 Skills /v1/skills 端点上传管理 需要 API 密钥和相应权限
    Cursor ⚠️ Beta/Nightly 通过 OpenSkills 和 AGENTS.md 使用 OpenSkills CLI 同步到 .cursor/rules/AGENTS.md 功能尚未完全稳定,自动触发不保证
    Windsurf ✅ 支持 原生支持 Anthropic Skills 标准 类似 Claude Code 的文件系统结构 社区反馈较少,功能相对稳定
    Aider ✅ 支持 原生支持 Anthropic Skills 标准 文件系统目录结构 支持自动发现和手动调用
    VS Code(GitHub Copilot) ✅ 已集成 通过 Microsoft 集成 在 VS Code 中定义 Skills 需要 GitHub Copilot 订阅
    OpenAI Codex CLI ✅ 部分支持 Skills 框架(类似 Anthropic) ~/.codex/skills/ 目录 格式与 Anthropic 高度一致,但功能较新
    ChatGPT ✅ 部分支持 Code Interpreter 预置 + 自定义 通过设置上传 Skills 触发机制不如 Claude 稳定

    3.2 Claude Code 详细支持情况

    Claude Code 是 Anthropic 官方开发的 AI 编程助手,对 Skills 标准提供最完整和原生的支持。

    支持的功能:

    • ✅ 自动发现:Agent 自动扫描技能目录,根据任务相关性匹配技能
    • ✅ 自动触发:当任务匹配技能描述时,自动加载技能内容
    • ✅ 手动调用:支持通过 /skill-name 命令手动触发
    • ✅ 目录结构:支持 .claude/skills/ 和 .agent/skills/ 目录
    • ✅ 完整格式:支持 SKILL.md + 脚本 + 模板 + 资源的完整结构
    • ✅ 组织级管理:支持团队共享和组织级 Skills

    使用方式:

    • 项目级 Skills:项目根目录/.claude/skills/ 或 .agent/skills/
    • 全局 Skills:~/.claude/skills/ 或 ~/.agent/skills/

    3.3 Cursor 支持情况

    支持程度:⚠️ Beta/Nightly 阶段,功能尚未完全稳定

    实现方式:

    • 通过 OpenSkills CLI 工具管理技能
    • 使用 AGENTS.md 文件让 Agent 发现可用技能
    • Agent 通过 openskills read 命令加载技能内容

    使用流程:

  • 安装技能:使用 OpenSkills 安装到 .agent/skills/ 目录
  • 同步到 AGENTS.md:执行 openskills sync -o .cursor/rules/AGENTS.md
  • Agent 发现:Cursor Agent 读取 AGENTS.md 中的技能列表
  • 技能加载:Agent 执行 openskills read <skill-name> 加载技能
  • 限制与注意事项:

    • ⚠️ 自动触发不稳定:Agent 可能不会自动识别和使用技能
    • ⚠️ 需要手动提示:建议在任务中明确提到技能名称
    • ⚠️ Nightly 版本:需要切换到 Cursor Nightly 渠道
    • ⚠️ 权限问题:使用 openskills 而非 npx openskills 避免权限错误

    3.4 其他工具支持情况

    Windsurf
    • ✅ 原生支持:原生支持 Anthropic Skills 标准
    • ✅ 自动发现:支持自动发现和手动调用
    • ✅ 文件系统结构:类似 Claude Code 的文件系统结构
    Aider
    • ✅ 原生支持:原生支持 Anthropic Skills 标准
    • ✅ 自动发现:支持自动发现和手动调用
    • ✅ 目录结构:支持 .aider/skills/ 目录
    VS Code(GitHub Copilot)
    • ✅ 已集成:Microsoft 在 Anthropic 宣布开放标准后迅速集成
    • ⚠️ 需要订阅:需要 GitHub Copilot 订阅
    • ✅ 在 VS Code 中定义:支持在 VS Code 中定义和使用 Skills

    3.5 时间线与标准化进程

    关键时间节点
    时间事件影响
    2025 年 10 月中旬 Anthropic 正式在 Claude 中推出 Agent Skills 功能 首次公开发布 Skills 概念
    2025 年 12 月 18 日 Anthropic 将 Agent Skills 发布为开放标准(agent-skills.io) 标准化进程,Microsoft、OpenAI 等迅速集成
    Claude Code v2.1.1 开始合并 Commands 和 Skills 统一底层工具
    Claude Code v2.1.3 Commands 和 Skills 完全合并 用户可见的融合完成
    2026 年 1 月 多个平台宣布支持或正在集成 生态逐步完善
    标准化影响

    开放标准发布后的影响:

    • ✅ Microsoft:在 VS Code 和 GitHub 中迅速集成
    • ✅ OpenAI:在 ChatGPT 和 Codex CLI 中开始支持
    • ✅ 第三方工具:Cursor、Windsurf、Aider 等逐步支持
    • ✅ 企业工具:Notion、Figma、Atlassian 等提供 Partner Skills

    4. Skills 使用技巧和细节

    4.1 技能描述优化技巧

    关键原则:技能描述是 Agent 决定是否使用技能的主要依据,必须清晰、具体、包含使用场景。

    好的描述示例


    name: javarestapidesign
    description: 生成符合主流规范的 Java RESTful API 接口设计,包括 Controller、DTO、统一响应格式、异常处理等。使用场景:(1) 创建新的 REST API 接口,(2) 设计 Controller 层代码,(3) 生成 API 相关的 DTO 类,(4) 审查或优化现有 API 设计,(5) 需要遵循 Spring Boot 最佳实践和 RESTful 规范时

    特点:

    • ✅ 明确说明技能功能
    • ✅ 列出具体使用场景
    • ✅ 包含关键词(REST API、Controller、DTO、Spring Boot)
    • ✅ 描述长度适中(100-200 词)
    不好的描述示例


    name: javaapi
    description: 生成 API 代码

    问题:

    • ❌ 描述过于简单,缺少使用场景
    • ❌ 关键词不够具体
    • ❌ Agent 难以判断何时使用

    4.2 SKILL.md 内容组织技巧

    保持简洁

    原则:SKILL.md 应保持简洁(<500行,推荐<300行),只包含核心流程和指导。

    好的结构:

    # Skill 名称

    ## 快速开始
    核心流程和步骤…

    ## 详细参考
    – 详细内容见 [references/xxx.md](references/xxx.md)
    – 代码模板见 `assets/xxx.java`

    使用链接引用

    原则:详细内容放在 references/ 中,SKILL.md 中使用链接引用。

    示例:

    ## 详细参考

    – **RESTful 模式**:见 [references/restful-patterns.md](references/restful-patterns.md)
    – **DTO 模式**:见 [references/dto-patterns.md](references/dto-patterns.md)
    – **代码模板**:见 `assets/ControllerTemplate.java`

    4.3 目录结构最佳实践

    标准目录结构

    skill-name/
    ├── SKILL.md # 必需:技能定义(简洁,<300行)
    ├── scripts/ # 可选:可执行脚本
    ├── assets/ # 可选:用于输出的模板、图标等
    └── references/ # 可选:按需加载的文档和参考资料

    目录用途说明
    • SKILL.md:核心定义,应保持简洁
    • scripts/:可执行脚本,用于自动化任务
    • assets/:不加载到上下文,用于输出的文件(模板、图标等)
    • references/:按需加载的文档和参考资料

    4.4 触发技巧

    自然语言触发(推荐)

    方式:在任务描述中使用技能相关的关键词。

    示例:

    用户:为用户管理创建 REST API 接口

    Agent:
    1. 识别到需要"REST API 设计"任务
    2. 在 AGENTS.md 中找到 java-rest-api-design 技能
    3. 执行:openskills read java-rest-api-design
    4. 按照技能定义生成 Controller 和 DTO 代码

    明确指定技能

    方式:在任务中明确提到技能名称。

    示例:

    用户:使用 java-rest-api-design 技能为用户管理创建 REST API

    使用命令触发

    方式:使用 /skill-name 命令手动触发。

    示例:

    用户:/java-rest-api-design 为用户管理创建 REST API

    4.5 调试技巧

    验证技能是否被使用

    方法 1:观察 Agent 响应

    • 如果 Agent 使用了技能,应该提到技能名称
    • 展示技能加载过程
    • 按照技能定义的格式输出

    方法 2:查看执行日志

    • 如果 Agent 执行了 openskills read,应该能看到命令执行记录
    • 技能内容加载过程

    方法 3:对比输出格式

    • 如果 Agent 使用了技能,输出应该符合技能定义的格式
    常见问题排查

    问题 1:技能没有被自动触发

    解决方案:

  • 优化技能描述:在 YAML front matter 的 description 字段中使用具体、明确的关键词
  • 使用 forced eval hook:在技能中添加评估机制,强制 Agent 评估每个技能是否匹配
  • 手动提示:在任务中明确提到技能名称或相关关键词
  • 问题 2:技能描述没有同步到 AGENTS.md

    解决方案:

    • 确保 SKILL.md 文件包含 YAML front matter
    • 确保 name 和 description 字段存在
    • 重新执行 openskills sync

    问题 3:技能内容加载失败

    解决方案:

    • 检查技能文件路径是否正确
    • 确保 openskills 命令可用
    • 检查权限问题

    5. OpenSkills 使用细节

    5.1 什么是 OpenSkills

    OpenSkills 是一个由社区开发的开源 CLI 工具,用于管理和使用遵循 Anthropic Skills 标准的技能。它将 Anthropic 定义的 Skills 开放标准扩展到任何支持的 AI 编程代理中(Cursor、Claude Code、Windsurf、Aider 等)。

    核心价值:

    • 🔧 提供统一的技能管理接口
    • 📦 支持从 Anthropic 官方市场、GitHub 仓库、本地路径安装技能
    • 🔄 自动同步技能信息到 AGENTS.md,供 Agent 发现和使用
    • 🌐 支持多种安装模式(项目级、全局、通用),适配不同使用场景

    5.2 安装 OpenSkills

    前置要求
    • Node.js ≥ v20.6
    • Git(用于从 GitHub 安装技能)
    安装步骤

    # 全局安装 OpenSkills CLI
    npm install -g openskills

    # 验证安装
    openskills –version

    5.3 核心功能

    1. 安装技能(Install)

    # 从 Anthropic 官方市场安装所有技能
    openskills install anthropics/skills

    # 从 GitHub 仓库安装特定技能
    openskills install username/repo-name

    # 从本地路径安装
    openskills install ./local-skill-path

    # 安装到通用目录(多 Agent 共享,推荐)
    openskills install anthropics/skills –universal

    # 全局安装(所有项目共享)
    openskills install anthropics/skills –global

    # 跳过确认提示(适合 CI/CD)
    openskills install anthropics/skills –yes

    ⚠️ 重要:工作目录要求

    • 项目级和通用模式:必须在项目根目录执行
    • 全局模式:可以在任何目录执行
    2. 列出已安装技能(List)

    # 列出当前项目的技能
    openskills list

    # 列出全局技能
    openskills list –global

    # 列出通用技能
    openskills list –universal

    3. 同步技能到 AGENTS.md(Sync)

    # 同步到默认位置
    openskills sync

    # 同步到指定路径(推荐)
    openskills sync -o .cursor/rules/AGENTS.md

    # 同步到通用位置
    openskills sync –universal

    # 跳过确认提示
    openskills sync –yes

    生成的 AGENTS.md 格式:

    <available_skills>
    <skill>
    <name>java-rest-api-design</name>
    <description>生成符合主流规范的 Java RESTful API 接口设计…</description>
    <location>project</location>
    </skill>
    </available_skills>

    4. 读取技能内容(Read)

    # 读取技能内容
    openskills read java-rest-api-design

    # 读取多个技能
    openskills read skill-one,skill-two

    5. 删除技能(Remove)

    # 删除指定技能
    openskills remove <skill-name>

    # 交互式管理(批量删除)
    openskills manage

    5.4 安装模式详解

    模式命令参数安装位置需要项目目录适用场景
    项目级 无参数(默认) 项目目录/.claude/skills/ ✅ 是 项目特定技能
    全局 –global ~/.claude/skills/ ❌ 否 所有项目共享
    通用 –universal 项目目录/.agent/skills/ 或 ~/.agent/skills/ ✅ 是 多 Agent 共享(推荐)

    5.5 目录识别规则

    OpenSkills 只识别以下目录:

    • ✅ .claude/skills/ – Claude 生态技能目录
    • ✅ .agent/skills/ – 通用技能目录(推荐)
    • ❌ .cursor/skills/ – 不被 OpenSkills 识别

    目录查找优先级(从高到低):

  • ./.agent/skills/ – 当前项目的通用技能
  • ~/.agent/skills/ – 全局通用技能
  • ./.claude/skills/ – 当前项目的 Claude 技能
  • ~/.claude/skills/ – 全局 Claude 技能
  • 5.6 常见问题

    Q1: 为什么描述没有同步到 AGENTS.md?

    A: SKILL.md 文件缺少 YAML front matter。需要在文件开头添加:


    name: skillname
    description: 技能描述(应包含具体使用场景,如:使用场景:(1) xxx,(2) xxx)

    注意:根据 Anthropic Skills 规范,frontmatter 只包含 name 和 description,不需要 version 和 tags。

    Q2: 为什么 openskills list 显示没有技能?

    A: 检查技能是否在正确的目录:

    • 确保在项目根目录执行
    • 检查 .agent/skills/ 或 .claude/skills/ 目录
    • 确保 SKILL.md 文件存在
    Q3: 为什么 npx openskills 报权限错误?

    A: 使用全局安装的 openskills 命令,而不是 npx openskills:

    # ✅ 正确
    openskills read java-rest-api-design

    # ❌ 错误(可能权限问题)
    npx openskills read java-rest-api-design


    6. 本项目开发的 Skills

    6.1 项目介绍

    本项目提供了一套完整的 Java 后端开发 Skills,基于主流后端开发规范和 Spring Boot 最佳实践,帮助开发者快速生成符合规范的代码。

    GitHub 地址:https://github.com/lambert0529/skills.git

    Gitee 地址:https://gitee.com/lbl_lambert/skills.git

    6.2 Skills 列表

    本项目已创建了以下 7 个 Java 后端开发 Skills:

    1. java-rest-api-design – RESTful API 设计规范

    功能:

    • 生成符合规范的 RESTful API 接口
    • 创建 Controller 层代码
    • 生成 API 相关的 DTO 类
    • 遵循 Spring Boot 最佳实践和 RESTful 规范

    使用场景:

    • 创建新的 REST API 接口
    • 设计 Controller 层代码
    • 生成 API 相关的 DTO 类
    • 审查或优化现有 API 设计

    目录结构:

    java-rest-api-design/
    ├── SKILL.md (82 行)
    ├── assets/
    │ ├── ControllerTemplate.java
    │ └── CreateRequestTemplate.java
    └── references/
    ├── restful-patterns.md
    ├── dto-patterns.md
    └── example-usage.md

    2. java-service-layer – Service 层开发规范

    功能:

    • 生成 Service 接口和实现类
    • 实现业务逻辑和事务管理
    • 遵循分层架构最佳实践

    使用场景:

    • 创建新的 Service 层代码
    • 实现业务逻辑处理
    • 设计 Service 接口
    • 优化现有 Service 代码

    目录结构:

    java-service-layer/
    ├── SKILL.md (88 行)
    ├── assets/
    │ ├── ServiceInterfaceTemplate.java
    │ └── ServiceImplTemplate.java
    └── references/
    ├── transaction-management.md
    └── business-logic-patterns.md

    3. java-exception-handling – 异常处理规范

    功能:

    • 设计全局异常处理器
    • 定义错误码和异常类
    • 统一异常响应格式

    使用场景:

    • 设计异常处理机制
    • 创建自定义异常类
    • 实现全局异常处理器
    • 定义错误码体系

    目录结构:

    java-exception-handling/
    ├── SKILL.md (86 行)
    ├── assets/
    │ ├── GlobalExceptionHandlerTemplate.java
    │ └── ErrorCodeExample.java
    └── references/
    ├── exception-classes.md
    └── error-code-definition.md

    4. java-validation – 参数校验规范

    功能:

    • 为请求参数添加校验注解
    • 创建自定义校验器
    • 实现分组校验

    使用场景:

    • 为创建用户请求添加参数校验
    • 创建自定义校验器
    • 实现分组校验
    • 优化现有校验逻辑

    目录结构:

    java-validation/
    ├── SKILL.md (127 行)
    ├── assets/
    │ └── CustomValidatorTemplate.java
    └── references/
    ├── bean-validation-annotations.md
    ├── group-validation.md
    └── validation-examples.md

    5. java-response-wrapper – 统一响应格式规范

    功能:

    • 创建统一响应包装类
    • 实现分页响应格式
    • 统一 API 返回格式

    使用场景:

    • 设计统一响应格式
    • 创建响应包装类
    • 实现分页响应
    • 统一 API 返回格式

    目录结构:

    java-response-wrapper/
    ├── SKILL.md (80 行)
    ├── assets/
    │ ├── ResultTemplate.java
    │ └── PageResultTemplate.java
    └── references/
    ├── response-formats.md
    └── page-result.md

    6. java-logging – 日志记录规范

    功能:

    • 配置日志格式和级别
    • 实现日志脱敏
    • 遵循日志记录最佳实践

    使用场景:

    • 为 Service 添加日志记录
    • 配置日志格式
    • 实现日志脱敏
    • 优化现有日志记录

    目录结构:

    java-logging/
    ├── SKILL.md (120 行)
    ├── assets/
    │ ├── logback-example.xml
    │ └── desensitization-utils.java
    └── references/
    ├── log-levels.md
    └── log-format.md

    7. java-mybatis-plus-generator – MyBatis-Plus 代码生成

    功能:

    • 生成基于 MyBatis-Plus 的完整分层代码
    • 创建 Controller、Service、Mapper 层
    • 集成 PageHelper 分页功能

    使用场景:

    • 创建基于 MyBatis-Plus 的 CRUD 操作
    • 生成分页查询功能
    • 实现 Service 层和 DAO 层代码
    • 生成 Mapper XML 文件

    目录结构:

    java-mybatis-plus-generator/
    ├── SKILL.md (102 行)
    ├── assets/
    │ ├── EntityTemplate.java
    │ ├── MapperInterfaceTemplate.java
    │ ├── MapperXmlTemplate.xml
    │ ├── ServiceInterfaceTemplate.java
    │ ├── ServiceImplTemplate.java
    │ └── ControllerTemplate.java
    └── references/
    ├── pagehelper-usage.md
    ├── query-wrapper.md
    └── generation-examples.md

    6.3 安装和使用

    从 GitHub 安装

    # 安装本项目所有 Skills
    openskills install lambert0529/skills –universal

    # 或者指定 java 目录
    openskills install lambert0529/skills/java –universal

    从本地安装

    # 从本地 java 目录安装
    openskills install ./java –universal

    同步到 AGENTS.md

    # 同步到 Cursor
    openskills sync –yes -o .cursor/rules/AGENTS.md

    使用示例

    在 Cursor 中:

    "为用户管理创建 REST API 接口"
    "创建用户 Service 层,包含事务管理"
    "设计异常处理机制"
    "为创建用户请求添加参数校验"
    "设计统一响应格式"
    "为 Service 添加日志记录"
    "为用户管理生成基于 MyBatis-Plus 的 CRUD 代码"

    6.4 规范覆盖范围

    这些 Skills 覆盖了 Java 后端开发的核心规范:

    • ✅ RESTful API 设计
    • ✅ 分层架构(Controller-Service-Repository)
    • ✅ 异常处理机制
    • ✅ 参数校验
    • ✅ 统一响应格式
    • ✅ 日志记录
    • ✅ 事务管理
    • ✅ MyBatis-Plus 集成
    • ✅ 代码规范

    6.5 项目特点

    • ✅ 符合规范:完全遵循 Anthropic Skills 开放标准
    • ✅ 渐进式披露:SKILL.md 简洁(80-127 行),详细内容在 references 中
    • ✅ 跨平台兼容:可在 Cursor、Claude Code、Windsurf、Aider 等平台使用
    • ✅ 最佳实践:基于 Spring Boot 和主流后端开发规范
    • ✅ 开箱即用:提供完整的代码模板和参考资料

    6.6 贡献和反馈

    欢迎贡献和反馈!

    • GitHub Issues:https://github.com/lambert0529/skills/issues
    • Pull Requests:欢迎提交 PR 改进 Skills
    • Star:如果觉得有用,请给项目一个 Star ⭐

    📋 快速参考

    常用命令

    # 安装技能
    openskills install lambert0529/skills –universal

    # 列出技能
    openskills list

    # 同步到 AGENTS.md
    openskills sync –yes -o .cursor/rules/AGENTS.md

    # 读取技能
    openskills read java-rest-api-design

    # 删除技能
    openskills remove old-skill

    目录结构

    项目根目录/
    ├── .agent/
    │ └── skills/ # 通用技能(推荐)
    │ ├── java-rest-api-design/
    │ │ └── SKILL.md
    │ └── …
    ├── .claude/
    │ └── skills/ # Claude 技能
    └── .cursor/
    ├── rules/
    │ └── AGENTS.md # 技能列表(同步生成)
    └── skills/ # 手动创建(不被 OpenSkills 识别)


    🔗 相关资源

    标准与规范

    • Anthropic Skills 标准:https://github.com/anthropics/skills(官方标准定义)
    • Anthropic Skills 市场:https://github.com/anthropics/skills(官方技能库)

    工具与实现

    • OpenSkills GitHub:https://github.com/numman-ali/openskills(开源 CLI 工具)
    • OpenSkills 文档:https://github.com/numman-ali/openskills#readme

    平台支持

    • Cursor 文档:https://docs.cursor.com(Skills 支持情况请查看最新文档)
    • Claude Code:原生支持 Anthropic Skills 标准
    • Windsurf:支持 Anthropic Skills 标准
    • Aider:支持 Anthropic Skills 标准

    项目资源

    • 本项目 GitHub:https://github.com/lambert0529/skills.git
    • 本项目 Gitee:https://gitee.com/lbl_lambert/skills.git
    • 项目 README:./README.md
    • Java Skills README:./java/README.md
    赞(0)
    未经允许不得转载:171主机测评 » 从 Rules 到 Skills:用 Anthropic 开放标准重构你的 AI 编程工作流
    分享到: 更多 (0)

    评论 抢沙发

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址