Managing Skills

Skills are reusable capability packages. After upload or import, a Skill first enters the Skill Library. It can then be enabled by default, built into an agent, or selected for one chat only.

📋 Table of Contents

What is a Skill
How Skills Become Available
Creating a Skill Package
Uploading Skills
Managing Skills
Using Skills in Agents
Best Practices
Common Issues
Related Resources

🎯 What is a Skill

A Skill is a capability extension package that contains executable code, configurations, and documentation. Skills are deployed to ~/.claude/skills/ when a task starts, extending the agent's capabilities.

Analogy: If a Bot is like a person, Skills are like tools or special training:

Ghost: Person's personality and base knowledge
Skills: Specialized tools and techniques the person can use
Bot: Complete person with tools

Examples of Skills:

Python debugging tools
Code formatters and linters
API testing utilities
Database query helpers
Custom workflow automation

🧭 How Skills Become Available

The Skill Library answers "which Skills can I use?" Availability answers "where will these Skills be used?"

Availability	Meaning	When it applies
Default Enabled Skills	Follows the current user	Automatically available with default, system, shared, and self-created agents
Agent Built-in	Follows the agent	Automatically available after choosing that agent; cannot be removed from chat
This Chat Only	Follows the current chat or task	Applies after selecting the Skill from the chat input Skill button

Rules:

New personal uploads enter the Skill Library and are automatically enabled by default for the uploader.
New group uploads belong to the group, but are automatically enabled by default only for the uploader.
Enabling a group Skill by default affects only you, not other group members.
System and library Skills are not automatically enabled by default; enable them manually when needed.
Existing Skills are not automatically enabled by default after upgrade.

📦 Creating a Skill Package

Requirements

A Skill must be packaged as a ZIP file containing:

SKILL.md (required): Documentation with YAML frontmatter
Other files: Scripts, configurations, assets, etc.

SKILL.md Format

---
description: "Brief description of what this skill does"
version: "1.0.0"
author: "Your Name"
tags: ["category1", "category2"]
---

# Skill Name

## Overview

Detailed description of the skill's functionality.

## Usage

How to use this skill...

## Examples

Example code or commands...

YAML Frontmatter Fields

Field	Required	Description	Example
`description`	Yes	Brief skill description	"Python debugging tool with breakpoint support"
`version`	No	Semantic version number	"1.0.0", "2.3.1"
`author`	No	Author name or organization	"WeCode Team", "Your Name"
`tags`	No	Category tags (array)	["python", "debugging", "development"]

Directory Structure Example

my-skill.zip
├── SKILL.md                 # Required: Documentation with frontmatter
├── main.py                  # Your skill code
├── config.json              # Configuration file (optional)
├── utils/
│   ├── helper.py
│   └── formatter.py
└── README.md                # Additional docs (optional)

Creating the ZIP Package

Using command line:

cd my-skill-directory
zip -r my-skill.zip .

Important:

Include SKILL.md at the root level or in a subdirectory
Keep file size under 10MB
Avoid including sensitive data (API keys, passwords)
Use relative paths in your code

⬆️ Uploading Skills

Via Web UI

Navigate to Skills Page
- Go to Settings (⚙️)
- Click on "Skills" tab
Upload Skill
- Click "Upload Skill" button
- Enter a unique skill name (e.g., python-debugger)
- Select or drag-and-drop your ZIP file
- Wait for upload to complete
Verify Upload
- Skill card appears in the list
- Check metadata (version, author, tags)
- New personal uploads show "Enabled by Default"

Upload Requirements

File format: Must be a .zip file
File size: Maximum 10MB
Name: Unique identifier (lowercase, hyphens allowed)
SKILL.md: Must be present and valid

Validation

The system validates:

✅ ZIP file format
✅ File size < 10MB
✅ SKILL.md exists
✅ YAML frontmatter is valid
✅ description field is present
✅ No security issues (Zip Slip attacks)

🛠️ Managing Skills

Viewing Skills

The Skills page has two areas:

Default Enabled Skills: Skills that automatically follow you into conversations. You can disable them by default from this list.
Skill Library: All Skills you can use and manage. You can enable Skills by default from here.

When you click Add Default Skill, Wegent lets you choose from all Skills available to you. You do not need to switch to a personal or team source first. Personal, team, system, and library are Skill sources, not ownership of the default-enabled setting.

The Skill Library displays:

Skill name
Description (first 2 lines)
Version, author, tags
Skill source: My Skill, Team Skill, System Skill, or Library Skill
Default enabled status
Last updated time

The resource library asks you to choose a resource type first, such as Skill, Agent, or Model. Source filtering happens inside that type and defaults to "All". When you choose "Team", you can view all teams or pick one team from the dropdown. Source filtering only changes which resources appear in the list; Default Enabled Skills still belong to the current user. Team resources show their owning team on the list item so their source is clear.

Managing Default Enabled Skills

In the Skill Library, use:

Enable by Default: the Skill becomes automatically available when you use default, system, shared, or self-created agents.
Disable by Default: the Skill no longer follows you automatically, but the Skill asset stays in the library.

This only affects the current user. It does not modify agents, system assistants, or group Skill assets.

In Advanced Settings, you can configure each default-enabled Skill further:

Enabled Modes: all modes are enabled by default. Unchecked modes do not auto-enable this Skill.
Enabled Agents: all agents are enabled by default. You can disable all My Agents, Team Agents, or System Agents at once, or disable a single agent.
Force Activate: when enabled, the Skill is injected into task context through preload. When disabled, the Skill remains automatically available but is loaded on demand by the model.

Downloading Skills

Find your skill in the list
Click the download icon (⬇️)
ZIP file is downloaded to your computer

Use case: Backup, share with team, or modify locally

Updating Skills

Click the edit icon (✏️) on a skill card
Upload a new ZIP file
Name and namespace cannot be changed
Metadata is extracted from the new SKILL.md

Note: All Bots using this skill will get the updated version on next task start.

Deleting Skills

Click the delete icon (🗑️) on a skill card
Confirm deletion in the dialog

Important:

⚠️ Cannot delete skills referenced by Bots/Ghosts
Remove skill from all Bots first
Error message shows which Bots are using the skill

🤖 Using Skills in Agents

Associating Skills with Agents

Edit Agent
- Go to Settings > Agents
- Click edit on an Agent
Add Skills
- Find the "Skills" section (below Agent Config)
- Click the dropdown to see available skills
- Select skills to add
- Skills appear as removable tags
Save Agent
- Click "Save" button
- Skills are now built into that agent

If you only want a Skill to be automatically available for you across conversations, use "Enable by Default" in the Skill Library instead of copying a system agent.

Via YAML Configuration

apiVersion: agent.wecode.io/v1
kind: Ghost
metadata:
  name: developer-ghost
  namespace: default
spec:
  systemPrompt: "You are a senior developer..."
  mcpServers:
    github:
      command: docker
      args: [...]
  skills:
    - python-debugger # Skill name
    - code-formatter
    - api-tester

How Skills Are Deployed

When a task starts:

Executor fetches Bot configuration including skills list
Downloads each skill from the API
Extracts ZIP files to ~/.claude/skills/{skill-name}/
Claude Code loads skills automatically
Agent can use skill capabilities during task execution

Deployment path example:

~/.claude/skills/
├── python-debugger/
│   ├── SKILL.md
│   ├── main.py
│   └── utils/
├── code-formatter/
│   ├── SKILL.md
│   └── formatter.py
└── api-tester/
    ├── SKILL.md
    └── test_runner.py

💡 Best Practices

Creating Skills

Clear Documentation
- Write comprehensive SKILL.md
- Include usage examples
- Document dependencies
Semantic Versioning
- Use version numbers: MAJOR.MINOR.PATCH
- Increment major for breaking changes
- Increment minor for new features
- Increment patch for bug fixes
Meaningful Tags
- Use descriptive category tags
- Examples: ["python", "testing"], ["nodejs", "linting"]
- Helps with discovery and organization
Keep It Focused
- One skill = one specific capability
- Don't create monolithic skills
- Easier to maintain and reuse

Managing Skills

Naming Convention
- Use lowercase with hyphens: my-skill-name
- Be descriptive: python-unit-test-runner vs runner
- Include language/framework if relevant
Version Control
- Update version number when modifying
- Keep old versions for rollback (download before update)
- Document changes in SKILL.md
Security
- Never include API keys or passwords
- Use environment variables for secrets
- Review ZIP contents before uploading
Size Optimization
- Remove unnecessary files
- Compress assets when possible
- Stay well under 10MB limit

Using Skills

Test Individually
- Create a Bot with one skill first
- Verify it works correctly
- Then combine multiple skills
Document Dependencies
- Note which skills work together
- Document any conflicts
- Update Bot descriptions
Monitor Usage
- Check which Bots use each skill
- Remove unused skills
- Keep skills up to date

❓ Common Issues

Upload Failures

Problem: "SKILL.md not found in ZIP package"

✅ Ensure SKILL.md exists at root or in subdirectory
✅ Check file name is exactly SKILL.md (case-sensitive)

Problem: "Invalid YAML frontmatter"

✅ Verify YAML syntax between --- markers
✅ Ensure description field is present
✅ Check for proper indentation

Problem: "File size exceeds 10MB"

✅ Remove unnecessary files
✅ Compress large assets
✅ Split into multiple smaller skills

Deletion Issues

Problem: "Cannot delete Skill referenced by Ghosts"

✅ Check error message for Bot/Ghost names
✅ Edit those Bots to remove the skill
✅ Then delete the skill

Deployment Issues

Problem: Skill not available in task

✅ Verify skill is associated with Bot
✅ Check task logs for download errors
✅ Ensure skill status is "Available"

Problem: "Unsafe file path detected in ZIP"

✅ Don't use ../ in file paths
✅ Don't use absolute paths like /etc/
✅ Use only relative paths within the ZIP

Documentation

YAML Specification - Skill
Agent Settings - Configure agents and bots with skills

External Resources

Examples

Coming soon: Wegent Skills Repository
Community-contributed skills
Pre-built skill templates

🎓 Quick Start Example

1. Create a Simple Skill

Create a directory structure:

hello-skill/
├── SKILL.md
└── hello.py

SKILL.md:

---
description: "A simple hello world skill"
version: "1.0.0"
author: "Your Name"
tags: ["example", "tutorial"]
---

# Hello Skill

A simple example skill that prints a greeting.

## Usage

This skill provides a hello() function that can be called by the agent.

hello.py:

def hello(name="World"):
    return f"Hello, {name}!"

if __name__ == "__main__":
    print(hello())

2. Package the Skill

cd hello-skill
zip -r hello-skill.zip .

3. Upload to Wegent

Go to Settings > Skills
Click "Upload Skill"
Name: hello-skill
Upload hello-skill.zip
Wait for success message

4. Use in a Bot

Go to Settings > Bots
Edit or create a Bot
Scroll to "Skills" section
Select hello-skill
Save Bot

5. Test in a Task

Create a task using this Bot and ask it to use the hello skill!

Need Help?

Check Common Issues
Review YAML Specification
Ask in Wegent community forums

📋 Table of Contents​

🎯 What is a Skill​

🧭 How Skills Become Available​

📦 Creating a Skill Package​

Requirements​

SKILL.md Format​

YAML Frontmatter Fields​

Directory Structure Example​

Creating the ZIP Package​

⬆️ Uploading Skills​

Via Web UI​

Upload Requirements​

Validation​

🛠️ Managing Skills​

Viewing Skills​

Managing Default Enabled Skills​

Downloading Skills​

Updating Skills​

Deleting Skills​

🤖 Using Skills in Agents​

Associating Skills with Agents​

Via YAML Configuration​

How Skills Are Deployed​

💡 Best Practices​

Creating Skills​

Managing Skills​

Using Skills​

❓ Common Issues​

Upload Failures​

Deletion Issues​

Deployment Issues​

🔗 Related Resources​

Documentation​

External Resources​

Examples​

🎓 Quick Start Example​

1. Create a Simple Skill​

2. Package the Skill​

3. Upload to Wegent​

4. Use in a Bot​

5. Test in a Task​

📋 Table of Contents

🎯 What is a Skill

🧭 How Skills Become Available

📦 Creating a Skill Package

Requirements

SKILL.md Format

YAML Frontmatter Fields

Directory Structure Example

Creating the ZIP Package

⬆️ Uploading Skills

Via Web UI

Upload Requirements

Validation

🛠️ Managing Skills

Viewing Skills

Managing Default Enabled Skills

Downloading Skills

Updating Skills

Deleting Skills

🤖 Using Skills in Agents

Associating Skills with Agents

Via YAML Configuration

How Skills Are Deployed

💡 Best Practices

Creating Skills

Managing Skills

Using Skills

❓ Common Issues

Upload Failures

Deletion Issues

Deployment Issues

🔗 Related Resources

Documentation

External Resources

Examples

🎓 Quick Start Example

1. Create a Simple Skill

2. Package the Skill

3. Upload to Wegent

4. Use in a Bot

5. Test in a Task