bob-skill-creator 0.1.0

A Python library for creating, testing, and managing Bob skills

Bob Skill Creator

A Python library for creating, testing, and managing Bob skills programmatically.

Features

• Skill Creation: Build skills programmatically with a fluent API
• Templates: Start from pre-built templates for common skill types
• Validation: Validate skills against best practices and requirements
• Evaluation: Create and manage test cases for skills
• Packaging: Package skills into .skill files for distribution
• CLI: Command-line interface for common operations

Installation

pip install bob-skill-creator

Or install from source:

git clone https://github.com/yourusername/bob-skill-creator.git
cd bob-skill-creator
pip install -e .

Quick Start

Creating a Skill Programmatically

from bob_skill_creator import SkillBuilder

# Create a new skill
skill = (
    SkillBuilder()
    .with_name("my-awesome-skill")
    .with_description("A skill that does awesome things. Use when you need awesome.")
    .from_template("basic")
    .add_section("Usage", "Explain how to use this skill")
    .add_section("Examples", "Show some examples")
    .build()
)

# Save the skill
from pathlib import Path
skill.save(Path("./my-awesome-skill"))

Using the CLI

# Create a new skill from a template (defaults to ~/.bob/skills/my-skill)
bob-skill create my-skill \
  --description "My skill description" \
  --template basic

# Or specify a custom output directory
bob-skill create my-skill \
  --description "My skill description" \
  --template basic \
  --output ./my-skill

# Validate a skill
bob-skill validate ./my-skill

# Package a skill
bob-skill package ./my-skill --output my-skill.skill

# Install a skill
bob-skill install my-skill.skill ~/.bob/skills

Usage Examples

Building a Skill with Resources

from bob_skill_creator import SkillBuilder

builder = SkillBuilder()
builder.with_name("data-processor")
builder.with_description("Process CSV data files efficiently")
builder.from_template("data-processing")

# Add a helper script
builder.add_script("process.py", """
import pandas as pd

def process_csv(input_path, output_path):
    df = pd.read_csv(input_path)
    # Processing logic here
    df.to_csv(output_path, index=False)
""")

# Add reference documentation
builder.add_reference("api.md", """
# API Reference

## Functions

### process_csv(input_path, output_path)
Process a CSV file and save results.
""")

skill = builder.build_and_save(Path("./data-processor"))

Loading and Validating an Existing Skill

from bob_skill_creator import Skill, SkillValidator
from pathlib import Path

# Load a skill
skill = Skill.from_file(Path("./my-skill"))

# Validate it
validator = SkillValidator()
result = validator.validate(skill)

if result.is_valid:
    print("✓ Skill is valid")
else:
    print("✗ Validation failed:")
    for error in result.errors:
        print(f"  - {error}")

Creating Evaluation Test Cases

from bob_skill_creator import SkillEvaluator
from pathlib import Path

# Create evaluator
evaluator = SkillEvaluator("my-skill")

# Add test cases
evaluator.add_eval_case(
    prompt="Process the sales data and generate a report",
    expected_output="A formatted report with sales statistics",
    files=["sales_data.csv"]
)

# Add assertions
evaluator.add_assertion(
    eval_id=0,
    assertion_type="file_exists",
    description="Output report should exist",
    file="report.pdf"
)

# Save evaluation configuration
evaluator.save_to_file(Path("./evals/evals.json"))

Packaging and Distribution

from bob_skill_creator import SkillPackager
from pathlib import Path

# Package a skill
packager = SkillPackager(validate=True)
skill_file = packager.package_from_directory(
    Path("./my-skill"),
    Path("./dist/my-skill.skill")
)

print(f"Packaged to: {skill_file}")

# Unpack a skill
unpacked_dir = packager.unpack(
    Path("./dist/my-skill.skill"),
    Path("./unpacked")
)

Available Templates

• basic: Basic skill template with common sections
• code-generation: Template for code generation skills
• data-processing: Template for data processing skills
• documentation: Template for documentation generation skills

List templates via CLI:

bob-skill list-templates

Skill Structure

A Bob skill consists of:

my-skill/
├── SKILL.md           # Main skill file with YAML frontmatter
├── scripts/           # Executable scripts (optional)
│   └── helper.py
├── references/        # Reference documentation (optional)
│   └── api.md
└── assets/           # Assets like templates, icons (optional)
    └── template.txt

SKILL.md Format

---
name: my-skill
description: What the skill does and when to use it
compatibility:
  tools: ["tool1", "tool2"]
---

## Overview

Skill instructions here...

## Usage

How to use the skill...

## Examples

Example usage...

API Reference

SkillBuilder

Fluent API for building skills:

• with_name(name: str) - Set skill name
• with_description(description: str) - Set description
• with_compatibility(compatibility: dict) - Set compatibility requirements
• with_content(content: str) - Set skill content
• add_section(title: str, content: str, level: int) - Add a section
• add_resource(path: str, content: str) - Add a resource file
• add_script(filename: str, content: str) - Add a script
• add_reference(filename: str, content: str) - Add a reference
• add_asset(filename: str, content: str) - Add an asset
• from_template(template_name: str) - Initialize from template
• build() - Build and return the skill
• build_and_save(output_path: Path) - Build and save to disk

Skill

Core skill class:

• from_file(skill_path: Path) - Load skill from file
• to_markdown() - Convert to SKILL.md format
• save(output_path: Path, include_resources: bool) - Save to disk

SkillValidator

Validate skills:

• validate(skill: Skill) - Validate a skill
• validate_file(skill_path: Path) - Validate from file
• validate_and_raise(skill: Skill) - Validate and raise on error

SkillEvaluator

Create and manage test cases:

• add_eval_case(prompt, expected_output, files, assertions) - Add test case
• add_assertion(eval_id, assertion_type, description, **kwargs) - Add assertion
• load_from_file(evals_file: Path) - Load from evals.json
• save_to_file(output_path: Path) - Save to evals.json
• check_assertions(eval_id, output_dir) - Check assertions
• generate_grading_json(eval_id, output_dir, grading_path) - Generate grading

SkillPackager

Package and distribute skills:

• package(skill: Skill, output_path: Path) - Package a skill
• package_from_directory(skill_dir: Path, output_path: Path) - Package from directory
• unpack(skill_file: Path, output_dir: Path) - Unpack a .skill file
• install(skill_file: Path, install_dir: Path) - Install a skill

CLI Commands

# Create a new skill (defaults to ~/.bob/skills/NAME)
bob-skill create NAME --description DESC [--template TEMPLATE] [--output DIR]

# Validate a skill
bob-skill validate SKILL_PATH

# Package a skill
bob-skill package SKILL_PATH [--output FILE] [--no-validate]

# Unpack a .skill file
bob-skill unpack SKILL_FILE [--output DIR]

# Install a skill
bob-skill install SKILL_FILE INSTALL_DIR

# Show skill information
bob-skill info SKILL_PATH

# Initialize evals.json
bob-skill init-evals --name SKILL_NAME [--output FILE]

# List available templates
bob-skill list-templates

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/yourusername/bob-skill-creator.git
cd bob-skill-creator

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Running Tests

pytest
pytest --cov=bob_skill_creator

Code Formatting

black bob_skill_creator/
flake8 bob_skill_creator/
mypy bob_skill_creator/

Best Practices

1. Keep SKILL.md under 500 lines - Move large content to reference files
2. Write clear descriptions - Include when to use the skill
3. Use imperative form - "Do this" instead of "You should do this"
4. Add examples - Show concrete usage examples
5. Include test cases - Verify the skill works as expected
6. Validate before packaging - Catch issues early

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Documentation: GitHub README
• Issues: GitHub Issues