Skills

VJSP features built-in Agent Skills, a lightweight open standard that extends AI agents' capabilities through domain knowledge bases and workflows.

Definition of Agent Skills

Agent Skills are containers that encapsulate domain expertise, new capabilities, and reusable workflows for AI agents to invoke. Their core structure is a folder containing a SKILL.md file, which defines the process for agents to execute specific tasks through metadata and instruction sets.

This design ensures agent operational efficiency while supporting on-demand context retrieval. When task scenarios match functional module descriptions, agents read complete instructions and execute them, loading associated files or running embedded code as needed.

Core Advantages

• Self-documenting: Developers or users can directly understand module functionality and usage scenarios by reading the SKILL.md file, facilitating auditing and iterative optimization.

• Cross-platform compatibility: Modules developed according to the Agent Skills specification can run in all agent systems compatible with this standard.

• High extensibility: Module complexity is flexible, ranging from simple text instructions to integrated scripts, templates, and reference materials.

• Easy sharing: Modules are portable and can be quickly shared across different projects and developers.

Skill Execution Mechanism in VJSP

Skills are categorized into two types:

• Universal: Can be invoked in all operating modes
• Mode-specific: Loaded only in designated modes (e.g., Code, Architect)

The complete Skill execution flow is as follows:

1. Discovery phase: During initialization, VJSP automatically scans specified directories for functional modules
2. Activation phase: When the target operating mode starts, relevant functional modules are incorporated into the system prompt
3. Execution phase: AI agents execute operation instructions defined in functional modules for matching tasks

Skill Storage Paths

Skills support multi-path loading, allowing simultaneous configuration of personal modules and project-level custom instructions.

Global Skills (User-level)

Global Skills are stored in the .vjsp folder under the user's home directory:

• macOS/Linux: ~/.vjsp/skills/
• Windows: \Users<yourUser>.vjsp\

Directory structure example:

~/.vjsp/
├── skills/                    # Universal Skills (effective in all modes)
│   └── my-skill/
│   │   └── SKILL.md
│   └── another-skill/
│       └── SKILL.md
├── skills-code/              # Code mode exclusive Skills
│   └── refactoring/
│       └── SKILL.md
└── skills-architect/         # Architect mode exclusive Skills
    └── system-design/
        └── SKILL.md

Project Skills (Workspace-level)

Project Skills are stored in the .vjsp/skills/ folder at the project root:

your-project/
└── .vjsp/
    ├── skills/               # Project universal Skills
    │   └── project-conventions/
    │       └── SKILL.md
    └── skills-code/          # Code mode exclusive Skills
        └── linting-rules/
            └── SKILL.md

Creating Mode-specific Skills

To create Skills that take effect only in specific modes, create directories using the following commands:

# Create Code mode exclusive Skill
mkdir -p ~/.vjsp/skills-code/typescript-patterns

# Create Architect mode exclusive Skill
mkdir -p ~/.vjsp/skills-architect/microservices

Directory naming convention: skills-{mode-slug}, where {mode-slug} must match system-defined mode IDs (e.g., code, architect, ask, debug).

Priority and Overriding

When multiple Skills with the same name exist, VJSP follows these priority rules for loading:

1. Project Skills override Global Skills: For same-named Skills, project-level Skills override user-level global Skills.
2. Mode-specific Skills override Universal Skills: In Code mode, Skills in the skills-code/ directory override same-named universal Skills in the skills/ directory.

Based on these rules, developers can implement flexible configurations:

• Define global Skills to meet personal daily development needs
• Override global configurations with project Skills in specific projects
• Customize differentiated functions for different work modes

Skill Loading Timing

Skill scanning and loading operations are triggered in the following scenarios:

• When IDE starts
• When reloading IDE window (e.g., VS Code shortcut: Cmd+Shift+P → execute "Developer: Reload Window" command)

The system monitors changes to SKILL.md files in Skill directories in real time, but the most reliable way to take effect is to reload the IDE or VJSP plugin.

⚠️

After adding or modifying Skills, you must reload the IDE for changes to take effect.

Using Symbolic Links

Symbolic links (Symlink) can be created to share Skills across multiple devices or central code repositories. When using symbolic links, note: The name field of the Skill must match the name of the symbolic link, not the target directory name.

SKILL.md File Format

The SKILL.md file adopts a combined format of YAML front matter + Markdown instruction content, structured as follows:

---
name: my-skill-name
description: Briefly describe the Skill's functionality and applicable scenarios
---

# Operation Instructions
Write detailed execution steps for AI agents here

This instruction will be included in the system prompt when:
1.  Skill storage path is valid and has been successfully discovered by the system
2.  Current work mode matches the Skill (or the Skill is universal)

## Usage Examples
Add examples, specifications, code snippets, and other supplementary content here

Front Matter Field Descriptions

Following the Agent Skills specification, the front matter supports the following fields:

Field Name	Required	Description
name	Yes	Max length 64 characters, only lowercase letters, numbers, and hyphens; cannot start or end with a hyphen
description	Yes	Max length 1024 characters, used to describe the Skill's functionality and applicable scenarios
license	No	License name, or path to built-in license file
compatibility	No	Runtime environment requirements (e.g., target product, system dependencies, network access permissions)
metadata	No	Custom key-value pairs for storing additional metadata information

Example with Optional Fields

---
name: pdf-processing
description: Implements text extraction, table recognition, form filling, and document merging for PDF files
license: Apache-2.0
metadata:
    author: example-org
    version: 1.0.0
---

## Text Extraction Method
1.  Use pdfplumber library for text extraction work……

## Form Filling Steps
……

Name Matching Rule

In VJSP, the name field must exactly match the name of the folder where the Skill resides.

✅ Correct example:

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

❌ Incorrect example:

skills/
└── frontend-design/
    └── SKILL.md  # name: my-frontend-skill (Name mismatch!)

Optional Built-in Resources

SKILL.md is the only required file in the Skill directory. Additionally, the following directories can be added as needed to enrich Skill functionality:

my-skill/
├── SKILL.md           # Required: stores instructions and metadata
├── scripts/           # Optional: stores executable code scripts
├── references/        # Optional: stores reference documents
└── assets/            # Optional: stores templates, resource files, etc.

These additional resources can be directly referenced in Skill instructions, supporting agents in reading reference documents, executing scripts, or invoking templates for complex operations.

Skill Creation Example

1. Create Skill directory

mkdir -p ~/.vjsp/skills/api-design

2. Create SKILL.md file

---
name: api-design
description: Provides best practices and standards for REST API design
---

# API Design Specifications

When designing REST APIs, follow these conventions:

## URL Structure Specifications
- Resource paths use plural nouns: `/users`, `/orders`
- Multi-word resource names use kebab-case: `/order-items`
- Related resources use nested structure: `/users/{id}/orders`

## HTTP Method Usage Specifications
- GET: Query resources
- POST: Create new resources
- PUT: Full update of resources
- PATCH: Partial update of resources
- DELETE: Delete resources

## Response Status Code Specifications
- 200: Request successful
- 201: Resource created successfully
- 400: Invalid request
- 404: Resource not found
- 500: Internal server error

3. Reload IDE to load the Skill

After completing these steps, this Skill will take effect in all operating modes.

Troubleshooting

Skill fails to load?

1. View Output panel: Open "View → Output", select "VJSP" from the dropdown menu, and check error logs related to Skills.

2. Validate front matter: Confirm the name field is correctly configured and exactly matches the folder name, while checking if the description field exists.

3. Reload IDE: Skills are loaded when the software starts; you can trigger a reload via shortcut Cmd+Shift+P → execute "Developer: Reload Window" command.

4. Check file path: Ensure the SKILL.md file is placed directly in the Skill directory without multi-level nesting.

Common Errors and Solutions

Error Message	Cause	Solution
"missing required 'name' field"	Missing name field in front matter	Add name: your-skill-name configuration
"name doesn't match directory"	name field in front matter doesn't match folder name	Modify name field to exactly match folder name
Skill not displayed	Directory structure doesn't comply with specifications	Check if path follows skills/skill-name/SKILL.md format

Related Documentation Links

Custom Modes - Create custom work modes that can invoke specific Skills

Custom Instructions - Differences and configuration methods between global instructions and Skill-level instructions

Custom Rules - Project-level rule configurations that complement Skill functionality