Initial commit

skills/skill-adapter/assets/README.md

@@ -0,0 +1,7 @@
+# Assets
+
+Bundled resources for api-cache-manager skill
+
+- [ ] cache_invalidation_template.json: JSON template for cache invalidation requests.
+- [ ] example_redis_config.conf: Example Redis configuration file.
+- [ ] example_http_headers.txt: Example HTTP headers for caching.

skills/skill-adapter/assets/cache_invalidation_template.json

@@ -0,0 +1,37 @@
+{
+  "_comment": "Template for cache invalidation requests.  Use this to build your request to invalidate cached data.",
+  "request_id": "unique_request_id_123",
+  "_comment": "A unique identifier for this invalidation request.  Helps with tracking and auditing.",
+  "cache_type": "redis",
+  "_comment": "The type of cache to invalidate.  Options: 'redis', 'cdn', 'http'.",
+  "target": "key",
+  "_comment": "Specifies what is being targeted for invalidation.  Options: 'key', 'tag', 'all'.",
+  "key": "user:profile:12345",
+  "_comment": "The specific cache key to invalidate (if target is 'key').",
+  "tag": "user_profile",
+  "_comment": "The tag to invalidate (if target is 'tag').  All entries with this tag will be invalidated.",
+  "cdn_provider": "cloudflare",
+  "_comment": "If cache_type is 'cdn', specify the CDN provider. Options: 'cloudflare', 'akamai', 'fastly'.",
+  "cloudflare_zone_id": "your_cloudflare_zone_id",
+  "_comment": "If cache_type is 'cdn' and cdn_provider is 'cloudflare', specify the Cloudflare zone ID.",
+  "akamai_client_token": "your_akamai_client_token",
+  "_comment": "If cache_type is 'cdn' and cdn_provider is 'akamai', specify the Akamai Client Token.",
+  "akamai_client_secret": "your_akamai_client_secret",
+  "_comment": "If cache_type is 'cdn' and cdn_provider is 'akamai', specify the Akamai Client Secret.",
+  "akamai_access_token": "your_akamai_access_token",
+  "_comment": "If cache_type is 'cdn' and cdn_provider is 'akamai', specify the Akamai Access Token.",
+  "fastly_service_id": "your_fastly_service_id",
+  "_comment": "If cache_type is 'cdn' and cdn_provider is 'fastly', specify the Fastly Service ID.",
+  "fastly_api_key": "your_fastly_api_key",
+  "_comment": "If cache_type is 'cdn' and cdn_provider is 'fastly', specify the Fastly API Key.",
+  "http_header": "Cache-Control",
+  "_comment": "If cache_type is 'http', specify the HTTP header to modify.  Typically 'Cache-Control'.",
+  "http_header_value": "no-cache, no-store, must-revalidate",
+  "_comment": "If cache_type is 'http', specify the new value for the HTTP header.  Example: 'no-cache, no-store, must-revalidate'.",
+  "invalidate_all": false,
+  "_comment": "If true, invalidates all entries in the specified cache_type.  Use with caution!",
+  "timestamp": "2024-01-26T12:00:00Z",
+  "_comment": "Timestamp of the invalidation request. Useful for auditing and debugging.",
+  "user": "admin_user",
+  "_comment": "User who initiated the invalidation request."
+}

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/example_http_headers.txt

@@ -0,0 +1,129 @@
+# Example HTTP Headers for API Caching
+
+This document provides example HTTP headers that you can use to implement caching strategies for your API. These headers can be configured on your server to instruct browsers, CDNs, and other caching proxies on how to cache your API responses.
+
+## Cache-Control
+
+The `Cache-Control` header is the primary mechanism for controlling caching behavior. It allows you to specify various directives related to caching.
+
+### Common Directives
+
+*   **`public`**: Indicates that the response can be cached by any cache (e.g., browser, CDN, proxy).
+*   **`private`**: Indicates that the response can only be cached by the user's browser and not by shared caches.
+*   **`max-age=<seconds>`**: Specifies the maximum amount of time (in seconds) that a response is considered fresh. After this time, the cache must revalidate the response with the origin server.  **[Insert your desired cache duration in seconds here]**
+*   **`s-maxage=<seconds>`**: Similar to `max-age`, but specifically for shared caches like CDNs. This overrides `max-age` for shared caches. **[Insert your desired CDN cache duration in seconds here]**
+*   **`no-cache`**:  Forces caches to revalidate the response with the origin server before using it. The cache can still store the response, but it must always check for updates.
+*   **`no-store`**:  Indicates that the response should not be cached at all.
+*   **`must-revalidate`**:  Instructs caches to strictly adhere to the freshness information provided in the response. If a cached response is stale, the cache must revalidate it with the origin server before using it.
+*   **`proxy-revalidate`**:  Similar to `must-revalidate`, but specifically for proxy caches.
+
+### Example Cache-Control Headers
+
+*   **For public caching with a 1 hour (3600 seconds) TTL:**
+
+    ```
+    Cache-Control: public, max-age=3600
+    ```
+
+*   **For private caching with a 5 minute (300 seconds) TTL:**
+
+    ```
+    Cache-Control: private, max-age=300
+    ```
+
+*   **For CDN caching with a 1 day (86400 seconds) TTL and browser caching with 1 hour:**
+
+    ```
+    Cache-Control: public, max-age=3600, s-maxage=86400
+    ```
+
+*   **To force revalidation:**
+
+    ```
+    Cache-Control: no-cache
+    ```
+
+*   **To prevent caching:**
+
+    ```
+    Cache-Control: no-store
+    ```
+
+## Expires
+
+The `Expires` header specifies an absolute date/time after which the response is considered stale.  While still supported, `Cache-Control` is generally preferred as it offers more flexibility.
+
+### Example Expires Header
+
+*   **Expires one week from now:**
+
+    ```
+    Expires: [Insert calculated date/time string for one week from now in HTTP date format (e.g., "Tue, 15 Nov 2024 08:12:31 GMT")]
+    ```
+
+## ETag
+
+The `ETag` header provides a unique identifier for a specific version of a resource.  The server generates this value, and the client can use it in subsequent requests with the `If-None-Match` header to perform conditional requests.
+
+### Usage
+
+1.  The server returns an `ETag` header with the initial response. **[Insert example ETag value here]**
+2.  The client stores the `ETag` value.
+3.  When the client needs to request the same resource again, it includes the `If-None-Match` header with the stored `ETag` value.
+4.  If the resource has not changed since the client last requested it, the server returns a `304 Not Modified` response. If the resource has changed, the server returns the new resource with a new `ETag` value.
+
+### Example ETag Header
+
+```
+ETag: "[Insert generated ETag value here]"
+```
+
+## Last-Modified
+
+The `Last-Modified` header indicates the date and time the resource was last modified on the server. Clients can use this information with the `If-Modified-Since` header to perform conditional requests.
+
+### Usage
+
+1. The server includes the `Last-Modified` header with the initial response. **[Insert Last-Modified date/time string here]**
+2. The client stores the `Last-Modified` value.
+3. When the client needs to request the same resource again, it includes the `If-Modified-Since` header with the stored `Last-Modified` value.
+4. If the resource has not been modified since the client last requested it, the server returns a `304 Not Modified` response. If the resource has been modified, the server returns the new resource with an updated `Last-Modified` value.
+
+### Example Last-Modified Header
+
+```
+Last-Modified: [Insert date/time string in HTTP date format (e.g., "Mon, 14 Nov 2024 10:00:00 GMT")]
+```
+
+## Vary
+
+The `Vary` header specifies the request headers that the server uses to determine which version of a resource to serve. This is important when the server returns different responses based on the client's request headers (e.g., language, user-agent).
+
+### Example Vary Header
+
+*   **Vary based on the `Accept-Language` header:**
+
+    ```
+    Vary: Accept-Language
+    ```
+
+*   **Vary based on the `User-Agent` and `Accept-Encoding` headers:**
+
+    ```
+    Vary: User-Agent, Accept-Encoding
+    ```
+
+*   **Vary on everything (use with caution as it can reduce cache effectiveness):**
+
+    ```
+    Vary: *
+    ```
+
+## Practical Considerations
+
+*   **Balancing Freshness and Validation:** Carefully consider the `max-age` and `s-maxage` values to strike a balance between serving cached content and ensuring that clients receive up-to-date information.
+*   **CDN Configuration:** Configure your CDN to respect the caching headers set by your origin server.  Refer to your CDN provider's documentation for specific instructions.
+*   **Testing:** Thoroughly test your caching configuration to ensure that it is working as expected and that clients are receiving the correct responses. Use browser developer tools or command-line tools like `curl` to inspect the HTTP headers.
+*   **API Design:** Design your API to be cache-friendly. For example, use resource-based URLs and provide appropriate `ETag` or `Last-Modified` headers.
+*   **Invalidation:** Implement a strategy for invalidating cached content when the underlying data changes. This may involve purging the CDN cache or updating the `Cache-Control` headers.
+*   **Dynamic Content:** For dynamic content that cannot be cached, use the `Cache-Control: no-store` header.

skills/skill-adapter/assets/example_redis_config.conf

@@ -0,0 +1,101 @@
+# Example Redis Configuration File
+# This file provides a starting point for configuring Redis for use with the API Cache Manager plugin.
+# Adjust these settings to match your specific Redis deployment and performance requirements.
+
+# --- Basic Configuration ---
+
+# Bind to all interfaces or specify an IP address (e.g., 127.0.0.1) for local access only.
+# bind 127.0.0.1 -::1
+bind 0.0.0.0
+
+# Listen on the default Redis port.  Change if necessary.
+port 6379
+
+# TCP keepalive.
+#
+# If non-zero, use SO_KEEPALIVE to send TCP ACKs to clients in absence
+# of communication. This is useful for two reasons:
+#
+# 1) Detect dead peers.
+# 2) Take advantage of the TCP keepalive period to half close idle
+#    connections if the server wants to reduce resources usage.
+#
+# On Linux, the default keepalive settings are to send probes every
+# 75 seconds, with 9 failed probes before declaring the client dead.
+# This means that a broken connection is only discovered after 11 minutes
+# (75*9).
+#
+# To make connection alive detection more aggressive on Linux, it is
+# recommended to set the following TCP keepalive settings:
+#
+# tcp-keepalive 60
+tcp-keepalive 300
+
+# --- Memory Management ---
+
+# Set the maximum memory Redis will use.  Adjust this based on your available RAM.
+# A good starting point is to allocate around half of your system's RAM to Redis.
+# Ensure you have enough memory for both Redis and your application.
+maxmemory 2gb
+
+# Eviction policy: how Redis will evict keys when it reaches maxmemory.
+# Common policies:
+# - volatile-lru: Evict keys with an expire set using an LRU algorithm.
+# - allkeys-lru: Evict any key using an LRU algorithm.
+# - volatile-ttl: Evict keys with an expire set, with the shortest remaining TTL.
+# - noeviction: Don't evict. Return an error when memory is full.
+maxmemory-policy allkeys-lru
+
+# --- Persistence ---
+
+# Redis offers different persistence options:
+# - RDB (Snapshotting): Saves the dataset to disk periodically.  Good for backups.
+# - AOF (Append Only File): Logs every write operation.  Provides better durability.
+# - Disable Persistence:  Redis will only exist in memory. Data is lost on shutdown.
+
+# RDB Snapshotting configuration
+save 900 1       # Save the DB if 1 key changed in 900 seconds
+save 300 10      # Save the DB if 10 keys changed in 300 seconds
+save 60 10000    # Save the DB if 10000 keys changed in 60 seconds
+
+# AOF configuration (more durable, but can be slower)
+# appendonly yes
+# appendfsync everysec # Recommended for most use cases
+# appendfsync always # Slowest, but safest
+# appendfsync no # Fastest, but least safe (OS decides when to flush)
+
+# --- Security ---
+
+# Require a password for accessing Redis.  Strongly recommended for production.
+# Replace 'YOUR_REDIS_PASSWORD' with a strong, unique password.
+# requirepass YOUR_REDIS_PASSWORD
+
+# Rename potentially dangerous commands.  This is an optional security measure.
+# rename-command FLUSHALL ""
+# rename-command FLUSHDB ""
+# rename-command CONFIG ""
+
+# --- Advanced Configuration ---
+
+# Number of databases. The default is 16.
+# databases 16
+
+# The idle time after which a client connection will be closed.
+# If set to 0, the connection will never be closed.
+# timeout 300
+
+# --- Cluster Configuration (if applicable) ---
+# If you are using Redis Cluster, configure the following:
+# cluster-enabled yes
+# cluster-config-file nodes.conf
+# cluster-node-timeout 15000
+
+# --- Logging ---
+# Specify the log file.  Leave commented to log to stdout.
+# logfile /var/log/redis/redis-server.log
+
+# --- Important Notes ---
+# - Regularly review and adjust these settings based on your application's needs and performance monitoring.
+# - Monitor Redis memory usage and adjust 'maxmemory' accordingly.
+# - Consider using Redis Sentinel or Redis Cluster for high availability.
+# - Secure your Redis instance properly, especially if it's exposed to the internet.

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,7 @@
+# References
+
+Bundled resources for api-cache-manager skill
+
+- [ ] redis_config.md: Documentation on configuring Redis for caching, including connection parameters and best practices.
+- [ ] http_cache_headers.md: Explanation of HTTP caching headers and how to use them effectively.
+- [ ] cdn_integration.md: Guide on integrating the API cache with a CDN for improved performance.

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-cache-manager skill
+
+- [ ] clear_cache.sh: Script to clear the API cache based on different strategies (Redis, HTTP headers).
+- [ ] warm_cache.py: Python script to pre-populate the cache with frequently accessed data.
+- [ ] cache_stats.sh: Script to retrieve and display cache statistics (hit rate, size, etc.).

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"