zhongwei/gh-jeremylongshore-claude-code-plugins-plus-plugins-api-development-api-versioning-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:52:42 +08:00
commit 4bb7de1bdc
18 changed files with 1789 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
skills/skill-adapter/assets/README.md Normal file
View File

@@ -0,0 +1,8 @@
# Assets
Bundled resources for api-versioning-manager skill
- [ ] api_version_template.json: Template for API version configuration files.
- [ ] deprecation_notice_template.md: Template for deprecation notices.
- [ ] compatibility_test_suite.json: Example compatibility test suite.
- [ ] migration_guide_template.md: Template for migration guides.

106
skills/skill-adapter/assets/api_version_template.json Normal file
View File

@@ -0,0 +1,106 @@
{
"_comment": "API Version Configuration Template",
"apiName": "MyAwesomeAPI",
"versions": [
{
"version": "v1",
"_comment": "Initial version of the API",
"status": "active",
"releaseDate": "2023-01-15",
"deprecationDate": null,
"sunsetDate": null,
"migrationGuide": null,
"backwardCompatible": true,
"endpoints": {
"/users": {
"method": "GET",
"description": "Retrieve all users",
"fields": ["id", "name", "email"]
},
"/users/{id}": {
"method": "GET",
"description": "Retrieve a specific user",
"fields": ["id", "name", "email"]
}
}
},
{
"version": "v2",
"_comment": "Second version of the API with enhanced features",
"status": "active",
"releaseDate": "2023-07-20",
"deprecationDate": "2024-01-15",
"sunsetDate": "2024-07-20",
"migrationGuide": "https://example.com/migration-v1-to-v2",
"backwardCompatible": false,
"endpoints": {
"/users": {
"method": "GET",
"description": "Retrieve all users with pagination and filtering",
"fields": ["id", "name", "email", "createdAt", "updatedAt"],
"parameters": ["page", "limit", "filter"]
},
"/users/{id}": {
"method": "GET",
"description": "Retrieve a specific user with extended profile information",
"fields": ["id", "name", "email", "createdAt", "updatedAt", "profile"]
},
"/users/{id}/orders": {
"method": "GET",
"description": "Retrieve orders for a specific user",
"fields": ["orderId", "orderDate", "total"]
}
}
},
{
"version": "v3",
"_comment": "Third version of the API - current version",
"status": "active",
"releaseDate": "2024-02-01",
"deprecationDate": null,
"sunsetDate": null,
"migrationGuide": null,
"backwardCompatible": true,
"endpoints": {
"/users": {
"method": "GET",
"description": "Retrieve all users with improved pagination and filtering",
"fields": ["id", "name", "email", "createdAt", "updatedAt"],
"parameters": ["page", "limit", "filter", "sort"]
},
"/users/{id}": {
"method": "GET",
"description": "Retrieve a specific user with extended profile information and address",
"fields": ["id", "name", "email", "createdAt", "updatedAt", "profile", "address"]
},
"/users/{id}/orders": {
"method": "GET",
"description": "Retrieve orders for a specific user with detailed order information",
"fields": ["orderId", "orderDate", "total", "items"]
}
}
},
{
"version": "v0",
"_comment": "Deprecated version of the API",
"status": "deprecated",
"releaseDate": "2022-01-01",
"deprecationDate": "2023-01-01",
"sunsetDate": "2023-07-01",
"migrationGuide": "https://example.com/migration-v0-to-v1",
"backwardCompatible": false,
"endpoints": {
"/users": {
"method": "GET",
"description": "Retrieve all users (DEPRECATED)",
"fields": ["id", "name"]
},
"/users/{id}": {
"method": "GET",
"description": "Retrieve a specific user (DEPRECATED)",
"fields": ["id", "name"]
}
}
}
]
}

110
skills/skill-adapter/assets/compatibility_test_suite.json Normal file
View File

@@ -0,0 +1,110 @@
{
"_comment": "Compatibility Test Suite for API Versioning Manager",
"api_name": "User Management API",
"tests": [
{
"_comment": "Test case for retrieving user details in version 1",
"test_name": "Get User Details v1",
"api_version": "1",
"endpoint": "/users/123",
"method": "GET",
"request_headers": {
"Accept": "application/json"
},
"expected_status_code": 200,
"expected_response_body": {
"id": 123,
"name": "John Doe",
"email": "john.doe@example.com"
},
"backward_compatible_versions": []
},
{
"_comment": "Test case for retrieving user details in version 2",
"test_name": "Get User Details v2",
"api_version": "2",
"endpoint": "/v2/users/123",
"method": "GET",
"request_headers": {
"Accept": "application/json"
},
"expected_status_code": 200,
"expected_response_body": {
"user_id": 123,
"full_name": "John Doe",
"contact_email": "john.doe@example.com",
"profile_details": {
"created_at": "2023-10-26T10:00:00Z"
}
},
"backward_compatible_versions": ["1"]
},
{
"_comment": "Test case for creating a user in version 1",
"test_name": "Create User v1",
"api_version": "1",
"endpoint": "/users",
"method": "POST",
"request_headers": {
"Content-Type": "application/json"
},
"request_body": {
"name": "Jane Smith",
"email": "jane.smith@example.com"
},
"expected_status_code": 201,
"expected_response_body": {
"id": 456,
"name": "Jane Smith",
"email": "jane.smith@example.com"
},
"backward_compatible_versions": []
},
{
"_comment": "Test case for creating a user in version 2",
"test_name": "Create User v2",
"api_version": "2",
"endpoint": "/v2/users",
"method": "POST",
"request_headers": {
"Content-Type": "application/json"
},
"request_body": {
"full_name": "Jane Smith",
"contact_email": "jane.smith@example.com"
},
"expected_status_code": 201,
"expected_response_body": {
"user_id": 456,
"full_name": "Jane Smith",
"contact_email": "jane.smith@example.com"
},
"backward_compatible_versions": ["1"]
},
{
"_comment": "Test case for deleting a user in version 1 (deprecated)",
"test_name": "Delete User v1 (Deprecated)",
"api_version": "1",
"endpoint": "/users/123",
"method": "DELETE",
"request_headers": {},
"expected_status_code": 410,
"expected_response_body": {
"error": "This endpoint is deprecated. Please use /v2/users/123/deactivate."
},
"backward_compatible_versions": [],
"deprecation_message": "This endpoint is deprecated. Please use /v2/users/123/deactivate."
},
{
"_comment": "Test case for deactivating a user in version 2",
"test_name": "Deactivate User v2",
"api_version": "2",
"endpoint": "/v2/users/123/deactivate",
"method": "POST",
"request_headers": {},
"expected_status_code": 204,
"expected_response_body": null,
"backward_compatible_versions": []
}
]
}

32
skills/skill-adapter/assets/config-template.json Normal file
View File

@@ -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": []
}
}

105
skills/skill-adapter/assets/deprecation_notice_template.md Normal file
View File

@@ -0,0 +1,105 @@
# Deprecation Notice Template
This template provides a structure for creating clear and informative deprecation notices for your API endpoints. Use this template to communicate upcoming changes to your users and guide them through the migration process.
## 1. Endpoint Identification
Clearly identify the API endpoint being deprecated. Provide the full URL, the HTTP method, and a brief description.
**Example:**
* **Endpoint:** `GET /users/{user_id}`
* **Description:** Retrieves user information by ID.
## 2. Deprecation Date
Specify the exact date when the endpoint will be officially deprecated. This date should be clearly visible and easily understandable.
**Example:**
* **Deprecation Date:** 2024-12-31
## 3. Sunset Date (Removal Date)
State the date when the deprecated endpoint will be completely removed and no longer functional. This is crucial for users to plan their migration.
**Example:**
* **Sunset Date:** 2025-06-30
## 4. Reason for Deprecation
Explain the reason behind the deprecation. Be transparent and provide context. This helps users understand the need for the change.
**Examples:**
* "This endpoint is being deprecated in favor of the new `GET /v2/users/{user_id}` endpoint, which offers improved performance and security."
* "This endpoint relies on outdated technology and is being replaced with a more modern and scalable solution."
* "This endpoint is being deprecated due to low usage and maintenance costs."
## 5. Recommended Alternative
Provide a clear and specific alternative to the deprecated endpoint. Include the full URL, HTTP method, and a description of its functionality.
**Example:**
* **Alternative Endpoint:** `GET /v2/users/{user_id}`
* **Description:** Retrieves user information by ID using a more efficient data structure.
## 6. Migration Guide
Provide detailed instructions on how to migrate from the deprecated endpoint to the recommended alternative. This should include code examples, data mapping information, and any other relevant details.
**Example:**
To migrate to the new endpoint, please follow these steps:
1. Replace all instances of `GET /users/{user_id}` with `GET /v2/users/{user_id}`.
2. The response format for the new endpoint is slightly different. The `name` field has been split into `firstName` and `lastName` fields. Update your code accordingly.
* **Old:** `{"id": 123, "name": "John Doe"}`
* **New:** `{"id": 123, "firstName": "John", "lastName": "Doe"}`
3. Ensure you are handling any potential errors returned by the new endpoint.
## 7. Impact of Deprecation
Explain the potential impact of the deprecation on users who continue to use the deprecated endpoint after the deprecation date.
**Examples:**
* "After the deprecation date, this endpoint will continue to function but will no longer receive updates or bug fixes."
* "After the sunset date, this endpoint will return a `410 Gone` error."
## 8. Support and Contact Information
Provide contact information for users who have questions or need assistance with the migration process.
**Example:**
If you have any questions or require assistance with the migration, please contact our support team at [support@example.com](mailto:support@example.com) or visit our documentation at [https://example.com/docs/api-migration](https://example.com/docs/api-migration).
## 9. Versioning Information (Optional)
If your API uses versioning, include information about the API version being deprecated.
**Example:**
* **Affected API Version(s):** v1
## Example Complete Notice
---
**Endpoint:** `POST /orders`
**Description:** Creates a new order.
**Deprecation Date:** 2024-11-15
**Sunset Date:** 2025-05-15
**Reason for Deprecation:** This endpoint is being deprecated due to security vulnerabilities.
**Recommended Alternative:** `POST /v2/orders`
**Description:** Creates a new order using a more secure authentication method.
**Migration Guide:** Please update your code to use the `POST /v2/orders` endpoint. The request body format is the same. You will need to update your authentication headers to use the new API key provided in your account settings.
**Impact of Deprecation:** After 2025-05-15, `POST /orders` will return a `403 Forbidden` error.
**Support and Contact Information:** Contact support@example.com for assistance.
---
**Remember to replace the placeholder information with your specific details.**

122
skills/skill-adapter/assets/migration_guide_template.md Normal file
View File

@@ -0,0 +1,122 @@
# API Migration Guide: [API Name] - Version [Old Version] to Version [New Version]
This document outlines the necessary steps to migrate your application from version [Old Version] to version [New Version] of the [API Name] API. Carefully review these instructions to ensure a smooth and successful transition.
## Introduction
This migration guide provides a detailed overview of the changes introduced in version [New Version] of the [API Name] API and offers step-by-step instructions on how to adapt your application accordingly. We strive to minimize disruption during the upgrade process while introducing new features and improvements.
**Key Changes in Version [New Version]:**
* [Briefly describe key change 1, e.g., New authentication method using OAuth 2.0]
* [Briefly describe key change 2, e.g., Updated response format for the `/users` endpoint]
* [Briefly describe key change 3, e.g., Removal of the `/legacy-endpoint` endpoint]
**Impact:**
[Summarize the overall impact of the changes on existing applications. Will it require significant code changes? Is it mostly additive?]
## Deprecation Notices
The following features or endpoints have been deprecated in version [New Version]:
* **Endpoint:** `/legacy-endpoint` - Use `/new-endpoint` instead. (See "Migration Steps" below)
* **Parameter:** `old_parameter` in `/resource` - Use `new_parameter` instead. This parameter will be removed in version [Future Version].
We strongly recommend migrating away from these deprecated features as soon as possible to avoid future compatibility issues.
## Migration Steps
This section provides detailed instructions on migrating your application to the new version. Follow these steps in order to ensure a successful upgrade.
**1. Update API Client:**
* If you're using a specific API client library, update it to the latest version compatible with version [New Version]. Refer to the client library's documentation for specific upgrade instructions.
**2. Authentication Changes (if applicable):**
* **Old Method:** [Describe the old authentication method, e.g., API keys]
* **New Method:** [Describe the new authentication method, e.g., OAuth 2.0]
* **Action Required:** [Explain how to implement the new authentication method. Include example code snippets if possible. For example:
```
// Old: Using API Key
const apiKey = "[YOUR_API_KEY]";
const response = await fetch("/api/users", {
headers: { "X-API-Key": apiKey }
});
// New: Using OAuth 2.0 Token
const accessToken = await getAccessToken(); // Function to obtain access token
const response = await fetch("/api/users", {
headers: { "Authorization": `Bearer ${accessToken}` }
});
```
]
**3. Endpoint Changes:**
* **`/legacy-endpoint` to `/new-endpoint`:**
* **Old Endpoint:** `/legacy-endpoint`
* **New Endpoint:** `/new-endpoint`
* **Reason for Change:** [Explain why the endpoint was changed, e.g., Improved performance, better data model]
* **Action Required:** Update all calls to `/legacy-endpoint` to use `/new-endpoint`. Note that the response format may have changed. See the "Response Format Changes" section below.
**4. Request Parameter Changes:**
* **`old_parameter` to `new_parameter` in `/resource`:**
* **Old Parameter:** `old_parameter` (Description: [Brief description of the old parameter])
* **New Parameter:** `new_parameter` (Description: [Brief description of the new parameter])
* **Action Required:** Replace all instances of `old_parameter` with `new_parameter`. Ensure the data type is compatible. [Explain any data type conversions needed.]
**5. Response Format Changes:**
* **`/users` Endpoint:**
* **Old Response Format:**
```json
{
"user_id": "123",
"user_name": "John Doe"
}
```
* **New Response Format:**
```json
{
"id": "123",
"name": "John Doe",
"email": "john.doe@example.com"
}
```
* **Action Required:** Update your application to handle the new response format. Specifically, replace references to `user_id` with `id` and `user_name` with `name`. Also, consider utilizing the new `email` field.
**6. Error Handling:**
* The error codes and messages may have changed in version [New Version]. Consult the API documentation for a complete list of error codes and their meanings. [Provide examples of common error code changes].
**7. Testing:**
* Thoroughly test your application after migrating to version [New Version] to ensure that all functionality is working as expected. Pay particular attention to the areas affected by the changes outlined in this guide. Consider using automated testing tools to verify the compatibility of your application with the new API version.
## Backward Compatibility
While we strive to maintain backward compatibility whenever possible, some changes were necessary in version [New Version]. The following aspects are **not** backward compatible:
* [List specific non-backward-compatible aspects, e.g., Authentication method]
* [List specific non-backward-compatible aspects, e.g., The `/legacy-endpoint` endpoint has been completely removed]
## Support and Resources
If you encounter any issues during the migration process, please consult the following resources:
* **API Documentation:** [Link to API documentation]
* **Support Forum:** [Link to support forum]
* **Contact Us:** [Email address or contact form link]
We are committed to providing you with the support you need to successfully migrate to version [New Version] of the [API Name] API.
## Versioning Policy
[Describe the API versioning policy - how long are old versions supported? How are deprecation notices handled? What is the upgrade schedule? Example: We support the current version and the previous two major versions. Deprecated features are announced at least 6 months prior to removal.]
## Conclusion
Migrating to version [New Version] of the [API Name] API will enable you to take advantage of the latest features and improvements. By following the steps outlined in this guide, you can ensure a smooth and successful transition. Thank you for using our API!

28
skills/skill-adapter/assets/skill-schema.json Normal file
View File

@@ -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)"
}
}
}

27
skills/skill-adapter/assets/test-data.json Normal file
View File

@@ -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"
}
}

8
skills/skill-adapter/references/README.md Normal file
View File

@@ -0,0 +1,8 @@
# References
Bundled resources for api-versioning-manager skill
- [ ] api_versioning_strategies.md: Detailed explanation of different API versioning strategies (e.g., URI versioning, header versioning).
- [ ] deprecation_best_practices.md: Best practices for managing API deprecation, including communication strategies.
- [ ] backward_compatibility_guidelines.md: Guidelines for ensuring backward compatibility in API changes.
- [ ] semantic_versioning_spec.md: A copy of the semantic versioning specification for reference.

69
skills/skill-adapter/references/best-practices.md Normal file
View File

@@ -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

70
skills/skill-adapter/references/examples.md Normal file
View File

@@ -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

8
skills/skill-adapter/scripts/README.md Normal file
View File

@@ -0,0 +1,8 @@
# Scripts
Bundled resources for api-versioning-manager skill
- [ ] api_version_bump.py: Automates the process of incrementing API versions in configuration files.
- [ ] deprecation_notice_generator.py: Generates deprecation notices in various formats (e.g., Markdown, JSON).
- [ ] compatibility_test_runner.sh: Executes compatibility tests against different API versions.
- [ ] migration_guide_generator.py: Generates migration guides from one API version to another.

42
skills/skill-adapter/scripts/helper-template.sh Executable file
View File

@@ -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"

32
skills/skill-adapter/scripts/validation.sh Executable file
View File

@@ -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"