@oneie/claude 0.5.0 → 0.6.0

package/skills/composio/rules/app-execute-tools.md

@@ -0,0 +1,202 @@
+---
+title: Direct Tool Execution for Applications
+impact: HIGH
+description: Core patterns for manually executing Composio tools in applications without agent frameworks
+tags: [tools, execute, execution, apps, manual]
+---
+
+# Direct Tool Execution for Applications
+
+When building applications without agent frameworks, use `composio.tools.execute()` to manually execute tools.
+
+## Basic Execution
+
+```typescript
+// Execute with a specific version (REQUIRED)
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+  userId: 'default',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  version: '12082025_00', // Specific version required
+});
+```
+
+## Discovering Available Tools
+
+> **⚠️ IMPORTANT:** Do NOT make up or guess tool or toolkit names/versions. Always verify slugs before using them:
+> - Use `composio manage tools list --toolkits "..."` to discover and `composio manage tools info "..."` to view tool schema (CLI)
+> - Use `composio.tools.get()` to discover available tools programmatically (SDK)
+>
+> See [Composio CLI Reference](./composio-cli.md) for discovery commands.
+
+```typescript
+// Get all available tools in a toolkit
+const githubTools = await composio.tools.get('default', {
+  toolkits: ['github'],
+  limit: 100 // Set appropriate limit
+});
+
+console.log('Available GitHub tools:', githubTools.map(t => t.name));
+```
+
+```python
+# Get all available tools in a toolkit
+github_tools = composio.tools.get(
+    user_id="default",
+    toolkits=["github"],
+    limit=100  # Set appropriate limit
+)
+
+print("Available GitHub tools:", [t.name for t in github_tools])
+```
+
+## Version Management
+
+**CRITICAL**: When manually executing tools (especially in workflows), a **specific version is required**. Using `'latest'` will throw an error.
+
+**How to discover available versions:**
+Use `composio.toolkits.get()` to see available versions for a toolkit:
+
+```typescript
+// Get toolkit information to see available versions
+const githubToolkit = await composio.toolkits.get('github');
+console.log('Available versions:', githubToolkit.versions);
+// e.g., ["12082025_00", "10082025_01", "08082025_00"]
+console.log('Current version:', githubToolkit.version); // e.g., "12082025_00"
+
+// ✅ DO: Pin to a specific version string for stability
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+  userId: 'user_123',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  version: '12082025_00', // Pinned version string
+});
+```
+
+```python
+# Get toolkit information to see available versions
+github_toolkit = composio.toolkits.get("github")
+print(f"Available versions: {github_toolkit.versions}")
+# e.g., ["12082025_00", "10082025_01", "08082025_00"]
+print(f"Current version: {github_toolkit.version}")  # e.g., "12082025_00"
+
+# ✅ DO: Pin to a specific version string for stability
+result = composio.tools.execute(
+    tool="GITHUB_GET_ISSUES",
+    user_id="user_123",
+    arguments={"owner": "composio", "repo": "sdk"},
+    version="12082025_00"  # Pinned version string
+)
+```
+
+**Why version pinning is required:**
+- Tool argument schemas can change between versions
+- Using `'latest'` in workflows can cause runtime errors when tools are updated
+- Pinned versions ensure workflow stability and predictability
+- Version validation prevents production issues from schema mismatches
+- **Don't use `githubToolkit.version` dynamically** - this always returns the latest version, defeating the purpose of pinning
+
+See [Tool Version Management](app-tool-versions.md) for detailed version strategies.
+
+## Parameters
+
+### ExecuteParams Object
+
+```typescript
+{
+  userId: string,           // User ID for connected account lookup
+  arguments: object,        // Tool-specific input parameters
+  version?: string,         // Toolkit version (required for manual execution)
+  dangerouslySkipVersionCheck?: boolean  // Bypass version validation (NOT recommended)
+}
+```
+
+### Execution Modifiers
+
+Transform requests and responses with modifiers:
+
+```typescript
+const result = await composio.tools.execute(
+  'GITHUB_GET_ISSUES',
+  {
+    userId: 'default',
+    arguments: { owner: 'composio', repo: 'sdk' },
+    version: '12082025_00',
+  },
+  {
+    beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
+      // Modify params before execution
+      console.log('Executing:', toolSlug);
+      return {
+        ...params,
+        arguments: {
+          ...params.arguments,
+          per_page: 100 // Add default parameter
+        }
+      };
+    },
+    afterExecute: ({ toolSlug, toolkitSlug, result }) => {
+      // Transform result after execution
+      console.log('Completed:', toolSlug);
+      return {
+        ...result,
+        timestamp: new Date().toISOString()
+      };
+    },
+  }
+);
+```
+
+## Response Format
+
+```typescript
+interface ToolExecuteResponse {
+  data: any;           // Tool-specific response data
+  error: string | null;  // Error message if execution failed
+  successful: boolean;   // Whether execution succeeded
+}
+```
+
+## Error Handling
+
+```typescript
+try {
+  const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+    userId: 'user_123',
+    arguments: { owner: 'composio', repo: 'sdk' },
+    version: '12082025_00',
+  });
+
+  if (!result.successful) {
+    console.error('Tool execution failed:', result.error);
+    // Handle error case
+    return;
+  }
+
+  // Process successful result
+  console.log('Issues:', result.data);
+} catch (error) {
+  if (error.name === 'ComposioToolNotFoundError') {
+    console.error('Tool not found');
+  } else if (error.name === 'ComposioToolExecutionError') {
+    console.error('Execution error:', error.message);
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## Common Error Types
+
+- `ComposioCustomToolsNotInitializedError`: Custom tools instance not initialized
+- `ComposioToolNotFoundError`: Tool with the given slug not found
+- `ComposioToolExecutionError`: Error during tool execution
+- Version validation errors: Thrown when version is missing or `'latest'` is used
+
+## Best Practices
+
+1. **Always specify versions**: Use explicit versions or configure at initialization
+2. **Handle errors gracefully**: Check `successful` flag and handle `error` field
+3. **Validate arguments**: Ensure all required parameters are provided
+4. **Use modifiers sparingly**: Only add modifiers when necessary for transformation
+5. **Log execution details**: Track which tools are executed for debugging
+6. **Test with real data**: Validate execution with actual connected accounts
+7. **Handle authentication errors**: User may not have connected account for toolkit

package/skills/composio/rules/app-fetch-tools.md

@@ -0,0 +1,292 @@
+---
+title: Fetching Tools for Applications
+impact: HIGH
+description: Essential patterns for discovering and retrieving tools from Composio for direct execution in applications
+tags: [tools, fetch, discovery, apps, providers]
+---
+
+# Fetching Tools for Applications
+
+When building applications (non-agent workflows), use direct tool fetching methods to discover and retrieve tools from Composio.
+
+> **⚠️ IMPORTANT:** Do NOT make up or guess tool or toolkit names. Always verify slugs before using them:
+> - Use `composio manage toolkits list` / `composio manage toolkits info "..."` and `composio manage tools list --toolkits "..."` / `composio manage tools info "..."` (CLI)
+> - Use `composio.tools.get()` to discover available tools programmatically (SDK)
+>
+> See [Composio CLI Reference](./composio-cli.md) for discovery commands.
+
+## Methods Overview
+
+- **`tools.get()`** - Use when working with a provider (OpenAI, Vercel, etc.). Returns tools wrapped in provider-specific format.
+- **`tools.getRawComposioTools()`** - Use for standalone applications and building UIs. Returns raw tool metadata without provider wrapping.
+
+### 1. tools.get() - For Provider-Based Applications
+
+Use `tools.get()` when you're using Composio with a provider like OpenAI, Vercel AI SDK, or LangChain. This method wraps tools in the format expected by your provider.
+
+**Get tools from a toolkit:**
+```typescript
+// Get important tools only (auto-applies important filter)
+const importantGithubTools = await composio.tools.get('default', {
+  toolkits: ['github']
+});
+
+// Get a limited number of tools (does NOT auto-apply important filter)
+const githubTools = await composio.tools.get('default', {
+  toolkits: ['github'],
+  limit: 10
+});
+```
+
+**Get a specific tool by slug:**
+```typescript
+const tool = await composio.tools.get('default', 'GITHUB_GET_REPO');
+```
+
+### 2. tools.getRawComposioTools() - For Standalone Applications & UIs
+
+Use `getRawComposioTools()` for standalone applications and building UIs. This method returns raw tool metadata without provider-specific wrapping, making it ideal for:
+- Building tool selection UIs
+- Creating tool catalogs or documentation
+- Direct tool execution workflows (without providers)
+- Custom tool management interfaces
+
+```typescript
+// Get important tools (auto-applies important filter)
+const importantTools = await composio.tools.getRawComposioTools({
+  toolkits: ['github']
+});
+
+// Get specific tools by slug
+const specificTools = await composio.tools.getRawComposioTools({
+  tools: ['GITHUB_GET_REPOS', 'SLACK_SEND_MESSAGE']
+});
+
+// Get limited tools (does NOT auto-apply important)
+const limitedTools = await composio.tools.getRawComposioTools({
+  toolkits: ['slack'],
+  limit: 5
+});
+```
+
+## Important Filter Behavior
+
+The `important` filter auto-applies to show only the most commonly used tools.
+
+**Auto-applies when:**
+- Only `toolkits` filter is provided (no other filters)
+
+**Does NOT auto-apply when:**
+- `limit` is specified
+- `search` is used
+- `tools` (specific slugs) are provided
+- `tags` are specified
+- `important` is explicitly set to `false`
+
+```typescript
+// Auto-applies important=true
+await composio.tools.get('default', { toolkits: ['github'] });
+
+// Does NOT auto-apply important (limit specified)
+await composio.tools.get('default', { toolkits: ['github'], limit: 10 });
+
+// Does NOT auto-apply important (search used)
+await composio.tools.get('default', { search: 'repo' });
+
+// Explicitly disable important filter
+await composio.tools.get('default', { toolkits: ['github'], important: false });
+```
+
+## Filter Parameters
+
+Available filters for both `tools.get()` and `tools.getRawComposioTools()`:
+
+- `toolkits`: Array of toolkit names (e.g., `['github', 'slack']`)
+- `tools`: Array of specific tool slugs (e.g., `['GITHUB_GET_REPO']`)
+- `search`: Search string for tool names/descriptions
+- `limit`: Maximum number of tools to return
+- `tags`: Array of tags to filter by
+- `scopes`: Array of scopes to filter by
+- `authConfigIds`: Array of auth config IDs to filter tools by specific auth configs
+- `important`: Boolean to explicitly control important filter (auto-applies in some cases)
+
+**Note:** You cannot use `tools` and `toolkits` filters together.
+
+## Schema Modification
+
+Customize tool schemas at fetch time:
+
+```typescript
+const customizedTools = await composio.tools.get('default', {
+  toolkits: ['github']
+}, {
+  modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
+    return { ...schema, description: 'Custom description' };
+  }
+});
+```
+
+## Best Practices
+
+1. **Choose the right method:**
+   - Use `tools.get()` when working with providers (OpenAI, Vercel, LangChain)
+   - Use `tools.getRawComposioTools()` for standalone apps, UIs, and catalogs
+
+2. **Use important filter for UIs**: Show important tools first, then allow users to discover all tools
+
+3. **Cache tool metadata**: Tools don't change frequently, cache the results
+
+4. **Filter by toolkit**: Group tools by toolkit for better organization
+
+5. **Don't mix tools and toolkits filters**: Cannot use both filters together
+
+## Complete Discovery Workflow
+
+Here's the recommended workflow for discovering and using tools:
+
+```typescript
+// Step 1: Get toolkit information (to discover available versions)
+const githubToolkit = await composio.toolkits.get('github');
+console.log('Toolkit:', githubToolkit.name);
+console.log('Available versions:', githubToolkit.versions);
+console.log('Current version:', githubToolkit.version);
+console.log('Description:', githubToolkit.description);
+
+// Step 2: Discover all available tools in the toolkit
+const allGithubTools = await composio.tools.get('default', {
+  toolkits: ['github'],
+  limit: 100 // Adjust based on your needs
+});
+
+console.log('\nAvailable tools:');
+allGithubTools.forEach(tool => {
+  console.log(`- ${tool.name}: ${tool.description}`);
+});
+
+// Step 3: Find the tool you need
+const repoTool = allGithubTools.find(t => t.name === 'GITHUB_GET_REPO');
+if (!repoTool) {
+  throw new Error('Tool not found');
+}
+
+// Step 4: Execute the tool with a pinned version string
+const result = await composio.tools.execute('GITHUB_GET_REPO', {
+  userId: 'user_123',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  version: '12082025_00' // ✅ Pinned version string for stability
+});
+```
+
+```python
+# Step 1: Get toolkit information (to discover available versions)
+github_toolkit = composio.toolkits.get("github")
+print(f"Toolkit: {github_toolkit.name}")
+print(f"Available versions: {github_toolkit.versions}")
+print(f"Current version: {github_toolkit.version}")
+print(f"Description: {github_toolkit.description}")
+
+# Step 2: Discover all available tools in the toolkit
+all_github_tools = composio.tools.get(
+    user_id="default",
+    toolkits=["github"],
+    limit=100  # Adjust based on your needs
+)
+
+print("\nAvailable tools:")
+for tool in all_github_tools:
+    print(f"- {tool.name}: {tool.description}")
+
+# Step 3: Find the tool you need
+repo_tool = next((t for t in all_github_tools if t.name == "GITHUB_GET_REPO"), None)
+if not repo_tool:
+    raise Exception("Tool not found")
+
+# Step 4: Execute the tool with a pinned version string
+result = composio.tools.execute(
+    tool="GITHUB_GET_REPO",
+    user_id="user_123",
+    arguments={"owner": "composio", "repo": "sdk"},
+    version="12082025_00"  # ✅ Pinned version string for stability
+)
+```
+
+## ❌ Common Mistakes
+
+```typescript
+// DON'T: Guess or make up tool names
+const result = await composio.tools.execute('GITHUB_GET_REPOSITORY', { // ❌ Wrong name
+  userId: 'user_123',
+  arguments: { repo: 'sdk' },
+  version: '12082025_00'
+});
+
+// DON'T: Use hardcoded versions without checking
+const result = await composio.tools.execute('GITHUB_GET_REPO', {
+  userId: 'user_123',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  version: '12082025_00' // ❌ This might be outdated, use `composio manage toolkits info "github"` to get the latest version
+});
+```
+
+```python
+# DON'T: Guess or make up tool names
+result = composio.tools.execute(
+    tool="GITHUB_GET_REPOSITORY",  # ❌ Wrong name
+    user_id="user_123",
+    arguments={"repo": "sdk"},
+    version="12082025_00"
+)
+
+# DON'T: Use hardcoded versions without checking
+result = composio.tools.execute(
+    tool="GITHUB_GET_REPO",
+    user_id="user_123",
+    arguments={"owner": "composio", "repo": "sdk"},
+    version="12082025_00"  # ❌ This might be outdated
+)
+```
+
+## ✅ Best Practices
+
+```typescript
+// DO: Discover available versions and tools first
+const toolkit = await composio.toolkits.get('github');
+console.log('Available versions:', toolkit.versions);
+
+const tools = await composio.tools.get('default', {
+  toolkits: ['github'],
+  limit: 100
+});
+
+// DO: Use discovered tool names and pin to a specific version string
+const toolName = tools.find(t => t.description.includes('repository'))?.name;
+if (toolName) {
+  const result = await composio.tools.execute(toolName, {
+    userId: 'user_123',
+    arguments: { owner: 'composio', repo: 'sdk' },
+    version: '12082025_00' // ✅ Pinned version string for stability
+  });
+}
+```
+
+```python
+# DO: Discover available versions and tools first
+toolkit = composio.toolkits.get("github")
+print(f"Available versions: {toolkit.versions}")
+
+tools = composio.tools.get(
+    user_id="default",
+    toolkits=["github"],
+    limit=100
+)
+
+# DO: Use discovered tool names and pin to a specific version string
+tool_name = next((t.name for t in tools if "repository" in t.description), None)
+if tool_name:
+    result = composio.tools.execute(
+        tool=tool_name,
+        user_id="user_123",
+        arguments={"owner": "composio", "repo": "sdk"},
+        version="12082025_00"  # ✅ Pinned version string for stability
+    )
+```

package/skills/composio/rules/app-modifiers.md

@@ -0,0 +1,148 @@
+---
+title: Tool Modifiers
+impact: MEDIUM
+description: Advanced patterns for customizing tool behavior with schema modifications and execution hooks
+tags: [modifiers, hooks, customization, schema, execution]
+---
+
+# Tool Modifiers
+
+Modifiers customize tool behavior through schema transformations, pre-execution hooks, and post-execution hooks.
+
+## Schema Modification
+
+Customize tool descriptions or parameters at fetch time:
+
+```typescript
+const tools = await composio.tools.get(
+  'default',
+  { toolkits: ['github'] },
+  {
+    modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
+      // Enhance descriptions for AI
+      schema.description = `[Enhanced] ${schema.description}`;
+
+      // Customize specific parameters
+      if (toolSlug === 'GITHUB_GET_REPO') {
+        schema.inputParameters.properties.owner.description =
+          'GitHub organization or user name (e.g., "composio")';
+      }
+
+      return schema;
+    },
+  }
+);
+```
+
+## Pre-Execution Hooks (beforeExecute)
+
+Modify parameters before execution:
+
+```typescript
+const result = await composio.tools.execute(
+  'GITHUB_GET_REPO',
+  {
+    userId: 'default',
+    arguments: { owner: 'Composio', repo: 'sdk' },
+  },
+  {
+    beforeExecute: ({ toolSlug, params }) => {
+      // Normalize inputs
+      params.arguments.owner = params.arguments.owner.toLowerCase();
+
+      // Add defaults
+      params.arguments.branch = params.arguments.branch || 'main';
+
+      return params;
+    },
+  }
+);
+```
+
+**Common uses:**
+- Parameter validation and normalization
+- Adding default values
+- Logging and tracing
+
+## Post-Execution Hooks (afterExecute)
+
+Transform outputs after execution:
+
+```typescript
+const result = await composio.tools.execute(
+  'GITHUB_GET_REPO',
+  {
+    userId: 'default',
+    arguments: { owner: 'composio', repo: 'sdk' },
+  },
+  {
+    afterExecute: ({ result }) => {
+      if (result.successful) {
+        // Remove sensitive data
+        delete result.data.token;
+
+        // Add metadata
+        result.data.fetchedAt = new Date().toISOString();
+      }
+
+      return result;
+    },
+  }
+);
+```
+
+**Common uses:**
+- Filtering sensitive data
+- Data transformation and formatting
+- Adding metadata
+
+## Common Patterns
+
+### Sensitive Data Filtering
+
+```typescript
+const filterSensitive = ({ result }) => {
+  if (result.successful) {
+    ['token', 'secret', 'password', 'api_key'].forEach(field => {
+      delete result.data[field];
+    });
+  }
+  return result;
+};
+```
+
+### Logging & Monitoring
+
+```typescript
+const monitor = {
+  beforeExecute: ({ toolSlug, params }) => {
+    console.log(`[START] ${toolSlug}`, params.arguments);
+    return params;
+  },
+  afterExecute: ({ toolSlug, result }) => {
+    console.log(`[END] ${toolSlug} - Success: ${result.successful}`);
+    return result;
+  },
+};
+```
+
+### Reusable Modifiers
+
+```typescript
+const addTimestamps = ({ result }) => {
+  if (result.successful) result.data.executedAt = new Date().toISOString();
+  return result;
+};
+
+// Use in multiple executions
+await composio.tools.execute('GITHUB_GET_REPO', { ... }, {
+  afterExecute: addTimestamps
+});
+```
+
+## Key Points
+
+- Schema modifiers apply at fetch time, execution modifiers at runtime
+- Always return modified object (don't just mutate)
+- Modifiers are synchronous - keep operations lightweight
+- Must pass modifiers to each execute() call (not persisted)