Skills System

Skills extend the agent's capabilities with specialized processing for specific file types and tasks.

Overview

Skills are modular extensions that teach the agent how to handle specific tasks:

• Document Processing: PDF, DOCX, XLSX, PPTX
• Data Transformation: Format conversion, extraction
• Custom Workflows: Project-specific automation

Built-in Skills

Kuse Cowork includes several built-in skills:

PDF Processing

Extract text and analyze PDF documents.

Location: ~/.kuse-cowork/skills/pdf/

Capabilities:

• Extract text content
• Parse tables
• Handle multi-page documents

Usage:

"Extract the text from report.pdf"

DOCX Processing

Work with Microsoft Word documents.

Location: ~/.kuse-cowork/skills/docx/

Capabilities:

• Extract text content
• Preserve formatting info
• Handle embedded images (metadata)

Usage:

"Summarize the content of proposal.docx"

XLSX Processing

Process Excel spreadsheets.

Location: ~/.kuse-cowork/skills/xlsx/

Capabilities:

• Read cell data
• Parse multiple sheets
• Handle formulas (values)

Usage:

"Analyze the data in sales.xlsx"

PPTX Processing

Handle PowerPoint presentations.

Location: ~/.kuse-cowork/skills/pptx/

Capabilities:

• Extract slide text
• Read speaker notes
• Parse slide structure

Usage:

"Create an outline from presentation.pptx"

Skill Structure

Each skill follows a standard structure:

~/.kuse-cowork/skills/
└── my-skill/
    ├── SKILL.md        # Skill definition and instructions
    ├── forms.md        # Optional: Input forms
    ├── reference.md    # Optional: Additional documentation
    └── scripts/        # Optional: Executable scripts
        ├── process.py
        └── convert.sh

SKILL.md Format

The main skill definition file:

# My Custom Skill

A brief description of what this skill does.

## Trigger

Keywords or patterns that activate this skill:
- "convert to X"
- "process Y file"

## Instructions

When activated, follow these steps:

1. Read the input file using read_file
2. Run the processing script: `python /skills/my-skill/scripts/process.py`
3. Return the output to the user

## Parameters

- **input_file**: Path to the file to process
- **output_format**: Desired output format

## Examples

### Example 1: Basic Usage
Input: "Process document.pdf"
Action: Run extraction script and return text

### Example 2: With Options
Input: "Process document.pdf as markdown"
Action: Run extraction with markdown formatting

Creating Custom Skills

Step 1: Create Skill Directory

mkdir -p ~/.kuse-cowork/skills/my-skill/scripts

Step 2: Write SKILL.md

# CSV to JSON Converter

Converts CSV files to JSON format.

## Trigger
- "convert csv to json"
- "csv to json"

## Instructions

1. Read the CSV file path from user input
2. Run: `python /skills/csv-converter/scripts/convert.py <input_file>`
3. Return the JSON output

## Parameters
- **input_file**: Path to the CSV file
- **pretty**: Whether to format output (default: true)

Step 3: Create Scripts

#!/usr/bin/env python3
import csv
import json
import sys

def convert(input_file):
    with open(input_file, 'r') as f:
        reader = csv.DictReader(f)
        data = list(reader)
    return json.dumps(data, indent=2)

if __name__ == '__main__':
    if len(sys.argv) < 2:
        print("Usage: convert.py <input_file>")
        sys.exit(1)
    print(convert(sys.argv[1]))

Step 4: Test the Skill

User: "Convert data.csv to JSON"

Agent:
[Reading skill definition]
[Running: python /skills/csv-converter/scripts/convert.py /workspace/data.csv]
[Returning JSON output]

Skill Discovery

The agent discovers skills through:

1. System Prompt: Skills directory is mentioned in the system prompt
2. Automatic Mounting: Skills are mounted at /skills in Docker
3. SKILL.md Parsing: Agent reads skill definitions when needed

Skill Loading Flow

Advanced Skill Features

Dependencies

Skills can specify required packages:

## Dependencies

Python packages (installed in container):
- pandas
- openpyxl

Install command:
`pip install pandas openpyxl`

Multi-Step Processing

Skills can define complex workflows:

## Instructions

### Step 1: Extract
Run: `python /skills/doc-processor/scripts/extract.py <input>`

### Step 2: Transform
Run: `python /skills/doc-processor/scripts/transform.py <extracted_data>`

### Step 3: Format
Run: `python /skills/doc-processor/scripts/format.py <transformed_data>`

Error Handling

Skills can specify error handling:

## Error Handling

If extraction fails:
1. Check file format is supported
2. Try alternative extraction method
3. Report specific error to user

Skill Best Practices

Design Guidelines

Single Responsibility

Each skill should do one thing well.

Clear Triggers

Define specific, unambiguous trigger phrases.

Detailed Instructions

Provide step-by-step instructions the agent can follow.

Script Guidelines

Standalone Scripts

Scripts should work independently with clear input/output.

Error Messages

Provide helpful error messages for common issues.

Standard I/O

Use stdin/stdout for data flow when possible.

Documentation

Include Examples

Show concrete examples of skill usage.

Document Parameters

List all parameters with descriptions and defaults.

Skill Locations

Default Skills

~/.kuse-cowork/skills/
├── pdf/
├── docx/
├── xlsx/
└── pptx/

Custom Skills

Add custom skills in the same directory:

~/.kuse-cowork/skills/
├── pdf/
├── docx/
├── xlsx/
├── pptx/
├── my-custom-skill/
└── another-skill/

Docker Access

All skills are mounted at /skills in containers:

# In Docker container
ls /skills/
# Output: pdf docx xlsx pptx my-custom-skill another-skill

Sharing Skills

Export a Skill

cd ~/.kuse-cowork/skills
zip -r my-skill.zip my-skill/

Import a Skill

cd ~/.kuse-cowork/skills
unzip my-skill.zip

Community Skills

Future versions may support:

• Skill marketplace
• One-click installation
• Version management

Troubleshooting

Skill not detected

1. Verify SKILL.md exists in skill directory
2. Check skill directory is in `~/.kuse-cowork/skills/`
3. Restart Kuse Cowork

Script fails to run

1. Check script has execute permissions
2. Verify shebang line (`#!/usr/bin/env python3`)
3. Test script manually in Docker

Dependencies not found

1. Install deps in Docker: `docker_run pip install <package>`
2. Add installation to script
3. Use custom Docker image with deps

Next Steps

• Tools Reference - Built-in tools
• Agent System - How skills are used
• Development Guide - Contributing skills