简体中文

English
日本語

简体中文

English
日本語

Skills ​

VJSP 内置Agent Skills功能，，这是一套轻量级开放标准，可通过专业知识库与工作流扩展 AI 智能体的能力边界。

Agent Skills 的定义 ​

Agent Skills 是将领域专业知识、新增能力及可复用工作流进行封装的载体，供智能体调用。其核心结构为一个文件夹，内含 SKILL.md 文件，该文件通过元数据与指令集，定义智能体执行特定任务的流程。

这种设计在保障智能体运行效率的同时，支持按需调取上下文信息。当任务场景与功能模块描述匹配时，智能体将读取完整指令并执行，必要时可加载关联文件或运行内置代码。

核心优势 ​

  • 自文档化特性：开发人员或使用者可直接通过阅读 SKILL.md 文件，掌握模块功能与使用场景，便于审计与迭代优化。

  • 跨平台兼容性：遵循 Agent Skills 规范开发的模块，可在所有兼容该标准的智能体系统中运行。

  • 高扩展性：模块复杂度可灵活调整，既可以是简单文本指令，也可集成脚本、模板与参考资料等资源。

  • 便捷共享性：模块具备可移植性，可在不同项目与开发人员之间快速共享。

VJSP 中 Skill 的运行机制 ​

Skill 分为两种类型：

  • 通用型：在所有运行模式下均可调用

  • 模式专属型：仅在指定模式下加载（如 Code、Architect）

Skill 的完整执行流程如下：

  1. 发现阶段：VJSP 初始化时，自动扫描指定目录下的功能模块

  2. 激活阶段：当目标运行模式启动后，相关功能模块会被纳入系统提示词中

  3. 执行阶段：AI 智能体针对匹配任务，执行功能模块中定义的操作指令

Skill 存储路径 ​

Skill 支持多路径加载，可同时配置个人专属模块与项目级定制指令。

全局 Skill（用户级） ​

全局 Skill 存储在用户主目录下的 .vjsp 文件夹中。

  • Mac 与 Linux 系统：~/.vjsp/skills/

  • Windows 系统：\Users<yourUser>.vjsp\

目录结构示例：

plaintext
~/.vjsp/
├── skills/                    #  通用型 Skill（全模式生效）
│   └── my-skill/
│   │   └── SKILL.md
│   └── another-skill/
│       └── SKILL.md
├── skills-code/              # Code 模式专属 Skill
│   └── refactoring/
│       └── SKILL.md
└── skills-architect/         # Architect 模式专属 Skill
    └── system-design/
        └── SKILL.md

项目 Skill（工作区级） ​

项目 Skill 存储在项目根目录下的 .vjsp/skills/ 文件夹中。

目录结构示例：

plaintext
your-project/
└── .vjsp/
    ├── skills/               # 项目通用型 Skill
    │   └── project-conventions/
    │       └── SKILL.md
    └── skills-code/          # Code 模式专属 Skill
        └── linting-rules/
            └── SKILL.md

模式专属 Skill 的创建方法 ​

若需创建仅在指定模式下生效的 Skill，可按以下命令创建目录：

bash
# 创建 Code 模式专属 Skill
mkdir -p ~/.vjsp/skills-code/typescript-patterns

# 创建 Architect 模式专属 Skill
mkdir -p ~/.vjsp/skills-architect/microservices

目录命名规则为 skills-{mode-slug}，其中 {mode-slug} 需与系统定义的模式 ID 一致（如 code、architect、ask、debug）。

优先权与覆盖 ​

当存在多个同名 Skill 时，VJSP 遵循以下优先级规则加载：

  1. 项目 Skill 优先于全局 Skill：同名情况下，项目级 Skill 将覆盖用户级全局 Skill。

  2. 模式专属 Skill 优先于通用 Skill：在代码模式下，skills-code/ 目录下的 Skill 将覆盖 skills/ 目录下的同名通用 Skill。

基于上述规则，开发者可实现以下灵活配置：

  • 定义全局 Skill 满足个人日常开发需求

  • 在特定项目中通过项目 Skill 覆盖全局配置

  • 针对不同工作模式定制差异化功能

Skill 加载时机 ​

Skill 的扫描与加载操作在以下场景触发：

  • IDE 启动时

  • 重载 IDE 窗口时（如 VS Code 快捷键：Cmd+Shift+P → 执行「Developer: Reload Window」命令）

系统会实时监控 Skill 目录下 SKILL.md 文件的变更，但最稳妥的生效方式是重载 IDE 或 VJSP 插件。

⚠️

新增或修改 Skill 后，必须重载 IDE 才能使变更生效。

符号链接的使用方法 ​

可通过创建符号链接（Symlink），实现 Skill 在多台设备或中央代码仓库间的共享。使用符号链接时需注意：Skill 的 name 字段必须与符号链接的名称保持一致，而非目标目录的名称。

SKILL.md 文件格式 ​

SKILL.md 文件采用 YAML 前置元数据 + Markdown 指令内容的组合格式，结构如下：

markdown
---
name: my-skill-name
description: 简要描述该 Skill 的功能及适用场景
---

# 操作指令
在此处编写面向 AI 智能体的详细执行步骤

满足以下条件时，本指令将被纳入系统提示词：
1.  Skill 存储路径合法，且已被系统成功发现
2.  当前工作模式与 Skill 匹配（或该 Skill 为通用型 Skill）

## 使用示例
可在此处添加示例、规范说明、代码片段等补充内容

前置元数字段说明 ​

遵循 Agent Skills 规范，前置元数据支持以下字段：

字段名是否必填字段描述
name是最大长度 64 字符，仅限小写字母、数字与连字符，且不能以连字符开头或结尾
description是最大长度 1024 字符，用于说明 Skill 的功能及适用场景
license否许可证名称，或指向内置许可证文件的路径
compatibility否运行环境要求（如目标产品、系统依赖包、网络访问权限等）
metadata否自定义键值对，用于存储额外元数据信息

含可选字段的示例 ​

markdown
---
name: pdf-processing
description: 实现 PDF 文件的文本提取、表格识别、表单填充及文档合并功能
license: Apache-2.0
metadata:
    author: example-org
    version: 1.0.0
---

## 文本提取方法
1.  使用 pdfplumber 库完成文本提取工作……

## 表单填充步骤
……

名称匹配规则 ​

在 VJSP 中，name 字段必须与 Skill 所在文件夹的名称完全一致。

✅ 正确示例：

plaintext
skills/
└── frontend-design/
    └── SKILL.md  # name: frontend-design

❌ 错误示例：

plaintext
skills/
└── frontend-design/
    └── SKILL.md  # name: my-frontend-skill （名称不匹配！）

可选内置资源 ​

SKILL.md 是 Skill 目录下的唯一必填文件，此外还可按需添加以下目录，丰富 Skill 的功能：

plaintext
my-skill/
├── SKILL.md           # 必填项：存储指令与元数据
├── scripts/           # 可选：存放可执行代码脚本
├── references/        # 可选：存放参考文档
└── assets/            # 可选：存放模板、资源文件等

这些附加资源可在 Skill 指令中直接引用，支持智能体读取参考文档、执行脚本或调用模板等复杂操作。

Skill 创建示例 ​

  1. 创建 Skill 目录
bash
mkdir -p ~/.vjsp/skills/api-design
  1. 创建 SKILL.md 文件
markdown
---
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：服务器内部错误
  1. 重载 IDE 以加载该 Skill

完成上述步骤后，该 Skill 将在所有工作模式下生效。

故障排查 ​

Skill 无法加载？ ​

  1. 查看输出面板：打开「视图 → 输出」，在下拉菜单中选择「VJSP」，查看与 Skill 相关的错误日志。

  2. 校验前置元数据：确认 name 字段已正确配置，且与文件夹名称完全一致，同时检查 description 字段是否存在。

  3. 重载 IDE：Skill 在软件启动时加载，可通过快捷键 Cmd+Shift+P 执行「Developer: Reload Window」命令触发重载。

  4. 检查文件路径：确保 SKILL.md 文件直接存放在 Skill 目录下，不存在多层嵌套。

常见错误及解决方案 ​

错误提示信息错误原因解决方案
"missing required 'name' field"前置元数据中缺少 name 字段添加 name: your-skill-name 配置
"name doesn't match directory"前置元数据的 name 字段与文件夹名称不匹配修改 name 字段，使其与文件夹名称完全一致
Skill 未显示目录结构不符合规范检查路径是否遵循 skills/skill-name/SKILL.md 格式

相关文档链接 ​

自定义模式 - 创建可调用特定 Skill 的自定义工作模式

自定义指令 - 全局指令与 Skill 级指令的区别与配置方法

自定义规则 - 与 Skill 功能互补的项目级规则配置