Initial commit

skills/skill-adapter/assets/README.md

@@ -0,0 +1,6 @@
+# Assets
+
+Bundled resources for api-response-validator skill
+
+- [ ] validation_report_template.html: HTML template for generating validation reports.
+- [ ] error_codes.json: JSON file containing error codes and descriptions.

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/error_codes.json

@@ -0,0 +1,83 @@
+{
+  "_comment": "Error codes and descriptions for the API Response Validator plugin.",
+  "error_codes": [
+    {
+      "code": "SCHEMA_VALIDATION_FAILED",
+      "description": "The API response failed validation against the provided JSON Schema.",
+      "details": {
+        "_comment": "Example details structure.  'errors' will contain schema validation errors.",
+        "errors": [
+          {
+            "dataPath": ".data.id",
+            "schemaPath": "#/properties/id/type",
+            "keyword": "type",
+            "message": "should be string"
+          }
+        ]
+      },
+      "severity": "ERROR",
+      "resolution": "Review the API response and the JSON Schema to identify and correct any discrepancies. Ensure data types and required fields match the schema definition."
+    },
+    {
+      "code": "OPENAPI_VALIDATION_FAILED",
+      "description": "The API response failed validation against the OpenAPI specification.",
+      "details": {
+        "_comment": "Example details structure. 'errors' will contain OpenAPI validation errors.",
+        "errors": [
+          {
+            "message": "Response body does not conform to schema for 200 response."
+          }
+        ],
+        "operationId": "getUserById",
+        "path": "/users/{userId}",
+        "method": "GET"
+      },
+      "severity": "ERROR",
+      "resolution": "Review the API response and the OpenAPI specification to identify and correct any discrepancies.  Check for missing or incorrect data types, required fields, and response codes."
+    },
+    {
+      "code": "CONTRACT_VALIDATION_FAILED",
+      "description": "The API response failed validation against the custom contract rules.",
+      "details": {
+        "_comment": "Example details structure. 'failed_rules' contains information about the failed custom rules.",
+        "failed_rules": [
+          {
+            "rule_name": "response_time_limit",
+            "message": "Response time exceeded the allowed limit of 500ms. Actual time: 750ms",
+            "actual_value": 750,
+            "expected_value": 500
+          }
+        ]
+      },
+      "severity": "WARNING",
+      "resolution": "Review the API response and the custom contract rules to identify and correct any discrepancies. Adjust the rules or the API implementation as needed."
+    },
+    {
+      "code": "MISSING_CONTENT_TYPE",
+      "description": "The API response is missing the 'Content-Type' header.",
+      "details": null,
+      "severity": "WARNING",
+      "resolution": "Ensure the API response includes the 'Content-Type' header to properly identify the response format."
+    },
+    {
+      "code": "INVALID_JSON",
+      "description": "The API response body is not valid JSON.",
+      "details": {
+        "_comment": "Details might include the parsing error message.",
+        "error_message": "Unexpected token '}' at position 10."
+      },
+      "severity": "ERROR",
+      "resolution": "Ensure the API response returns a valid JSON payload. Check for syntax errors and proper formatting."
+    },
+    {
+      "code": "UNEXPECTED_STATUS_CODE",
+      "description": "The API returned an unexpected HTTP status code.",
+      "details": {
+        "expected_status_code": 200,
+        "actual_status_code": 500
+      },
+      "severity": "WARNING",
+      "resolution": "Verify the expected HTTP status code against the actual status code returned by the API. Investigate the API logs for potential errors."
+    }
+  ]
+}

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/assets/validation_report_template.html

@@ -0,0 +1,122 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>API Validation Report</title>
+  <style>
+    /* Inline CSS for styling */
+    body {
+      font-family: sans-serif;
+      line-height: 1.6;
+      margin: 20px;
+      background-color: #f8f9fa; /* Light gray background */
+      color: #343a40; /* Dark gray text */
+    }
+
+    h1 {
+      color: #007bff; /* Primary color for headings */
+      border-bottom: 2px solid #007bff;
+      padding-bottom: 5px;
+      margin-bottom: 20px;
+    }
+
+    h2 {
+      color: #28a745; /* Success color for subheadings */
+      margin-top: 20px;
+    }
+
+    h3 {
+      color: #dc3545; /* Danger color for sub-subheadings */
+      margin-top: 15px;
+    }
+
+    .report-section {
+      margin-bottom: 20px;
+      padding: 15px;
+      border: 1px solid #ced4da; /* Light gray border */
+      border-radius: 5px;
+      background-color: #fff; /* White background */
+    }
+
+    .validation-summary {
+      margin-bottom: 20px;
+      padding: 15px;
+      border: 1px solid #ced4da; /* Light gray border */
+      border-radius: 5px;
+      background-color: #fff; /* White background */
+    }
+
+    .validation-summary p {
+      margin-bottom: 5px;
+    }
+
+    .success {
+      color: #28a745; /* Success color */
+    }
+
+    .failure {
+      color: #dc3545; /* Danger color */
+    }
+
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      margin-top: 10px;
+    }
+
+    th, td {
+      border: 1px solid #dee2e6; /* Lighter gray border for table cells */
+      padding: 8px;
+      text-align: left;
+    }
+
+    th {
+      background-color: #e9ecef; /* Light gray background for table headers */
+    }
+
+    pre {
+      background-color: #f0f0f0; /* Light gray background for code blocks */
+      padding: 10px;
+      overflow-x: auto;
+    }
+
+    /* Responsive design */
+    @media (max-width: 768px) {
+      body {
+        margin: 10px;
+      }
+      table {
+        font-size: 0.8em;
+      }
+    }
+  </style>
+</head>
+<body>
+
+  <h1>API Validation Report</h1>
+
+  <div class="validation-summary">
+    <p><strong>Total Requests:</strong> {{total_requests}}</p>
+    <p class="success"><strong>Successful Validations:</strong> {{successful_validations}}</p>
+    <p class="failure"><strong>Failed Validations:</strong> {{failed_validations}}</p>
+  </div>
+
+  <div class="report-section">
+    <h2>Validation Results</h2>
+    {{validation_results}}
+  </div>
+
+  <div class="report-section">
+    <h2>Detailed Errors</h2>
+    {{detailed_errors}}
+  </div>
+
+  <div class="report-section">
+    <h2>Summary</h2>
+      <p>This report summarizes the API validation results. Please review the details for any failed validations.</p>
+      <p>Report generated at: {{report_generation_time}}</p>
+  </div>
+
+</body>
+</html>

skills/skill-adapter/references/README.md

@@ -0,0 +1,8 @@
+# References
+
+Bundled resources for api-response-validator skill
+
+- [ ] json_schema_example.json: Example JSON schema for API response validation.
+- [ ] openapi_example.yaml: Example OpenAPI specification for API response validation.
+- [ ] custom_rules_example.yaml: Example custom rules configuration file.
+- [ ] api_response_validation_best_practices.md: Best practices for API response validation.

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,7 @@
+# Scripts
+
+Bundled resources for api-response-validator skill
+
+- [ ] validate_json_schema.py: Script to validate API responses against a JSON schema.
+- [ ] validate_openapi.py: Script to validate API responses against an OpenAPI specification.
+- [ ] validate_custom_rules.py: Script to validate API responses against custom rules defined in a configuration file.

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"