技能

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

什么是 Agent Skills？

Agent Skills 将领域专业知识、新功能和可重复的工作流程打包，供代理使用。核心来说，技能是一个包含 SKILL.md 文件的文件夹，该文件包含元数据和指令，告诉代理如何执行特定任务。

这种方法使代理保持快速，同时按需访问更多上下文。当任务与技能的描述匹配时，代理会将完整的指令读入上下文并遵循它们——可选择加载引用的文件或执行打包的代码。

主要优势

自文档化：技能作者或用户可以阅读 SKILL.md 文件并了解其作用，使技能易于审计和改进
可互操作：技能可在任何实现 Agent Skills 规范的代理中工作
可扩展：技能的复杂度可以从简单的文本指令到打包的脚本、模板和参考资料
可共享：技能是可移植的，可以轻松地在项目和开发人员之间共享

技能在 YouCode 中的工作方式

技能可以是：

通用 - 在所有模式下可用
模式特定 - 仅在使用特定模式时加载（例如 code、architect）

工作流程如下：

发现：YouCode 初始化时从指定目录扫描技能。此时仅读取元数据（名称、描述和文件路径）——而不是完整指令。
提示包含：当模式处于活动状态时，相关技能的元数据将包含在系统提示中。代理会看到可用技能及其描述的列表。
按需加载：当代理确定任务与技能描述匹配时，它会将完整的 SKILL.md 文件读入上下文并遵循指令。

代理如何决定使用技能

代理（LLM）根据技能的 description 字段决定是否使用技能。没有关键词匹配或语义搜索——代理会评估您的请求与所有可用技能的描述，并确定是否"明确且毫不含糊地适用"。

这意味着：

描述措辞很重要：编写与用户表达请求的方式相匹配的描述
显式调用始终有效：说"使用 api-design 技能"会触发它，因为代理会看到技能名称
模糊的描述会导致不确定的匹配：具体说明何时应使用该技能

技能位置

技能从多个位置加载，允许同时使用个人技能和项目特定指令。

全局技能（用户级）

全局技能位于主目录中的 .youcode 目录内。

Mac 和 Linux：~/.youcode/skills/
Windows：\\Users\\<yourUser>\\.youcode\\

~/.youcode/
├── skills/                    # 通用技能（所有模式）
│   ├── my-skill/
│   │   └── SKILL.md
│   └── another-skill/
│       └── SKILL.md
├── skills-code/              # 仅代码模式
│   └── refactoring/
│       └── SKILL.md
└── skills-architect/         # 仅架构师模式
    └── system-design/
        └── SKILL.md

项目技能（工作区级）

位于项目内的 .youcode/skills/ 中：

your-project/
└── .youcode/
    ├── skills/               # 此项目的通用技能
    │   └── project-conventions/
    │       └── SKILL.md
    └── skills-code/          # 此项目的代码模式技能
        └── linting-rules/
            └── SKILL.md

模式特定技能

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

# 仅用于代码模式
mkdir -p ~/.youcode/skills-code/typescript-patterns

# 仅用于架构师模式
mkdir -p ~/.youcode/skills-architect/microservices

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

优先级和覆盖

当多个技能共享相同名称时，YouCode 使用以下优先级规则：

项目技能覆盖全局技能 - 具有相同名称的项目技能优先
模式特定技能覆盖通用技能 - 在代码模式下，skills-code/ 中的技能覆盖 skills/ 中的相同技能

这允许您：

定义个人使用的全局技能
根据需要按项目覆盖它们
为特定模式自定义行为

技能何时加载

技能在 YouCode 初始化时被发现：

VSCode 启动时
重新加载 VSCode 窗口时（Cmd+Shift+P → "Developer: Reload Window"）

技能目录受监控以检测 SKILL.md 文件的更改。但是，获取新技能的最可靠方法是重新加载 VS 或 YouCode 扩展。

备注

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

使用符号链接

您可以对技能目录进行符号链接，以便在机器之间或从中央存储库共享技能。使用符号链接时，技能的 name 字段必须匹配__符号链接名称__，而不是目标目录名称。

SKILL.md 格式

SKILL.md 文件使用 YAML 前置内容，后跟包含指令的 Markdown 内容：

---
name: my-skill-name
description: 对此技能的作用以及使用时间的简要描述
---

# 指令

AI 代理的详细指令放在这里。

当代理根据您的请求与上述描述匹配决定使用该技能时，
将阅读此内容。

## 使用示例

您可以包括示例、指南、代码片段等。

前置内容字段

根据 Agent Skills 规范：

字段	必需	描述
`name`	是	最多 64 个字符。仅小写字母、数字和连字符。不能以连字符开头或结尾。
`description`	是	最多 1024 个字符。描述技能的作用以及何时使用它。
`license`	否	许可证名称或对打包许可证文件的引用
`compatibility`	否	环境要求（预期产品、系统包、网络访问等）
`metadata`	否	任意键值映射以获取其他元数据

包含可选字段的示例

---
name: pdf-processing
description: 从 PDF 文件中提取文本和表格、填写表单、合并文档。
license: Apache-2.0
metadata:
    author: example-org
    version: 1.0.0
---

## 如何提取文本

1. 使用 pdfplumber 进行文本提取...

## 如何填写表单

...

名称匹配规则

在 YouCode 中，name 字段__必须匹配__父目录名称：

✅ 正确：
skills/
└── frontend-design/
    └── SKILL.md  # name: frontend-design

❌ 错误：
skills/
└── frontend-design/
    └── SKILL.md  # name: my-frontend-skill  （不匹配！）

可选的打包资源

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

my-skill/
├── SKILL.md           # 必需：指令 + 元数据
├── scripts/           # 可选：可执行代码
├── references/        # 可选：文档
└── assets/            # 可选：模板、资源

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

示例：创建技能

创建技能目录：
```
mkdir -p ~/.youcode/skills/api-design
```

创建 SKILL.md：

---
name: api-design
description: REST API 设计最佳实践和约定
---

# API 设计指南

设计 REST API 时，请遵循以下约定：

## URL 结构

- 对资源使用复数名词：`/users`、`/orders`
- 对多词资源使用 kebab-case：`/order-items`
- 嵌套相关资源：`/users/{id}/orders`

## HTTP 方法

- GET：检索资源
- POST：创建新资源
- PUT：替换整个资源
- PATCH：部分更新
- DELETE：删除资源

## 响应代码

- 200：成功
- 201：已创建
- 400：错误请求
- 404：未找到
- 500：服务器错误

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

故障排除

技能未加载？

检查输出面板：打开 视图 → 输出 → 从下拉列表中选择 "YouCode"。查找与技能相关的错误。
验证前置内容：确保 name 与目录名称完全匹配，并且 description 存在。
重新加载 VSCode：技能在启动时加载。使用 Cmd+Shift+P → "Developer: Reload Window"。
检查文件位置：确保 SKILL.md 直接位于技能目录内，而不是嵌套得更深。

验证技能是否可用

要确认技能是否正确加载并可由代理使用，您可以直接询问代理。只需发送如下消息：

"您可以访问技能 X 吗？"
"名为 X 的技能是否已加载？"
"您有哪些可用技能？"

代理会响应有关技能是否已加载并可访问的信息。这是在添加技能或重新加载 VSCode 后验证技能可用的最可靠方法。

如果代理确认技能可用，您就可以使用它了。如果没有，请检查上述故障排除步骤以识别并解决问题。

检查技能是否被使用

要查看技能在对话期间是否实际被使用，请在聊天中查找针对 SKILL.md 文件的 read_file 工具调用。当代理决定使用技能时，它会将完整的技能文件读入上下文——这在对话中显示为文件读取操作。

目前没有专用的 UI 指示器显示"技能 X 已激活"。read_file 调用是确认技能已被使用的最可靠方法。

常见错误

错误	原因	解决方案
"缺少必需的 'name' 字段"	前置内容中没有 `name`	添加 `name: your-skill-name`
"名称与目录不匹配"	前置内容与文件夹名称不匹配	使 `name` 完全匹配
技能未出现	目录结构错误	验证路径遵循 `skills/skill-name/SKILL.md`

什么是 Agent Skills？​

主要优势​

技能在 YouCode 中的工作方式​

代理如何决定使用技能​

技能位置​

全局技能（用户级）​

项目技能（工作区级）​

模式特定技能​

优先级和覆盖​

技能何时加载​

使用符号链接​

SKILL.md 格式​

前置内容字段​

包含可选字段的示例​

名称匹配规则​

可选的打包资源​

示例：创建技能​

故障排除​

技能未加载？​

验证技能是否可用​

检查技能是否被使用​

常见错误​

相关功能​