Skip to main content

Module wizard

composio_sdk

Module wizard 

Source
Expand description

Wizard instruction generation from Composio Skills Wizard instruction generation module

This module provides utilities for extracting Composio Skills content and generating wizard instructions for AI agents. It integrates with the official Composio Skills repository to provide production-ready guidance based on best practices and anti-patterns.

§Overview

The wizard module consists of three main components:

§Architecture

┌─────────────────────────────────────────────────────────────┐
│              Composio Skills Repository                      │
│  (https://github.com/ComposioHQ/skills)                     │
│  - AGENTS.md (consolidated reference)                        │
│  - rules/tr-*.md (Tool Router rules)                        │
│  - rules/triggers-*.md (Trigger rules)                      │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ extracts
                        ▼
                ┌───────────────┐
                │ SkillsExtractor│
                └───────┬───────┘
                        │
         ┌──────────────┼──────────────┐
         │              │              │
         ▼              ▼              ▼
  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  │  Generator  │ │  Validator  │ │   Rules     │
  └─────────────┘ └─────────────┘ └─────────────┘

§Usage Examples

§Basic Usage: Generate Wizard Instructions

use composio_sdk::wizard::{SkillsExtractor, WizardInstructionGenerator};

// Skills are now bundled within the SDK
// No need to specify external path - use the bundled skills
let skills_path = concat!(env!("CARGO_MANIFEST_DIR"), "/skills");
let skills = SkillsExtractor::new(skills_path);

// Verify the Skills repository is accessible
skills.verify_path()?;

// Create the instruction generator
let generator = WizardInstructionGenerator::new(skills);

// Generate generic Composio instructions
let instructions = generator.generate_composio_instructions(None)?;
println!("{}", instructions);

// Generate toolkit-specific instructions (e.g., for GitHub)
let github_instructions = generator.generate_composio_instructions(Some("github"))?;
println!("{}", github_instructions);

§Advanced Usage: Extract and Filter Rules

use composio_sdk::wizard::{SkillsExtractor, Impact};

// Skills are bundled within the SDK
let skills_path = concat!(env!("CARGO_MANIFEST_DIR"), "/skills");
let skills = SkillsExtractor::new(skills_path);

// Get all Tool Router rules
let tool_router_rules = skills.get_tool_router_rules()?;
println!("Found {} Tool Router rules", tool_router_rules.len());

// Get all Trigger rules
let trigger_rules = skills.get_trigger_rules()?;
println!("Found {} Trigger rules", trigger_rules.len());

// Filter rules by tag
let session_rules = skills.get_rules_by_tag("session")?;
println!("Found {} session-related rules", session_rules.len());

// Get consolidated content from AGENTS.md
let consolidated = skills.get_consolidated_content()?;
println!("Consolidated content: {} bytes", consolidated.len());

// Inspect individual rules
for rule in tool_router_rules.iter().take(5) {
    println!("Rule: {}", rule.title);
    println!("Impact: {:?}", rule.impact);
    println!("Tags: {:?}", rule.tags);
    println!("Correct examples: {}", rule.correct_examples.len());
    println!("Incorrect examples: {}", rule.incorrect_examples.len());
    println!("---");
}

§Validation: Check Instructions Against Official Patterns

use composio_sdk::wizard::{SkillsExtractor, InstructionValidator};

// Skills are bundled within the SDK
let skills_path = concat!(env!("CARGO_MANIFEST_DIR"), "/skills");
let skills = SkillsExtractor::new(skills_path);
let validator = InstructionValidator::new(skills);

// Validate some instructions
let instructions = r#"

Always use composio.create(user_id) to create a session.
Use session.tools() for native tool integration.
"#;

let result = validator.validate(instructions)?;

if result.is_valid() {
    println!("✓ Instructions are valid!");
} else {
    println!("✗ Validation failed:");
    println!("{}", result.format());
}

if result.has_warnings() {
    println!("⚠ Warnings found:");
    println!("{}", result.format());
}

println!("Total issues: {}", result.total_issues());

§Working with Rules

use composio_sdk::wizard::{Rule, Impact};
use std::path::Path;

// Load a rule from the bundled skills
let skills_path = concat!(env!("CARGO_MANIFEST_DIR"), "/skills");
let rule_path = format!("{}/rules/tr-001.md", skills_path);
let rule = Rule::from_file(Path::new(&rule_path))?;

println!("Title: {}", rule.title);
println!("Impact: {:?}", rule.impact);
println!("Description: {}", rule.description);
println!("Tags: {:?}", rule.tags);

// Access examples
for (i, example) in rule.correct_examples.iter().enumerate() {
    println!("✅ Correct example {}: {}", i + 1, example);
}

for (i, example) in rule.incorrect_examples.iter().enumerate() {
    println!("❌ Incorrect example {}: {}", i + 1, example);
}

§Integration with Build Process

The Skills content is now bundled directly within the SDK at composio-sdk/skills/. This means:

  1. No external dependencies on vendor/skills repository
  2. Skills content is always available at compile time
  3. No need to clone or download Skills repository separately
  4. SDK is fully self-contained

The bundled Skills include:

  • AGENTS.md - Consolidated reference (150+ KB)
  • SKILL.md - Metadata
  • rules/*.md - 30+ rule files with best practices

§Skills Repository Structure

composio-sdk/skills/
├── AGENTS.md              # Consolidated reference (150+ KB)
├── SKILL.md               # Metadata
└── rules/
    ├── tr-*.md            # Tool Router rules
    ├── triggers-*.md      # Trigger rules
    └── app-*.md           # Application rules

§Rule Format

Rules are markdown files with YAML frontmatter:

---
title: Always use composio.create(user_id)
impact: critical
tags: [session, user-scoping]
---

# Description
Always create sessions with user_id for proper isolation.

## Correct ✅
```python
session = composio.create(user_id="user_123")

§Incorrect ❌

session = composio.create()  # Missing user_id

§Impact Levels

Rules are categorized by impact:

  • Critical: Must be followed, causes failures if violated
  • High: Should be followed, causes issues if violated
  • Medium: Recommended, improves quality
  • Low: Optional, nice to have

§Error Handling

All operations return Result<T, SkillsError> for proper error handling:

use composio_sdk::wizard::{SkillsExtractor, SkillsError};

// Skills are bundled within the SDK
let skills_path = concat!(env!("CARGO_MANIFEST_DIR"), "/skills");
let skills = SkillsExtractor::new(skills_path);

match skills.verify_path() {
    Ok(_) => println!("Skills repository found"),
    Err(SkillsError::PathNotFound(path)) => {
        eprintln!("Skills repository not found at: {}", path.display());
    }
    Err(e) => eprintln!("Error: {}", e),
}

Structs§

InstructionValidator
Validator for wizard instructions
Rule
A rule extracted from the Skills repository
SkillsExtractor
Extractor for Composio Skills content
ValidationResult
Result of instruction validation
WizardInstructionGenerator
Generator for wizard instructions

Enums§

Impact
Impact level of a rule
SkillsError
Errors that can occur during skills extraction

Functions§

generate_wizard_instructions
Generate wizard instructions for Composio integration