Skills

CodeRider 实现了 Agent Skills，这是一种轻量级的开放格式，用于通过专业知识和工作流扩展 AI 智能体的能力。

什么是智能体技能#

技能包（Skill package）包含了领域专家知识、新功能和可重复的工作流。其核心是一个包含 SKILL.md 文件的文件夹，该文件内含元数据和指令，告诉智能体如何执行特定任务。

这种方法能让智能体保持快速响应，同时还能让它们按需获取更多上下文信息。当某项任务与某个技能的描述相匹配时，智能体会将完整的指令读入上下文并遵照执行，还可以根据需要选择性地加载参考文件或执行捆绑代码。

主要优势#

• 自文档化：技能作者或用户可以阅读 SKILL.md 文件并理解其功能，这使得技能易于审计和改进
• 互操作性：技能可在任何实现了代理技能规范的代理上运行
• 可扩展性：技能的复杂程度各异，既可以是简单的文本指令，也可以是捆绑的脚本、模板和参考资料
• 可共享性：技能具有可移植性，能够轻松在项目和开发者之间共享

CodeRider 中的技能如何运作#

技能可以是：

• 通用型 —— 在所有模式下均可使用
• 特定模式型 —— 仅在使用特定模式（例如，代码模式、架构师模式）时加载

工作流程如下：

• 发现：CodeRider 初始化时，会从指定目录扫描技能
• 激活：当某个模式处于活跃状态时，相关技能会被纳入系统提示中
• 执行：AI 智能体会遵循技能的指示来完成适用的任务

技能存放位置#

技能从多个位置加载，既可以加载个人技能，也可以加载项目特定指令。

全局技能（用户级别）#

全局技能位于你的主目录下的.coderider 文件夹中。

• Mac 系统和 Linux 系统：~/.coderider/skills/
• Windows 系统：\Users.coderider\

text
复制
1~/.coderider/
2├── skills/                    # Generic skills (all modes)
3│   ├── my-skill/
4│   │   └── SKILL.md
5│   └── another-skill/
6│       └── SKILL.md
7├── skills-code/              # Code mode only
8│   └── refactoring/
9│       └── SKILL.md
10└── skills-architect/         # Architect mode only
11    └── system-design/
12        └── SKILL.md

项目技能（工作区级别）#

位于你的项目中的.coderider/skills/ 目录下：

text
复制
1your-project/
2└── .ccoderider/
3    ├── skills/               # Generic skills for this project
4    │   └── project-conventions/
5    │       └── SKILL.md
6    └── skills-code/          # Code mode skills for this project
7        └── linting-rules/
8            └── SKILL.md

模式特定技能#

要创建一个仅在特定模式下显示的技能：

text
复制
# For Code mode only
mkdir -p ~/.coderider/skills-code/typescript-patterns

# For Architect mode only
mkdir -p ~/.coderider/skills-architect/microservices

目录命名模式为 skills-{mode-slug}，其中 {mode-slug} 与模式的标识符相匹配（例如，code、architect、ask、debug）。

优先级与覆盖规则#

当多个技能具有相同名称时，CodeRider 会遵循以下优先级规则：

1. 项目技能覆盖全局技能 —— 同名的项目技能具有更高优先级
2. 特定模式的技能覆盖通用技能 —— 在代码模式下，skills - code/ 中的技能会覆盖 skills/ 中同名的技能

这使你能够：

• 定义供个人使用的全局技能
• 在需要时按项目覆盖这些技能
• 为特定模式自定义行为

技能加载#

当 CodeRider 初始化时，技能会被发现：

• 当 VSCode 启动时
• 当你重新加载 VSCode 窗口时（Cmd+Shift+P → “Developer：Reload Window”）

技能目录会监控 SKILL.md 文件的变化。不过，获取新技能最可靠的方法是重新加载 VS 或 CodeRider 扩展。

添加或修改技能需要重新加载 VSCode 才能使更改生效。

使用符号链接#

你可以通过符号链接技能目录，在多台机器之间或从中央仓库共享技能。使用符号链接时，技能的'name'字段必须与 symlink name 匹配，而非目标目录的名称。

SKILL.md 格式#

SKILL.md 文件采用 YAML 前置元数据，其后是包含说明的 Markdown 内容：

text
复制
1---
2name: my-skill-name
3description: A brief description of what this skill does and when to use it
4---
5
6# Instructions
7
8Your detailed instructions for the AI agent go here.
9
10These instructions will be included in the system prompt when:
11
121. The skill is discovered in a valid location
132. The current mode matches (or the skill is generic)
14
15## Example Usage
16
17You can include examples, guidelines, code snippets, etc.

前置内容字段#

根据 Agent Skills specification:

带有可选字段的示例#

text
复制
1---
2name: pdf-processing
3description: Extract text and tables from PDF files, fill forms, merge documents.
4license: Apache-2.0
5metadata:
6    author: example-org
7    version: 1.0.0
8---
9
10## How to extract text
11
121. Use pdfplumber for text extraction...
13
14## How to fill forms
15
16...

姓名匹配规则#

在 CodeRider 中，名称字段必须与父目录名称匹配：

text
复制
1✅ Correct:
2skills/
3└── frontend-design/
4    └── SKILL.md  # name: frontend-design
5
6❌ Incorrect:
7skills/
8└── frontend-design/
9    └── SKILL.md  # name: my-frontend-skill  (doesn't match!)

可选的捆绑资源#

虽然 SKILL.md 是唯一必需的文件，但你也可以选择包含额外的目录来支持你的技能：

text
复制
my-skill/
├── SKILL.md           # Required: instructions + metadata
├── scripts/           # Optional: executable code
├── references/        # Optional: documentation
└── assets/            # Optional: templates, resources

这些附加文件可以从你的技能说明中引用，使代理能够根据需要阅读文档、执行脚本或使用模板。

示例：创建技能#

1. 创建技能目录：

text
复制
mkdir -p ~/.coderider/skills/api-design

2. 创建 SKILL.md 文件：

text
复制
1---
2name: api-design
3description: REST API design best practices and conventions
4---
5
6# API Design Guidelines
7
8When designing REST APIs, follow these conventions:
9
10## URL Structure
11
12- Use plural nouns for resources: `/users`, `/orders`
13- Use kebab-case for multi-word resources: `/order-items`
14- Nest related resources: `/users/{id}/orders`
15
16## HTTP Methods
17
18- GET: Retrieve resources
19- POST: Create new resources
20- PUT: Replace entire resource
21- PATCH: Partial update
22- DELETE: Remove resource
23
24## Response Codes
25
26- 200: Success
27- 201: Created
28- 400: Bad Request
29- 404: Not Found
30- 500: Server Error

3. 重新加载 VSCode 以加载该技能
4. 现在，该技能将在所有模式下可用

发现技能#

您可以通过以下方式发现并安装社区创建的技能：

• 代理技能规范 —— 技能所遵循的开放规范，可实现不同人工智能代理之间的互操作性

故障排除#

技能无法加载？#

1. 检查输出面板：打开 View→Output→从下拉菜单中选择 “CodeRider”。查找与技能相关的错误。
2. 验证前端信息：确保name与目录名称完全匹配，并且存在description 字段。
3. 重新加载 VSCode：技能在启动时加载。使用 Cmd+Shift+P→“Developer：Reload Window” 重新加载扩展。
4. 检查文件位置：确保 SKILL.md 直接位于技能目录内，而不是进一步嵌套。

验证技能是否已激活#

要确认某个技能已正确加载且可供代理使用，您可以直接询问代理。只需发送如下消息：

• “你能访问技能 X 吗？”
• “名为 X 的技能已加载吗？”
• “你有哪些可用的技能？”

智能体会回复有关该技能是否已加载且可访问的信息。这是在添加技能或重新加载 VSCode 后，验证技能是否已激活的最可靠方法。

如果智能体确认该技能可用，您就可以使用它了。如果不可用，请查看上面的故障排除步骤，以识别并解决问题。

常见错误#