Managing Skills

Skills are Claude Code capability extension packages that add specialized functionality to your Bots. This guide will teach you how to upload, manage, and use Skills in Wegent.

📋 Table of Contents

What is a Skill
Creating a Skill Package
Uploading Skills
Managing Skills
Using Skills in Bots
Best Practices
Common Issues
Related Resources

🎯 What is a Skill

A Skill is a Claude Code 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

📦 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)
- Status shows "Available"

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

Skills List displays:

Skill name
Description (first 2 lines)
Version, author, tags
File size and status
Last updated time

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 Bots

Associating Skills with Bots

Edit Bot
- Go to Settings > Bots
- Click edit on a Bot
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 Bot
- Click "Save" button
- Skills are now associated with the Bot

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​

📦 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​

Downloading Skills​

Updating Skills​

Deleting Skills​

🤖 Using Skills in Bots​

Associating Skills with Bots​

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

📦 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

Downloading Skills

Updating Skills

Deleting Skills

🤖 Using Skills in Bots

Associating Skills with Bots

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