Initial commit

skills/skill-adapter/assets/README.md

@@ -0,0 +1,8 @@
+# Assets
+
+Bundled resources for api-migration-tool skill
+
+- [ ] migration_template.py: Template for creating API migration scripts.
+- [ ] config_template.json: Template for API migration configuration files.
+- [ ] example_api_definition_v1.json: Example API definition for version 1.
+- [ ] example_api_definition_v2.json: Example API definition for version 2.

skills/skill-adapter/assets/config-template.json

@@ -0,0 +1,32 @@
+{
+  "skill": {
+    "name": "skill-name",
+    "version": "1.0.0",
+    "enabled": true,
+    "settings": {
+      "verbose": false,
+      "autoActivate": true,
+      "toolRestrictions": true
+    }
+  },
+  "triggers": {
+    "keywords": [
+      "example-trigger-1",
+      "example-trigger-2"
+    ],
+    "patterns": []
+  },
+  "tools": {
+    "allowed": [
+      "Read",
+      "Grep",
+      "Bash"
+    ],
+    "restricted": []
+  },
+  "metadata": {
+    "author": "Plugin Author",
+    "category": "general",
+    "tags": []
+  }
+}

skills/skill-adapter/assets/config_template.json

@@ -0,0 +1,113 @@
+{
+  "_comment": "API Migration Configuration Template",
+  "source_api": {
+    "_comment": "Details of the API you are migrating *from*",
+    "version": "v1",
+    "base_url": "https://api.example.com/v1",
+    "authentication": {
+      "type": "apiKey",
+      "_comment": "Supported types: apiKey, oauth2, none",
+      "apiKey": {
+        "name": "X-API-Key",
+        "in": "header"
+      }
+    },
+    "endpoints": [
+      {
+        "path": "/users/{user_id}",
+        "method": "GET",
+        "description": "Retrieve user details by ID",
+        "parameters": [
+          {
+            "name": "user_id",
+            "in": "path",
+            "type": "integer",
+            "required": true
+          }
+        ]
+      },
+      {
+        "path": "/products",
+        "method": "GET",
+        "description": "Retrieve a list of products",
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "type": "integer",
+            "description": "Maximum number of products to return",
+            "default": 10
+          }
+        ]
+      }
+    ]
+  },
+  "target_api": {
+    "_comment": "Details of the API you are migrating *to*",
+    "version": "v2",
+    "base_url": "https://api.example.com/v2",
+    "authentication": {
+      "type": "oauth2",
+      "flow": "authorizationCode",
+      "authorizationUrl": "https://example.com/oauth/authorize",
+      "tokenUrl": "https://example.com/oauth/token",
+      "scopes": ["read", "write"]
+    },
+    "endpoints": [
+      {
+        "path": "/users/{userId}",
+        "method": "GET",
+        "description": "Retrieve user details by ID",
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "type": "string",
+            "required": true
+          }
+        ]
+      },
+      {
+        "path": "/products",
+        "method": "GET",
+        "description": "Retrieve a list of products",
+        "parameters": [
+          {
+            "name": "maxResults",
+            "in": "query",
+            "type": "integer",
+            "description": "Maximum number of products to return",
+            "default": 10
+          }
+        ]
+      }
+    ]
+  },
+  "migration_strategy": {
+    "_comment": "Configuration for how to handle breaking changes",
+    "parameter_mapping": [
+      {
+        "source_parameter": "user_id",
+        "target_parameter": "userId",
+        "transformation": "toString"
+      },
+      {
+        "source_parameter": "limit",
+        "target_parameter": "maxResults"
+      }
+    ],
+    "data_mapping": {
+      "_comment": "Example of how to map data fields (if needed).  Leave empty if not required.",
+      "user_name": "full_name"
+    },
+    "error_handling": {
+      "_comment": "How to handle errors during migration",
+      "strategy": "fallback",
+      "_comment": "Options: fallback, retry, abort",
+      "fallback_response": {
+        "status_code": 500,
+        "message": "Error during migration"
+      }
+    }
+  }
+}

skills/skill-adapter/assets/example_api_definition_v1.json

@@ -0,0 +1,240 @@
+{
+  "_comment": "Example API definition for version 1",
+  "api_name": "User Management API",
+  "version": "1.0",
+  "description": "API for managing user accounts and profiles.",
+  "base_path": "/api/v1",
+  "endpoints": [
+    {
+      "path": "/users",
+      "method": "GET",
+      "description": "Retrieve a list of all users.",
+      "parameters": [
+        {
+          "name": "limit",
+          "type": "integer",
+          "description": "Maximum number of users to return.",
+          "required": false,
+          "default": 20
+        },
+        {
+          "name": "offset",
+          "type": "integer",
+          "description": "Offset for pagination.",
+          "required": false,
+          "default": 0
+        }
+      ],
+      "responses": {
+        "200": {
+          "description": "Successful operation",
+          "schema": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/User"
+            }
+          }
+        },
+        "500": {
+          "description": "Internal server error"
+        }
+      }
+    },
+    {
+      "path": "/users/{user_id}",
+      "method": "GET",
+      "description": "Retrieve a specific user by ID.",
+      "parameters": [
+        {
+          "name": "user_id",
+          "type": "string",
+          "description": "ID of the user to retrieve.",
+          "required": true,
+          "in": "path"
+        }
+      ],
+      "responses": {
+        "200": {
+          "description": "Successful operation",
+          "schema": {
+            "$ref": "#/definitions/User"
+          }
+        },
+        "404": {
+          "description": "User not found"
+        },
+        "500": {
+          "description": "Internal server error"
+        }
+      }
+    },
+    {
+      "path": "/users",
+      "method": "POST",
+      "description": "Create a new user.",
+      "parameters": [
+        {
+          "name": "user",
+          "type": "object",
+          "description": "User object to create.",
+          "required": true,
+          "in": "body",
+          "schema": {
+            "$ref": "#/definitions/CreateUserRequest"
+          }
+        }
+      ],
+      "responses": {
+        "201": {
+          "description": "User created successfully",
+          "schema": {
+            "$ref": "#/definitions/User"
+          }
+        },
+        "400": {
+          "description": "Invalid request body"
+        },
+        "500": {
+          "description": "Internal server error"
+        }
+      }
+    },
+    {
+      "path": "/users/{user_id}",
+      "method": "PUT",
+      "description": "Update an existing user.",
+      "parameters": [
+        {
+          "name": "user_id",
+          "type": "string",
+          "description": "ID of the user to update.",
+          "required": true,
+          "in": "path"
+        },
+        {
+          "name": "user",
+          "type": "object",
+          "description": "User object with updated information.",
+          "required": true,
+          "in": "body",
+          "schema": {
+            "$ref": "#/definitions/UpdateUserRequest"
+          }
+        }
+      ],
+      "responses": {
+        "200": {
+          "description": "User updated successfully",
+          "schema": {
+            "$ref": "#/definitions/User"
+          }
+        },
+        "400": {
+          "description": "Invalid request body"
+        },
+        "404": {
+          "description": "User not found"
+        },
+        "500": {
+          "description": "Internal server error"
+        }
+      }
+    },
+    {
+      "path": "/users/{user_id}",
+      "method": "DELETE",
+      "description": "Delete a user.",
+      "parameters": [
+        {
+          "name": "user_id",
+          "type": "string",
+          "description": "ID of the user to delete.",
+          "required": true,
+          "in": "path"
+        }
+      ],
+      "responses": {
+        "204": {
+          "description": "User deleted successfully"
+        },
+        "404": {
+          "description": "User not found"
+        },
+        "500": {
+          "description": "Internal server error"
+        }
+      }
+    }
+  ],
+  "definitions": {
+    "User": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the user."
+        },
+        "username": {
+          "type": "string",
+          "description": "Username of the user."
+        },
+        "email": {
+          "type": "string",
+          "description": "Email address of the user."
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp of when the user was created."
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp of when the user was last updated."
+        }
+      },
+      "required": [
+        "id",
+        "username",
+        "email",
+        "created_at",
+        "updated_at"
+      ]
+    },
+    "CreateUserRequest": {
+      "type": "object",
+      "properties": {
+        "username": {
+          "type": "string",
+          "description": "Username of the user."
+        },
+        "email": {
+          "type": "string",
+          "description": "Email address of the user."
+        },
+        "password": {
+          "type": "string",
+          "description": "Password for the user."
+        }
+      },
+      "required": [
+        "username",
+        "email",
+        "password"
+      ]
+    },
+    "UpdateUserRequest": {
+      "type": "object",
+      "properties": {
+        "username": {
+          "type": "string",
+          "description": "Username of the user."
+        },
+        "email": {
+          "type": "string",
+          "description": "Email address of the user."
+        }
+      }
+    }
+  }
+}

skills/skill-adapter/assets/example_api_definition_v2.json

@@ -0,0 +1,138 @@
+{
+  "_comment": "Example API Definition - Version 2.0",
+  "api_name": "MyAwesomeAPI",
+  "version": "2.0",
+  "description": "This is the second version of the MyAwesomeAPI, introducing enhanced features and improved performance.",
+  "base_url": "https://api.example.com/v2",
+  "endpoints": [
+    {
+      "_comment": "Endpoint for retrieving user data",
+      "path": "/users/{user_id}",
+      "method": "GET",
+      "description": "Retrieves user information based on the provided user ID.",
+      "parameters": [
+        {
+          "name": "user_id",
+          "in": "path",
+          "description": "The unique identifier of the user.",
+          "required": true,
+          "type": "integer"
+        },
+        {
+          "name": "include_details",
+          "in": "query",
+          "description": "Whether to include additional user details (e.g., address, phone number).",
+          "required": false,
+          "type": "boolean",
+          "default": false
+        }
+      ],
+      "responses": {
+        "200": {
+          "description": "Successful retrieval of user data.",
+          "schema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "integer",
+                "description": "The user's unique identifier."
+              },
+              "username": {
+                "type": "string",
+                "description": "The user's username."
+              },
+              "email": {
+                "type": "string",
+                "description": "The user's email address."
+              },
+              "first_name": {
+                "type": "string",
+                "description": "The user's first name."
+              },
+              "last_name": {
+                "type": "string",
+                "description": "The user's last name."
+              },
+              "address": {
+                "type": "string",
+                "description": "The user's address (optional, only included if include_details=true)"
+              },
+              "phone_number": {
+                "type": "string",
+                "description": "The user's phone number (optional, only included if include_details=true)"
+              }
+            }
+          }
+        },
+        "404": {
+          "description": "User not found."
+        }
+      }
+    },
+    {
+      "_comment": "Endpoint for creating a new user",
+      "path": "/users",
+      "method": "POST",
+      "description": "Creates a new user account.",
+      "requestBody": {
+        "description": "User data to create a new account.",
+        "required": true,
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "username": {
+                  "type": "string",
+                  "description": "The desired username.",
+                  "required": true
+                },
+                "password": {
+                  "type": "string",
+                  "description": "The desired password.",
+                  "required": true
+                },
+                "email": {
+                  "type": "string",
+                  "description": "The user's email address.",
+                  "required": true
+                },
+                 "first_name": {
+                  "type": "string",
+                  "description": "The user's first name.",
+                  "required": false
+                },
+                "last_name": {
+                  "type": "string",
+                  "description": "The user's last name.",
+                  "required": false
+                }
+              }
+            }
+          }
+        }
+      },
+      "responses": {
+        "201": {
+          "description": "User account created successfully.",
+          "schema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "integer",
+                "description": "The newly created user's unique identifier."
+              },
+              "username": {
+                "type": "string",
+                "description": "The user's username."
+              }
+            }
+          }
+        },
+        "400": {
+          "description": "Invalid request body or validation errors."
+        }
+      }
+    }
+  ]
+}

skills/skill-adapter/assets/migration_template.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+
+"""
+Template for creating API migration scripts.
+
+This module provides a template for creating scripts to migrate APIs
+between different versions while maintaining backward compatibility.
+It includes functions for loading data, transforming data, and saving data
+in the new format, along with error handling and logging.
+"""
+
+import argparse
+import json
+import logging
+import os
+import sys
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+
+
+class MigrationError(Exception):
+    """Custom exception for migration-related errors."""
+
+    pass
+
+
+def load_data(input_file):
+    """
+    Loads data from a JSON file.
+
+    Args:
+        input_file (str): Path to the input JSON file.
+
+    Returns:
+        dict: The loaded data as a dictionary.
+
+    Raises:
+        MigrationError: If the file cannot be opened or parsed.
+    """
+    try:
+        with open(input_file, "r") as f:
+            data = json.load(f)
+        return data
+    except FileNotFoundError:
+        raise MigrationError(f"Input file not found: {input_file}")
+    except json.JSONDecodeError:
+        raise MigrationError(f"Invalid JSON format in file: {input_file}")
+    except Exception as e:
+        raise MigrationError(f"Error loading data from {input_file}: {e}")
+
+
+def transform_data(data):
+    """
+    Transforms the data from the old format to the new format.
+
+    This is where the core migration logic should be implemented.
+
+    Args:
+        data (dict): The data in the old format.
+
+    Returns:
+        dict: The data in the new format.
+
+    Raises:
+        MigrationError: If there is an error during the transformation.
+    """
+    try:
+        # Example transformation: Add a version field
+        transformed_data = data.copy()
+        transformed_data["version"] = "2.0"  # Example version
+        # Add your transformation logic here
+        return transformed_data
+    except Exception as e:
+        raise MigrationError(f"Error transforming data: {e}")
+
+
+def save_data(data, output_file):
+    """
+    Saves the transformed data to a JSON file.
+
+    Args:
+        data (dict): The transformed data.
+        output_file (str): Path to the output JSON file.
+
+    Raises:
+        MigrationError: If the file cannot be written to.
+    """
+    try:
+        with open(output_file, "w") as f:
+            json.dump(data, f, indent=4)
+    except Exception as e:
+        raise MigrationError(f"Error saving data to {output_file}: {e}")
+
+
+def migrate_api(input_file, output_file):
+    """
+    Migrates the API data from the old format to the new format.
+
+    Args:
+        input_file (str): Path to the input JSON file.
+        output_file (str): Path to the output JSON file.
+    """
+    try:
+        logging.info(f"Loading data from {input_file}...")
+        data = load_data(input_file)
+
+        logging.info("Transforming data...")
+        transformed_data = transform_data(data)
+
+        logging.info(f"Saving data to {output_file}...")
+        save_data(transformed_data, output_file)
+
+        logging.info("API migration completed successfully.")
+
+    except MigrationError as e:
+        logging.error(f"API migration failed: {e}")
+        sys.exit(1)
+
+
+def main():
+    """
+    Main function to parse arguments and run the migration.
+    """
+    parser = argparse.ArgumentParser(
+        description="Migrate API data between versions."
+    )
+    parser.add_argument(
+        "input_file", help="Path to the input JSON file (old format)."
+    )
+    parser.add_argument(
+        "output_file", help="Path to the output JSON file (new format)."
+    )
+
+    args = parser.parse_args()
+    migrate_api(args.input_file, args.output_file)
+
+
+if __name__ == "__main__":
+    # Example usage:
+    # Create a dummy input file
+    if not os.path.exists("input.json"):
+        with open("input.json", "w") as f:
+            json.dump({"name": "Example API", "version": "1.0"}, f, indent=4)
+
+    # Run the migration
+    try:
+        main()
+    except SystemExit:
+        # Handle argparse exit (e.g., when -h is used)
+        pass
+    except Exception as e:
+        logging.error(f"An unexpected error occurred: {e}")
+        sys.exit(1)

skills/skill-adapter/assets/skill-schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claude Skill Configuration",
+  "type": "object",
+  "required": ["name", "description"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$",
+      "maxLength": 64,
+      "description": "Skill identifier (lowercase, hyphens only)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1024,
+      "description": "What the skill does and when to use it"
+    },
+    "allowed-tools": {
+      "type": "string",
+      "description": "Comma-separated list of allowed tools"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version (x.y.z)"
+    }
+  }
+}

skills/skill-adapter/assets/test-data.json

@@ -0,0 +1,27 @@
+{
+  "testCases": [
+    {
+      "name": "Basic activation test",
+      "input": "trigger phrase example",
+      "expected": {
+        "activated": true,
+        "toolsUsed": ["Read", "Grep"],
+        "success": true
+      }
+    },
+    {
+      "name": "Complex workflow test",
+      "input": "multi-step trigger example",
+      "expected": {
+        "activated": true,
+        "steps": 3,
+        "toolsUsed": ["Read", "Write", "Bash"],
+        "success": true
+      }
+    }
+  ],
+  "fixtures": {
+    "sampleInput": "example data",
+    "expectedOutput": "processed result"
+  }
+}

skills/skill-adapter/references/README.md

@@ -0,0 +1,8 @@
+# References
+
+Bundled resources for api-migration-tool skill
+
+- [ ] api_migration_best_practices.md: Detailed guide on API migration strategies, backward compatibility, and versioning.
+- [ ] api_design_principles.md: Core principles for designing APIs that are easy to migrate and maintain.
+- [ ] api_versioning_strategies.md: Different approaches to API versioning (e.g., semantic versioning, URL-based versioning).
+- [ ] example_api_schemas.md: Examples of API schemas and data structures for different API versions.

skills/skill-adapter/references/best-practices.md

@@ -0,0 +1,69 @@
+# Skill Best Practices
+
+Guidelines for optimal skill usage and development.
+
+## For Users
+
+### Activation Best Practices
+
+1. **Use Clear Trigger Phrases**
+   - Match phrases from skill description
+   - Be specific about intent
+   - Provide necessary context
+
+2. **Provide Sufficient Context**
+   - Include relevant file paths
+   - Specify scope of analysis
+   - Mention any constraints
+
+3. **Understand Tool Permissions**
+   - Check allowed-tools in frontmatter
+   - Know what the skill can/cannot do
+   - Request appropriate actions
+
+### Workflow Optimization
+
+- Start with simple requests
+- Build up to complex workflows
+- Verify each step before proceeding
+- Use skill consistently for related tasks
+
+## For Developers
+
+### Skill Development Guidelines
+
+1. **Clear Descriptions**
+   - Include explicit trigger phrases
+   - Document all capabilities
+   - Specify limitations
+
+2. **Proper Tool Permissions**
+   - Use minimal necessary tools
+   - Document security implications
+   - Test with restricted tools
+
+3. **Comprehensive Documentation**
+   - Provide usage examples
+   - Document common pitfalls
+   - Include troubleshooting guide
+
+### Maintenance
+
+- Keep version updated
+- Test after tool updates
+- Monitor user feedback
+- Iterate on descriptions
+
+## Performance Tips
+
+- Scope skills to specific domains
+- Avoid overlapping trigger phrases
+- Keep descriptions under 1024 chars
+- Test activation reliability
+
+## Security Considerations
+
+- Never include secrets in skill files
+- Validate all inputs
+- Use read-only tools when possible
+- Document security requirements

skills/skill-adapter/references/examples.md

@@ -0,0 +1,70 @@
+# Skill Usage Examples
+
+This document provides practical examples of how to use this skill effectively.
+
+## Basic Usage
+
+### Example 1: Simple Activation
+
+**User Request:**
+```
+[Describe trigger phrase here]
+```
+
+**Skill Response:**
+1. Analyzes the request
+2. Performs the required action
+3. Returns results
+
+### Example 2: Complex Workflow
+
+**User Request:**
+```
+[Describe complex scenario]
+```
+
+**Workflow:**
+1. Step 1: Initial analysis
+2. Step 2: Data processing
+3. Step 3: Result generation
+4. Step 4: Validation
+
+## Advanced Patterns
+
+### Pattern 1: Chaining Operations
+
+Combine this skill with other tools:
+```
+Step 1: Use this skill for [purpose]
+Step 2: Chain with [other tool]
+Step 3: Finalize with [action]
+```
+
+### Pattern 2: Error Handling
+
+If issues occur:
+- Check trigger phrase matches
+- Verify context is available
+- Review allowed-tools permissions
+
+## Tips & Best Practices
+
+- ✅ Be specific with trigger phrases
+- ✅ Provide necessary context
+- ✅ Check tool permissions match needs
+- ❌ Avoid vague requests
+- ❌ Don't mix unrelated tasks
+
+## Common Issues
+
+**Issue:** Skill doesn't activate
+**Solution:** Use exact trigger phrases from description
+
+**Issue:** Unexpected results
+**Solution:** Check input format and context
+
+## See Also
+
+- Main SKILL.md for full documentation
+- scripts/ for automation helpers
+- assets/ for configuration examples

skills/skill-adapter/scripts/README.md

@@ -0,0 +1,8 @@
+# Scripts
+
+Bundled resources for api-migration-tool skill
+
+- [ ] api_version_compatibility_check.py: Checks compatibility between API versions using static analysis or API calls.
+- [ ] api_migration.py: Automates the migration of API code, including updating function calls and data structures.
+- [ ] api_deprecation_analyzer.py: Analyzes code for deprecated API usage and suggests replacements.
+- [ ] api_documentation_generator.py: Generates API documentation from code or configuration files.

skills/skill-adapter/scripts/helper-template.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Helper script template for skill automation
+# Customize this for your skill's specific needs
+
+set -e
+
+function show_usage() {
+    echo "Usage: $0 [options]"
+    echo ""
+    echo "Options:"
+    echo "  -h, --help     Show this help message"
+    echo "  -v, --verbose  Enable verbose output"
+    echo ""
+}
+
+# Parse arguments
+VERBOSE=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            show_usage
+            exit 0
+            ;;
+        -v|--verbose)
+            VERBOSE=true
+            shift
+            ;;
+        *)
+            echo "Unknown option: $1"
+            show_usage
+            exit 1
+            ;;
+    esac
+done
+
+# Your skill logic here
+if [ "$VERBOSE" = true ]; then
+    echo "Running skill automation..."
+fi
+
+echo "✅ Complete"

skills/skill-adapter/scripts/validation.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Skill validation helper
+# Validates skill activation and functionality
+
+set -e
+
+echo "🔍 Validating skill..."
+
+# Check if SKILL.md exists
+if [ ! -f "../SKILL.md" ]; then
+    echo "❌ Error: SKILL.md not found"
+    exit 1
+fi
+
+# Validate frontmatter
+if ! grep -q "^---$" "../SKILL.md"; then
+    echo "❌ Error: No frontmatter found"
+    exit 1
+fi
+
+# Check required fields
+if ! grep -q "^name:" "../SKILL.md"; then
+    echo "❌ Error: Missing 'name' field"
+    exit 1
+fi
+
+if ! grep -q "^description:" "../SKILL.md"; then
+    echo "❌ Error: Missing 'description' field"
+    exit 1
+fi
+
+echo "✅ Skill validation passed"